Skip to content

AI Gateway

Chat Completions

POST /v1/chat/completions — the OpenAI-compatible chat endpoint of Clipia AI Gateway. Streaming and regular responses, parameters, roles, tools and errors.

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.

POST/v1/chat/completions

Regular response

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)

Response 200

{
  "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. 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].

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)

Event stream

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]

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].

Timeouts and retries

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.

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, 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 tool has its own safe retry via idempotency_key. Chat is subject to the shared rate and concurrency limits.

Request parameters

Prop

Type

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.

Message roles

RoleHow it's handled
systemsystem instruction
developerhandled as system
useruser message
assistanta previous model reply, including one with tool_calls
toola tool call result; requires tool_call_id
anything elsehandled 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.

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.

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}

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.

Legacy format: POST /v1/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 use the OpenAI envelope { "error": { "message", "type", "param", "code" } }, always with Content-Type: application/json and a matching HTTP status.

StatuscodetypeWhen
400invalid_request_errorinvalid_request_errormalformed body: no model, empty messages, invalid JSON schema in response_format
400context_length_exceededinvalid_request_errorthe input exceeds the model's context; checked before anything is charged
400max_tokens_too_largeinvalid_request_errormax_tokens above 200,000; param names the field
400invalid_request_errorinvalid_request_errortemperature/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
401invalid_api_keyinvalid_request_errorthe key is missing, wrong or revoked
402insufficient_quotainsufficient_quotanot enough credits on the balance
402subscription_requiredinsufficient_quotathe model requires an active subscription
402insufficient_quotainsufficient_quotathe key's credit budget for the period is used up — see Rate limits
403insufficient_scope or permission_errorinvalid_request_errorthe key lacks a permission or the request isn't allowed
404model_not_foundinvalid_request_errorunknown or unavailable model
409idempotency_key_reuse or request_in_progressinvalid_request_errorthe same Idempotency-Key with a different body, or a retry while the first request is still running
422model_input_invalidinvalid_request_errorthe model declined the request on content grounds; rephrase the input
429rate_limit_exceeded or concurrency_limit_exceededrate_limit_errorrequest, token or concurrency limit exceeded
500, 502, 503, 504nullapi_errortemporary model failure; retry later
{
  "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.

Errors inside a stream

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:

{
  "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" }
}
codeWhat happened
upstream_errorthe model didn't respond
upstream_timeoutthe model timed out
service_unavailablethe model is temporarily unavailable
empty_responsethe model returned no usable output
incomplete_streamthe model's stream ended early
invalid_structured_outputthe output doesn't match the requested response_format
model_input_invalidthe model declined the request on content grounds
invalid_request_errorthe 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.