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.
/v1/chat/completionsRegular 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
| 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.
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.
| 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 |
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 |
{
"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" }
}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.
Clipia AI Gateway
One OpenAI-compatible API for Claude, GPT, Gemini, DeepSeek and Grok, paid with Clipia credits. Get a key and send your first request in a couple of minutes.
Models & pricing
The Clipia AI Gateway LLM catalog in GET /v1/models and prices in US dollars per 1M input and output tokens — Claude, GPT, Gemini, DeepSeek and Grok.