Chat Completions — Markdown source

Raw Markdown for copying or feeding to AI agents.
> **AI Agents**: Index `/api/llms.txt` | Full EN `/api/llms-full-en.txt` | Full ZH `/api/llms-full-zh.txt` | OpenAPI `/api/openapi.yaml`
> Base URL: `<BASE_URL>/v1`

# Chat Completions

Create a model response for a multi-turn conversation.

```
POST <BASE_URL>/v1/chat/completions
```

> **Protocol note**: OpenAI-**shaped** entry for any sellable catalog model. Client shape and upstream protocol may differ; the gateway translates (e.g. `anthropic/*` → Anthropic Messages). For Claude images use [`/v1/messages`](./messages.md).

## Authentication

Required: `Authorization: Bearer <API_KEY>`

## Request headers

| Header | Required | Description |
|--------|----------|-------------|
| `Authorization` | Yes | Bearer API key |
| `Content-Type` | Yes | `application/json` |
| `Idempotency-Key` | No | Prevents duplicate calls within 24h |
| `Accept-Language` / `X-Locale` | No | Affects localized error messages where applicable |

## Request body

SupaNexus accepts the **OpenAI Chat Completions** JSON shape and reads `model` and `stream`; other fields follow OpenAI-compatible behavior. For multimodal input (`image_url`, and `video_url` as public URLs only), see [Parameters → Multimodal input](./parameters.md).

```json
{
  "model": "deepseek/deepseek-chat",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello!"}
  ],
  "stream": false,
  "temperature": 0.7,
  "max_tokens": 1024
}
```

| Field | Required | Description |
|-------|----------|-------------|
| `model` | Yes | Model id from `GET /v1/models` (e.g. `deepseek/deepseek-chat`) |
| `messages` | Yes | Chat message array (OpenAI format) |
| `stream` | No | `true` for SSE streaming — see [Streaming](./streaming.md) |

## Non-streaming response

Returns OpenAI-compatible JSON. Example shape:

```json
{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "Hello! How can I help?"},
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 2000,
    "completion_tokens": 300,
    "total_tokens": 2300,
    "prompt_tokens_details": {
      "cached_tokens": 1500
    }
  }
}
```

`prompt_tokens_details.cached_tokens` (OpenAI) counts input tokens served from **Prompt Cache**. SupaNexus uses this with [cached input pricing](/help/prompt-cache-pricing) when configured; otherwise all input tokens bill at the **input** rate.

## Usage and Prompt Cache billing

SupaNexus does **not** run Prompt Cache but **reads** cache fields from the response `usage` for billing:

| Provider | Typical field |
|----------|----------------|
| OpenAI | `usage.prompt_tokens_details.cached_tokens` |
| Anthropic | `usage.cache_read_input_tokens` |

Billing (simplified):

```
charge ≈ (prompt_tokens − cached_hit) × input_rate
       + cached_hit × cached_input_rate
       + completion_tokens × output_rate
```

See the [Models marketplace](https://console.supanexus.ai/models) for rates — [Model pricing](./model-pricing.md). Server-side usage records may include `cached_input_tokens`.

## Response headers (SupaNexus)

| Header | Description |
|--------|-------------|
| `X-SNX-Trace-ID` | Unique request id for support |
| `X-SNX-Model` | Model id used for this request |
| `X-SNX-Provider` | Vendor identifier for the inference provider |

## Idempotency

Send `Idempotency-Key: <unique-string>` to deduplicate chat requests within **24 hours** per API key. If the same key was already processed:

- **HTTP 409**
- `error.code`: `duplicate_request`

If `Idempotency-Key` is omitted, SupaNexus may fall back to `X-SNX-Trace-ID`.

## Routing

SupaNexus selects an available service for your model id. If the request cannot be completed, you may receive **502** or **503**.

## Data and privacy

SupaNexus **does not store conversation history across requests** — callers assemble `messages[]` on every call.

| Handling | Description |
|----------|-------------|
| Request body | SupaNexus does **not** persist prompt/completion text by default |
| Usage records | Call time, model, token counts, and billing-related metadata |
| Support | Provide `X-SNX-Trace-ID` when contacting support |

Chat history in the developer console **Text chat** playground lives only in the **current browser session**; SupaNexus does not restore it from the server after refresh or close.

See [Privacy Policy](/privacy) and [Terms of Service](/terms).

## Common errors

| HTTP | Meaning |
|------|---------|
| 400 | Missing `model`, invalid JSON, or illegal `video_url` (not public http(s)) |
| 401 | Authentication failed |
| 413 | Request body exceeds the default **64 MB** |
| 402 | Insufficient account balance (`error.code=402`) |
| 404 | Unknown or unavailable model |
| 408 | Request timeout (default 120s) |
| 409 | Idempotency conflict |
| 429 | Usage quota exceeded |
| 502 | Service temporarily unavailable |
| 503 | Service temporarily unavailable |

See [Errors](./errors.md) for full reference.

## Related

- [Parameters](./parameters.md)
- [Streaming](./streaming.md)
- [Messages (Anthropic)](./messages.md)
- [Model pricing](./model-pricing.md)
- [Response Headers](./response-headers.md)