api/Chat CompletionsPOST
POST /v1/chat/completions
Complete API specification for chat completions, streaming, tool calls, and model fallbacks.
Endpoint Specification
`POST https://unlockedai.net/v1/chat/completions`
Creates a model response for the given conversation history. Standard OpenAI API wire compatibility.
| Parameter | Type | Required | Description |
|---|---|---|---|
| model | string | Yes* | Target model ID or smart alias (`claude-sonnet-5.5`, `auto`, `frontier`). |
| models | string[] | No | Ordered array of fallback models to cascade through upon upstream failure. |
| messages | array | Yes | List of conversation turns (`system`, `user`, `assistant`, `tool`). |
| stream | boolean | No | If true, streams partial message deltas via Server-Sent Events. Default false. |
| temperature | number | No | Sampling temperature between 0.0 and 2.0. Defaults to model standard. |
| max_tokens | integer | No | Upper limit on generated completion tokens (capped at 8,192). |
| top_p | number | No | Nucleus sampling probability mass cutoff between 0.0 and 1.0. |
| tools | array | No | List of tools the model may generate JSON arguments for. |
| tool_choice | string | object | No | Controls tool usage (`auto`, `none`, `required`, or explicit function). |
| response_format | object | No | Enforces structured outputs, e.g. `{"type": "json_object"}`. |
| presence_penalty | number | No | Number between -2.0 and 2.0 penalizing new tokens based on presence. |
| frequency_penalty | number | No | Number between -2.0 and 2.0 penalizing new tokens based on frequency. |
| seed | integer | No | Deterministic sampling integer for reproducible completions. |
HTTP Request Headers
| Header Name | Required | Description |
|---|---|---|
| Authorization | Yes | Bearer token authentication: `Bearer sk-unlocked-...` |
| Content-Type | Yes | Must be `application/json`. |
| HTTP-Referer | No | Optional site URL for client attribution. |
| X-Title | No | Optional client application title. |
Response Payload Schema
{
"id": "gen_8e7f9a2b",
"object": "chat.completion",
"created": 1740000000,
"model": "claude-sonnet-5.5",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "A Raft consensus cluster tolerates up to (N-1)/2 node failures without losing state."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 32,
"completion_tokens": 18,
"total_tokens": 50
}
}Need an Unlocked AI Key or Credits?
Generate secret API keys backed by non-expiring pay-as-you-go credits starting at $5. No monthly minimums.