> For the complete documentation index, see [/llms.txt](/llms.txt).

> Source: /api/chat

# Chat completions API

OpenAPI spec: `./openapi/openapi.yaml`

- `POST /chat/completions`

## Response

**Return values**

Returns a `chat.completion` object, or a streamed sequence of `chat.completion.chunk` objects if the request is streamed.

**The chat completion object**

<table><tbody><tr><td><strong>id</strong> string<br />A unique identifier for the chat completion. Each chunk has the same ID.</td></tr><tr><td><strong>object</strong> string <br />The object type, which is always <code>chat.completion</code></td></tr><tr><td><strong>created</strong> integer<br />The Unix timestamp (in seconds) of when the chat completion was created. Each chunk has the same timestamp.</td></tr><tr><td><strong>model</strong> string<br />A string representing the version of the model being used.</td></tr><tr><td><strong>system\_fingerprint</strong> null <br />This field is not yet available.</td></tr><tr><td><strong>choices</strong> list<br />A list of chat completion choices.</td></tr><tr><td><strong>choices\[].finish\_reason</strong> string<br />The reason the model stopped generating tokens. This will be `stop` if the model hit a natural stop point or a provided stop sequence, `length` if the maximum number of tokens specified in the request was reached.</td></tr><tr><td><strong>choices\[].index</strong> integer <br />The index of the choice in the list of choices.</td></tr><tr><td><strong>choices\[].message</strong> object <br />A chat completion message generated by the model.</td></tr><tr><td><strong>choices\[].message.content</strong> string <br />The contents of the message.</td></tr><tr><td><strong>choices\[].message.reasoning</strong> string or null <br />The visible reasoning text returned by models that expose it when reasoning is enabled. This field is omitted or <code>null</code> otherwise.</td></tr><tr><td><strong>choices\[].message.role</strong> string<br />The role of the author of this message.</td></tr><tr><td><strong>choices\[].message.tool\_calls</strong> list<br />A list of tools selected by model to call.</td></tr><tr><td><strong>choices\[].message.tool\_calls\[].id</strong> string<br />The ID of tool calls.</td></tr><tr><td><strong>choices\[].message.tool\_calls\[].type</strong> string<br />The type of tool.</td></tr><tr><td><strong>choices\[].message.tool\_calls\[].function</strong> object<br />A function object to call.</td></tr><tr><td><strong>choices\[].message.tool\_calls\[].function.name</strong> string<br />The name of function to call.</td></tr><tr><td><strong>choices\[].message.tool\_calls\[].function.arguments</strong> string<br />A JSON input to function.</td></tr><tr><td><strong>choices\[].logprobs</strong> null<br />This field is not yet available.</td></tr><tr><td><strong>usage</strong> object<br />Usage statistics for the completion request.</td></tr><tr><td><strong>usage.completion\_tokens</strong> integer<br />Number of tokens in the generated completion.</td></tr><tr><td><strong>usage.completion\_tokens\_details</strong> object<br />A breakdown of the tokens in the generated completion.</td></tr><tr><td><strong>usage.completion\_tokens\_details.reasoning\_tokens</strong> integer<br />Number of tokens the model used for reasoning. This can be <code>0</code> when reasoning is disabled.</td></tr><tr><td><strong>usage.prompt\_tokens</strong> integer<br />Number of tokens in the prompt.</td></tr><tr><td><strong>usage.total\_tokens</strong> integer<br />Total number of tokens used in the request (prompt + completion).</td></tr></tbody></table>

**The chat completion chunk object**

<table><tbody><tr><td><strong>id</strong> string<br />A unique identifier for the chat completion. Each chunk has the same ID.</td></tr><tr><td><strong>object</strong> string <br />The object type, which is always `chat.completion.chunk`</td></tr><tr><td><strong>created</strong> integer<br />The Unix timestamp (in seconds) of when the chat completion was created. Each chunk has the same timestamp.</td></tr><tr><td><strong>model</strong> string<br />A string representing the version of the model being used.</td></tr><tr><td><strong>system\_fingerprint</strong> null <br />This field is not yet available.</td></tr><tr><td><strong>choices</strong> list<br />A list of chat completion choices.</td></tr><tr><td><strong>choices\[].finish\_reason</strong> string<br />The reason the model stopped generating tokens. This will be `stop` if the model hit a natural stop point or a provided stop sequence, `length` if the maximum number of tokens specified in the request was reached.</td></tr><tr><td><strong>choices\[].index</strong> integer <br />The index of the choice in the list of choices.</td></tr><tr><td><strong>choices\[].delta</strong> object <br />A chat completion message generated by the model.</td></tr><tr><td><strong>choices\[].delta.content</strong> string <br />The contents of the message.</td></tr><tr><td><strong>choices\[].delta.reasoning</strong> string or null <br />A partial segment of visible reasoning text returned by models that expose it. This field is omitted or <code>null</code> for chunks without reasoning text.</td></tr><tr><td><strong>choices\[].delta.role</strong> string or null<br />The role of the author of this message.</td></tr><tr><td><strong>choices\[].delta.tool\_calls</strong> list<br />A list of tools selected by model to call.</td></tr><tr><td><strong>choices\[].delta.tool\_calls\[].id</strong> string<br />The ID of tool calls.</td></tr><tr><td><strong>choices\[].delta.tool\_calls\[].type</strong> string<br />The type of tool.</td></tr><tr><td><strong>choices\[].delta.tool\_calls\[].function</strong> object<br />A function object to call.</td></tr><tr><td><strong>choices\[].delta.tool\_calls\[].function.name</strong> string<br />The name of function to call.</td></tr><tr><td><strong>choices\[].delta.tool\_calls\[].function.arguments</strong> string<br />A JSON input to function.</td></tr><tr><td><strong>choices\[].logprobs</strong> null<br />This field is not yet available.</td></tr></tbody></table>

## Example

### Request

_Request/response examples: chat / request_

### Response

_Request/response examples: chat / response-200_