---
title: Chat Completions
description: POST /v1/chat/completions — the OpenAI-compatible chat endpoint of Clipia AI Gateway. Streaming and regular responses, parameters, roles, tools and errors.
icon: MessageSquare
---

`POST /v1/chat/completions` is the core endpoint of Clipia AI Gateway, compatible with OpenAI Chat Completions. The key needs the `generate` permission, which every key has, so you don't need a separate key for chat. It takes a `messages` array and returns the assistant's response in non-streaming or streaming mode, with support for tool calling and structured output by JSON schema.

<Method name="POST" path="/v1/chat/completions" />

## Regular response

<Tabs items={['Python', 'Node.js', 'cURL']}>
<Tab value="Python">

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["CLIPIA_KEY"],
    base_url="https://api.clipia.ai/v1",
)

resp = client.chat.completions.create(
    model="claude-opus-5-5",
    messages=[
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user", "content": "Tell me three facts about Mars."},
    ],
    max_tokens=512,
)

print(resp.choices[0].message.content)
print(resp.usage)
```

</Tab>
<Tab value="Node.js">

```ts
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.CLIPIA_KEY,
  baseURL: "https://api.clipia.ai/v1",
});

const resp = await client.chat.completions.create({
  model: "claude-opus-5-5",
  messages: [
    { role: "system", content: "You are a concise assistant." },
    { role: "user", content: "Tell me three facts about Mars." },
  ],
  max_tokens: 512,
});

console.log(resp.choices[0].message.content);
```

</Tab>
<Tab value="cURL">

```bash
curl https://api.clipia.ai/v1/chat/completions \
  -H "Authorization: Bearer $CLIPIA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "messages": [
      { "role": "system", "content": "You are a concise assistant." },
      { "role": "user", "content": "Tell me three facts about Mars." }
    ],
    "max_tokens": 512
  }'
```

</Tab>
</Tabs>

**Response `200`**

```json
{
  "id": "chatcmpl-3f9a1c7e2b41",
  "object": "chat.completion",
  "created": 1782300000,
  "model": "claude-opus-5-5",
  "provider": "Clipia",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "1. ...\n2. ...\n3. ..." },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 64,
    "total_tokens": 92,
    "prompt_tokens_details": { "cached_tokens": 0 }
  }
}
```

`usage` is the token spend: `prompt_tokens`, `completion_tokens`, `total_tokens` and `prompt_tokens_details.cached_tokens`; with prompt caching, `cache_read_input_tokens` and `cache_creation_input_tokens` are added. The cost in **credits** is not part of `usage`: look it up by the response `id` with `GET /v1/generation?id=` — see [Key and limits](/en/docs/llm-gateway/account#cost). The response `id` looks like `chatcmpl-…`, and `provider` is always `"Clipia"`. `finish_reason` is normalized to the OpenAI enum: `stop`, `length`, `tool_calls`, `content_filter`.

## Streaming response

Pass `stream: true` — the response arrives incrementally as Server-Sent Events. Each event is a `chat.completion.chunk` with a delta; the stream ends with the literal `data: [DONE]`.

<Tabs items={['Python', 'Node.js', 'cURL']}>
<Tab value="Python">

```python
stream = client.chat.completions.create(
    model="claude-opus-5-5",
    messages=[{"role": "user", "content": "Write a haiku about the sea."}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta
    if delta.content:
        print(delta.content, end="", flush=True)
```

</Tab>
<Tab value="Node.js">

```ts
const stream = await client.chat.completions.create({
  model: "claude-opus-5-5",
  messages: [{ role: "user", content: "Write a haiku about the sea." }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}
```

</Tab>
<Tab value="cURL">

```bash
curl -N https://api.clipia.ai/v1/chat/completions \
  -H "Authorization: Bearer $CLIPIA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "messages": [{ "role": "user", "content": "Write a haiku about the sea." }],
    "stream": true
  }'
```

</Tab>
</Tabs>

**Event stream**

```text
data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1782300000,"model":"claude-opus-5-5","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","model":"claude-opus-5-5","choices":[{"index":0,"delta":{"content":"Waves "},"finish_reason":null}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","model":"claude-opus-5-5","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]
```

<Callout type="info" title="Final usage in a stream">
To receive `usage` while streaming, pass `stream_options: { "include_usage": true }`. An extra chunk with a populated `usage` and an empty `choices: []` is then sent right before `data: [DONE]`.
</Callout>

## Timeouts and retries [#timeouts]

<Callout type="warn" title="Long answers only in a stream">
A long-running non-streaming request can get a `504` at the gateway edge even while the model is still working. For reasoning models, long answers and large `max_tokens`, enable `stream: true` (with `stream_options.include_usage` if you need usage): the stream stays alive while data keeps flowing, and one response is capped at 4 minutes overall. A long pause without a single token also drops the connection.
</Callout>

For a regular (non-streaming) response send an `Idempotency-Key` header — up to 255 characters, for example a UUID v4. A retry with the same key and the same body within 24 hours returns the stored response with the `Idempotent-Replayed: true` header and no second charge; the same key with a different body returns `409 idempotency_key_reuse`, and a retry while the first request is still running returns `409 request_in_progress`. If the first request failed, the key is released. In streaming mode the header is ignored and the stream runs again. Without a key, a retry after a dropped connection or a network failure is a new request and a new charge, and the official `openai` SDK retries twice by default: send the key in the request headers or turn automatic retries off (`max_retries=0` in Python, `maxRetries: 0` in Node.js).

If the connection drops before the response is complete, generation stops: in a stream, once the first chunk has gone out, you pay for what was delivered; before the first chunk and in a regular response the reserve is returned. The cost of a completed request can be checked by its `id` with [`GET /v1/generation`](/en/docs/llm-gateway/account#cost), but you only get the `id` in a response you received; the request log is on the Logs tab of the developer console. The MCP [`chat`](/en/docs/mcp/tools#conditional) tool has its own safe retry via `idempotency_key`. Chat is subject to the shared [rate and concurrency limits](/en/docs/api-reference/rate-limits).

## Request parameters

<TypeTable
  type={{
    model: { type: 'string', description: 'Model identifier, e.g. claude-opus-5-5 (see the GET /v1/models catalog). Required.' },
    messages: { type: 'object[]', description: 'Non-empty conversation history. content is a string or an array of parts. See roles below.' },
    temperature: { type: 'number', description: 'Randomness, 0–2; out of range returns 400. Defaults to the model default.' },
    top_p: { type: 'number', description: 'Nucleus sampling, 0–1; out of range returns 400. An alternative to temperature.' },
    max_completion_tokens: { type: 'integer', description: 'Max tokens in the response. When omitted, the model ceiling applies: top_provider.max_completion_tokens from GET /v1/models. A value above the ceiling is allowed and the reserve follows the requested amount; above 200,000 returns 400 max_tokens_too_large. Wins if both limits are sent.' },
    max_tokens: { type: 'integer', description: 'The older name of the same limit.' },
    stream: { type: 'boolean', description: 'true — streaming response (SSE). Defaults to false.' },
    stream_options: { type: 'object', description: '{ include_usage: true } — add a final usage chunk to the stream.' },
    stop: { type: 'string | string[]', description: 'Stop sequences.' },
    seed: { type: 'integer', description: 'Requests determinism where the model supports it.' },
    presence_penalty: { type: 'number', description: 'Penalty for repeating topics, −2…2.' },
    frequency_penalty: { type: 'number', description: 'Penalty for repeating tokens, −2…2.' },
    reasoning_effort: { type: 'string', description: 'Reasoning depth: minimal, none and low map to fast; medium to balanced; high and xhigh to deep. Can also be sent as reasoning: { effort }.' },
    response_format: { type: 'object', description: '{ type: "json_object" } or { type: "json_schema", json_schema: {...} } — structured output.' },
    tools: { type: 'object[]', description: 'Descriptions of functions the model may call. Total size up to 256 KB.' },
    tool_choice: { type: 'string | object', description: 'auto | none | required | { type: "function", function: { name } }.' },
    user: { type: 'string', description: 'Stable end-user identifier.' },
  }}
/>

<Callout type="info" title="Parameter compatibility">
You always get a single choice: `n` is accepted only as 1, any other value returns `400`. The fields `parallel_tool_calls`, `logprobs`, `top_logprobs`, `logit_bias`, `service_tier` and `metadata` are accepted but don't affect the response. Unknown top-level fields don't cause a `400` either, so code written for OpenAI ports over unchanged.

Parameter support depends on the model: check `supported_parameters` in `GET /v1/models`. Current models may ignore `temperature`, `top_p` and repetition penalties. DeepSeek V4.1 Flash does not call tools. For strict JSON-schema output, choose a model with `response_format`, such as GPT-6.1 Sol. Claude 5.5 follows structured-output instructions without guaranteeing strict schema conformance.
</Callout>

## Message roles [#roles]

| Role | How it's handled |
| --- | --- |
| `system` | system instruction |
| `developer` | handled as `system` |
| `user` | user message |
| `assistant` | a previous model reply, including one with `tool_calls` |
| `tool` | a tool call result; requires `tool_call_id` |
| anything else | handled as `user` |

An empty `messages` array, a message without a string `role`, or a request without `model` returns `400 invalid_request_error`.

## Tool calling

Full cycle: you describe tools in `tools`, the model returns `tool_calls`, you run the function on your side and send the result back as a message with `role: "tool"`, after which the model produces the final answer.

```python
import json

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Current weather in a city",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "City name"},
                },
                "required": ["city"],
            },
        },
    }
]

messages = [{"role": "user", "content": "What's the weather in Moscow right now?"}]

# 1) The model decides to call a tool
resp = client.chat.completions.create(
    model="claude-opus-5-5", messages=messages, tools=tools,
)
msg = resp.choices[0].message
# resp.choices[0].finish_reason == "tool_calls"

# 2) Run the function on your side
call = msg.tool_calls[0]
args = json.loads(call.function.arguments)   # {"city": "Moscow"}
result = {"temp_c": 14, "condition": "cloudy"}

# 3) Send the result back and get the final answer
messages.append(msg)  # assistant echo with tool_calls
messages.append({
    "role": "tool",
    "tool_call_id": call.id,
    "content": json.dumps(result),
})

final = client.chat.completions.create(
    model="claude-opus-5-5", messages=messages, tools=tools,
)
print(final.choices[0].message.content)
```

When streaming, `tool_calls` fragments arrive grouped by `index`: the function name and `id` come in the first delta for that index, then `function.arguments` fragments you concatenate into valid JSON. A completed tool call is marked with `finish_reason: "tool_calls"`.

## Structured outputs

To force a response that matches a JSON schema, pass `response_format` with `type: "json_schema"` and `strict: true`.

```python
resp = client.chat.completions.create(
    model="gpt-6.1-sol",
    messages=[{"role": "user", "content": "Extract name and age: Anna is 30."}],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "person",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "age": {"type": "integer"},
                },
                "required": ["name", "age"],
                "additionalProperties": False,
            },
        },
    },
)

print(resp.choices[0].message.content)  # {"name": "Anna", "age": 30}
```

<Callout type="info" title="json_object vs json_schema">
`response_format: { "type": "json_object" }` guarantees valid JSON but without a specific schema — and requires the word "json" to appear in `messages`. For strict structural conformance use `json_schema` with `strict: true`. In a stream the schema is checked after the full answer: on a mismatch the last chunk carries an `invalid_structured_output` error and no credits are charged, but text you have already received can't be recalled.
</Callout>

## Legacy format: `POST /v1/completions` [#legacy-completions]

For clients of the old text-completion format (for example, LangChain's `OpenAI` class instead of `ChatOpenAI`) there is `POST /v1/completions`: the `prompt` string becomes the single user message, the response comes back as a `text_completion` with the text in `choices[].text`, and the identifier is `cmpl-…`. Models, prices, streaming, limits and errors are the same as for `/v1/chat/completions`.

## Errors [#errors]

Errors use the OpenAI envelope `{ "error": { "message", "type", "param", "code" } }`, always with `Content-Type: application/json` and a matching HTTP status.

| Status | `code` | `type` | When |
|--------|--------|--------|------|
| `400` | `invalid_request_error` | `invalid_request_error` | malformed body: no `model`, empty `messages`, invalid JSON schema in `response_format` |
| `400` | `context_length_exceeded` | `invalid_request_error` | the input exceeds the model's context; checked before anything is charged |
| `400` | `max_tokens_too_large` | `invalid_request_error` | `max_tokens` above 200,000; `param` names the field |
| `400` | `invalid_request_error` | `invalid_request_error` | `temperature`/`top_p` out of range, `n` other than 1, `tools` over 256 KB, or the model rejected the request parameters; checked before anything is charged |
| `401` | `invalid_api_key` | `invalid_request_error` | the key is missing, wrong or revoked |
| `402` | `insufficient_quota` | `insufficient_quota` | not enough credits on the balance |
| `402` | `subscription_required` | `insufficient_quota` | the model requires an active subscription |
| `402` | `insufficient_quota` | `insufficient_quota` | the key's credit budget for the period is used up — see [Rate limits](/en/docs/api-reference/rate-limits) |
| `403` | `insufficient_scope` or `permission_error` | `invalid_request_error` | the key lacks a permission or the request isn't allowed |
| `404` | `model_not_found` | `invalid_request_error` | unknown or unavailable `model` |
| `409` | `idempotency_key_reuse` or `request_in_progress` | `invalid_request_error` | the same `Idempotency-Key` with a different body, or a retry while the first request is still running |
| `422` | `model_input_invalid` | `invalid_request_error` | the model declined the request on content grounds; rephrase the input |
| `429` | `rate_limit_exceeded` or `concurrency_limit_exceeded` | `rate_limit_error` | request, token or concurrency limit exceeded |
| `500`, `502`, `503`, `504` | `null` | `api_error` | temporary model failure; retry later |

```json
{
  "error": {
    "message": "Insufficient credits. Please top up your balance.",
    "type": "insufficient_quota",
    "param": null,
    "code": "insufficient_quota"
  }
}
```

For `5xx` errors the message is always generic: "The upstream model is temporarily unavailable. Please retry." for `502`, `503` and `504`, and "An internal error occurred. Please retry or contact support." for `500`. A `504` from the gateway edge is a separate case: it arrives when a long non-streaming response did not arrive in time, and its body comes from the proxy, so it may not be in OpenAI format — see [Timeouts and retries](#timeouts).

### Errors inside a stream [#stream-errors]

If a failure happens after the stream has started, the HTTP status is already `200`. In that case the last chunk before `data: [DONE]` carries `finish_reason: "error"` and an `error` object:

```json
{
  "id": "chatcmpl-...",
  "object": "chat.completion.chunk",
  "choices": [{ "index": 0, "delta": {}, "finish_reason": "error" }],
  "error": { "message": "The model timed out. Please retry.", "code": "upstream_timeout", "type": "api_error" }
}
```

| `code` | What happened |
| --- | --- |
| `upstream_error` | the model didn't respond |
| `upstream_timeout` | the model timed out |
| `service_unavailable` | the model is temporarily unavailable |
| `empty_response` | the model returned no usable output |
| `incomplete_stream` | the model's stream ended early |
| `invalid_structured_output` | the output doesn't match the requested `response_format` |
| `model_input_invalid` | the model declined the request on content grounds |
| `invalid_request_error` | the model rejected the request parameters; such a chunk has `type` `invalid_request_error` |

Check `finish_reason` on the last chunk: OpenAI SDK clients don't always turn such a chunk into an exception. Text delivered before the failure is charged in credits; if nothing was delivered, the reservation is returned. Errors that happen before the stream starts, such as `402` or `404`, come back as regular JSON with an HTTP status.
