> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aireserve.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Dedicated GPU endpoints

> Call organization-owned HuggingFace GPU deployments through AI Reserve with your existing API key.

AI Reserve can provision a dedicated HuggingFace Inference Endpoint and bill
its GPU capacity hourly from your organization's wallet. Running vLLM
text-generation deployments are exposed through the AI Reserve gateway, so
you use an existing organization API key — the HuggingFace account credential
stays server-side and is never revealed.

## Call a deployment

Open **Admin → GPUs** for your organization and choose **How to call endpoint**
on a running vLLM deployment. The panel gives you the deployment-specific URL
and a copyable request.

```bash theme={"dark"}
export AIRESERVE_API_KEY="aireserve_api_..."

curl https://api.aireserve.com/v1/gpu/<deployment-id>/chat/completions \
  -H "Authorization: Bearer $AIRESERVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen2.5-7B-Instruct",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
```

The route accepts the OpenAI Chat Completions request and response format,
including `stream: true`. The `model` field is optional. If supplied, AI
Reserve pins it to the repository actually deployed, so a request cannot use
one deployment URL to target another model. On streaming requests AI Reserve
sets `stream_options.include_usage` on your behalf (overriding an explicit
`false`) so the final chunk always carries token counts for usage attribution.

<Note>
  The path contains the deployment's internal ID. Copy the complete URL from the GPUs page rather than constructing it
  from the HuggingFace endpoint name.
</Note>

## Authentication and access

* Send an active AI Reserve API key belonging to the same organization as the
  deployment.
* User-scoped and team-scoped keys can call their organization's deployment;
  normal key status, IP allowlist, organization IP blocklist, geographic, and
  API rate-limit controls still apply.
* **Spend-based gates do not apply to this route.** GPU capacity is prepaid
  hourly from the organization wallet and inference requests add no per-token
  spend, so the checks that meter token spend — organization wallet balance,
  per-user and per-team budget caps, and the Cognition Token balance gate —
  are intentionally not evaluated here. A principal over its budget cap can
  still call a running deployment. To restrict who can drive a deployment,
  pause or revoke keys, scope the key's IP allowlist, or use the organization
  IP blocklist; to stop the spending itself, pause the deployment.
* A key from another organization receives the same `404` as an unknown
  deployment. The API never confirms that another organization's deployment
  exists.
* Paused, failed, deleted, provisioning, externally drifted, and legacy
  HuggingFace-toolkit deployments cannot serve this OpenAI-compatible route.

AI Reserve replaces the inbound authorization header before forwarding to
HuggingFace. The account-wide `HF_TOKEN`, raw HuggingFace URL, and deployment
management APIs are never exposed to the caller.

## Billing and usage

GPU capacity is prepaid hourly when the deployment starts and while it remains
running. **Inference requests are not charged by token on top of that hourly
rate.** Requests still record model, API key/user/team attribution, token
counts when the vLLM response supplies them, latency, and success/error status
at `$0` request cost.

Running endpoints bill continuously, including idle time. Pause a deployment
to stop future hourly charges; the unused remainder of the current prepaid
hour is not refunded.

## Supported protocol

The managed gateway currently promises:

* `POST /v1/gpu/<deployment-id>/chat/completions`
* OpenAI-compatible JSON responses
* OpenAI-compatible SSE streaming
* vLLM text-generation deployments only

Direct HuggingFace URLs, `/v1/models`, completions, embeddings, and generic
HuggingFace-toolkit task routes are not part of this managed customer API.