Create Chat Completion
Create a chat completion.
Generates a model response for the given conversation and configuration. Supports OpenAI-compatible parameters and provider-specific extensions.
Headers:
- Authorization: bearer key for the calling account.
- Optional BYOK or provider headers if applicable.
Behavior:
- If multiple models are supplied, the first one is used, and the agent may hand off to another model.
- Tools may be invoked on the server or signaled for the client to run.
- Streaming responses emit incremental deltas; non-streaming returns a single object.
- Usage metrics are computed when available and returned in the response.
Responses:
- 200 OK: JSON completion object with choices, message content, and usage.
- 400 Bad Request: validation error.
- 401 Unauthorized: authentication failed.
- 402 Payment Required or 429 Too Many Requests: quota, balance, or rate limit issue.
- 500 Internal Server Error: unexpected failure.
Billing:
- Token usage metered by the selected model(s).
- Tool calls and MCP sessions may be billed separately.
- Streaming is settled after the stream ends via an async task.
Example (non-streaming HTTP): POST /v1/chat/completions Content-Type: application/json Authorization: Bearer <key>
{ "model": "provider/model-name", "messages": [{"role": "user", "content": "Hello"}] }
200 OK { "id": "cmpl_123", "object": "chat.completion", "choices": [ {"index": 0, "message": {"role": "assistant", "content": "Hi there!"}, "finish_reason": "stop"} ], "usage": {"prompt_tokens": 3, "completion_tokens": 4, "total_tokens": 7} }
Example (streaming over SSE): POST /v1/chat/completions Accept: text/event-stream
data: {"id":"cmpl_123","choices":[{"index":0,"delta":{"content":"Hi"}}]} data: {"id":"cmpl_123","choices":[{"index":0,"delta":{"content":" there!"}}]} data: [DONE]
Request body
Example request
{
"model_attributes": {
"gpt-5": {
"accuracy": 0.95,
"speed": 0.6
}
},
"agent_attributes": {
"accuracy": 0.9,
"complexity": 0.8
},
"max_turns": 5
}Response
JSON or SSE stream of ChatCompletionChunk events
Example response
{
"choices": [
{
"finish_reason": "stop",
"index": 0,
"message": {
"content": "The next Warriors game is tomorrow at 7:30 PM.",
"role": "assistant"
}
}
],
"created": 1677652288,
"id": "chatcmpl-123",
"model": "gpt-4o-mini",
"object": "chat.completion",
"tools_executed": [
"search_events",
"get_event_details"
],
"usage": {
"completion_tokens": 12,
"prompt_tokens": 9,
"total_tokens": 21
}
}