# Create chat completion

> Creates a model response for the given conversation. Set `stream: true` to receive the response as a stream of server-sent events. The last chunk before `data: [DONE]` carries the `usage` object on every stream, whether or not `stream_options.include_usage` is set. An error after the stream has started (the API commits a stream that the model has not answered within 2 seconds, and keeps it alive with `: ping` comment lines) arrives as a final `data:` event whose JSON has an `error` member, the usual error object, followed by `data: [DONE]`; see the [streaming guide](https://docs.serenityedge.ai/docs/streaming#errors-during-a-stream).

Source: https://docs.serenityedge.ai/docs/api/edge/create-chat-completion/

`POST https://api.serenityedge.ai/v1/chat/completions`

Creates a model response for the given conversation. Set `stream: true` to receive the response as a stream of server-sent events. The last chunk before `data: [DONE]` carries the `usage` object on every stream, whether or not `stream_options.include_usage` is set. An error after the stream has started (the API commits a stream that the model has not answered within 2 seconds, and keeps it alive with `: ping` comment lines) arrives as a final `data:` event whose JSON has an `error` member, the usual error object, followed by `data: [DONE]`; see the [streaming guide](https://docs.serenityedge.ai/docs/streaming#errors-during-a-stream).

## Request body (`application/json`)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `model` | string | yes | Id of the model to use. See the list of models for the available ids. |
| `messages` | array of one of SystemMessage (object), UserMessage (object), AssistantMessage (object), ToolMessage (object) | yes | The conversation so far, oldest first. At least 1 item. |
| `messages[] (SystemMessage).role` | string | yes | Always `system`. |
| `messages[] (SystemMessage).content` | string | yes | Instructions that steer the behaviour of the model. |
| `messages[] (SystemMessage).name` | string | no | Optional name of the participant. |
| `messages[] (UserMessage).role` | string | yes | Always `user`. |
| `messages[] (UserMessage).content` | one of string, array of one of TextContentPart (object), ImageContentPart (object) | yes | The message, as a plain string or as an array of text and image parts (up to the model's limit of 1 to 8 images per request, `references.max` in `GET /v1/models`; base64 data URLs only; image URLs are refused with 400). |
| `messages[] (UserMessage).name` | string | no | Optional name of the participant. |
| `messages[] (AssistantMessage).role` | string | yes | Always `assistant`. |
| `messages[] (AssistantMessage).content` | string or null | no | The text of the message. `null` when the message only carries tool calls. |
| `messages[] (AssistantMessage).tool_calls` | array of ToolCall (object) | no | Tool calls the model made in a previous turn. |
| `messages[] (AssistantMessage).tool_calls[].id` | string | yes | Identifier to echo back in the `tool_call_id` of the tool message. |
| `messages[] (AssistantMessage).tool_calls[].type` | string | yes | Always `function`. |
| `messages[] (AssistantMessage).tool_calls[].function` | object | yes |  |
| `messages[] (AssistantMessage).tool_calls[].function.name` | string | yes |  |
| `messages[] (AssistantMessage).tool_calls[].function.arguments` | string | yes | JSON-encoded arguments. Always validate before use. |
| `messages[] (AssistantMessage).name` | string | no | Optional name of the participant. |
| `messages[] (ToolMessage).role` | string | yes | Always `tool`. |
| `messages[] (ToolMessage).content` | string | yes | The result returned by your function, as a string (usually JSON). |
| `messages[] (ToolMessage).tool_call_id` | string | yes | The `id` of the tool call this message answers. |
| `stream` | boolean | no | If `true`, partial deltas are sent as server-sent events. The stream ends with `data: [DONE]`. Default `false`. |
| `stream_options` | StreamOptions (object) | no | Options that only apply when `stream` is `true`. |
| `stream_options.include_usage` | boolean | no | Accepted for compatibility; the usage chunk is sent on every stream whatever its value. It is the last chunk before `data: [DONE]`: its `usage` object carries the token counts, and its `choices` holds one choice with an empty `delta`. |
| `max_tokens` | integer | no | Upper bound on the number of tokens to generate. Each model's maximum output is the `max_length` of its text output modality in `GET /v1/models` (8,192 tokens on `paddleocr-vl-1.6`); a larger value is lowered to it rather than refused. At least 1. At most 32768. |
| `temperature` | number | no | Sampling temperature. Lower values make the output more deterministic. Default `1`. At least 0. At most 2. |
| `top_p` | number | no | Nucleus sampling: only tokens within the top `top_p` probability mass are considered. Default `1`. At least 0. At most 1. |
| `n` | integer | no | Number of completions to generate for each request. Default `1`. At least 1. |
| `stop` | one of string, array of string | no | Up to four sequences at which generation stops. |
| `presence_penalty` | number | no | Penalises tokens that already appear in the text so far. Default `0`. At least -2. At most 2. |
| `frequency_penalty` | number | no | Penalises tokens in proportion to how often they already appear. Default `0`. At least -2. At most 2. |
| `seed` | integer | no | Best-effort deterministic sampling. Repeated requests with the same seed and parameters aim to return the same result. |
| `tools` | array of Tool (object) | no | Functions the model may call. See the tool calling guide. |
| `tools[].type` | string | yes | Always `function`. |
| `tools[].function` | FunctionDefinition (object) | yes |  |
| `tools[].function.name` | string | yes | Function name. Letters, digits, underscores and dashes; at most 64 characters. |
| `tools[].function.description` | string | no | What the function does. The model uses it to decide when to call the function. |
| `tools[].function.parameters` | object | no | JSON Schema object describing the arguments. |
| `tools[].function.strict` | boolean | no | When `true`, the arguments are guaranteed to match `parameters` exactly. Default `false`. |
| `tool_choice` | one of string, object | no | Controls whether and which tool the model calls. `none` disables tools, `auto` lets the model decide, `required` forces at least one call, and an object forces a specific function. |
| `tool_choice.type` | string | yes | Always `function`. |
| `tool_choice.function` | object | yes |  |
| `tool_choice.function.name` | string | yes |  |
| `parallel_tool_calls` | boolean | no | Whether the model may return several tool calls in one response. Default `true`. |
| `response_format` | one of object, object, object | no | Format of the output. `text` (default), `json_object` for any valid JSON, or `json_schema` to constrain the output to a schema. |
| `response_format (Text).type` | string | yes | Always `text`. |
| `response_format (JSON object).type` | string | yes | Always `json_object`. |
| `response_format (JSON schema).type` | string | yes | Always `json_schema`. |
| `response_format (JSON schema).json_schema` | JsonSchemaFormat (object) | yes |  |
| `response_format (JSON schema).json_schema.name` | string | yes | Name of the schema. |
| `response_format (JSON schema).json_schema.description` | string | no |  |
| `response_format (JSON schema).json_schema.schema` | object | yes | A JSON Schema object the output must satisfy. |
| `response_format (JSON schema).json_schema.strict` | boolean | no | When `true`, the output is guaranteed to match the schema exactly. Default `false`. |
| `reasoning` | ReasoningOptions (object) | no | Reasoning settings for models that support it. Reasoning is off unless the request asks for it. Reasoning tokens are billed as output tokens. See [Reasoning](https://docs.serenityedge.ai/docs/models#reasoning). |
| `reasoning.effort` | string | no | `none` (default) and `minimal` turn reasoning off; `low`, `medium`, `high` and `xhigh` turn it on, from the least to the most reasoning on a model with levels (`high` and `xhigh` are the same level); on a model without levels any of the four turns reasoning on in the same way. The models guide lists the levels of each model. Any other value is ignored. One of `none`, `minimal`, `low`, `medium`, `high`, `xhigh`. |
| `reasoning.enabled` | boolean | no | Without an `effort`, `true` turns reasoning on at the model's highest level and `false` leaves it off. |
| `reasoning.max_tokens` | integer | no | Without an `effort`, a value above 0 turns reasoning on at the model's highest level. It is not a token budget. |
| `reasoning.exclude` | boolean | no | When `true`, the model reasons but the reasoning text is not returned. Default `false`. |
| `reasoning_effort` | string | no | The same as `reasoning.effort`, which wins when both are sent. One of `none`, `minimal`, `low`, `medium`, `high`, `xhigh`. |
| `cache_salt` | string or null | no | A scope inside your API key's prompt cache. Requests of the same key with the same `cache_salt` share cached prefixes; requests with different values, or without one, do not; two keys never share a cache. Without it (or with `null`) the request uses the key's own cache. 1 to 128 characters without `@`, `/`, `\` or NUL, otherwise HTTP 400 with `param: "cache_salt"`. Not logged and not returned. See [Cached input](https://docs.serenityedge.ai/docs/pricing-and-limits#cached-input). At most 128 characters. |
| `user` | string | no | An opaque identifier for your end user, useful for abuse detection on your side. Not stored beyond the request metadata retention period. |

Example:

```json
{
  "model": "orion-pro",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": "Summarise the benefits of EU data residency in two sentences."
    }
  ]
}
```

## Responses

### 200: A chat completion. When `stream` is `true` the body is a `text/event-stream` of `ChatCompletionChunk` objects terminated by `data: [DONE]`.

Body (`application/json`): `ChatCompletion`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | Unique identifier of the completion. |
| `object` | string | yes | Always `chat.completion`. |
| `created` | integer | yes | Unix timestamp (seconds) of creation. |
| `model` | string | yes | The model that generated the response. |
| `choices` | array of ChatCompletionChoice (object) | yes |  |
| `choices[].index` | integer | yes |  |
| `choices[].message` | AssistantResponseMessage (object) | yes |  |
| `choices[].message.role` | string | yes | Always `assistant`. |
| `choices[].message.content` | string or null | no | The generated text, or `null` when the response only carries tool calls. |
| `choices[].message.tool_calls` | array of ToolCall (object) | no |  |
| `choices[].message.tool_calls[].id` | string | yes | Identifier to echo back in the `tool_call_id` of the tool message. |
| `choices[].message.tool_calls[].type` | string | yes | Always `function`. |
| `choices[].message.tool_calls[].function` | object | yes |  |
| `choices[].message.tool_calls[].function.name` | string | yes |  |
| `choices[].message.tool_calls[].function.arguments` | string | yes | JSON-encoded arguments. Always validate before use. |
| `choices[].message.reasoning` | string or null | no | Reasoning text, when the request enabled reasoning and did not exclude it. |
| `choices[].finish_reason` | FinishReason (string or null) | yes | `stop`: natural end or stop sequence. `length`: `max_tokens` or the context window was reached. `tool_calls`: the model wants to call a tool. `content_filter`: output was withheld. `null` in streaming chunks that are not the last one. One of `stop`, `length`, `tool_calls`, `content_filter`, `null`. |
| `usage` | Usage (object) | no |  |
| `usage.prompt_tokens` | integer | yes | Tokens in the prompt, including cached tokens. |
| `usage.completion_tokens` | integer | yes | Tokens generated, including reasoning tokens. |
| `usage.total_tokens` | integer | yes |  |
| `usage.prompt_tokens_details` | object | no |  |
| `usage.prompt_tokens_details.cached_tokens` | integer | no | Prompt tokens served from the prompt cache, billed at the cached input price. |
| `usage.completion_tokens_details` | object | no |  |
| `usage.completion_tokens_details.reasoning_tokens` | integer | no | Tokens spent on reasoning. |
| `usage.cost` | number | no | Streamed chat completions only, in the final usage chunk, on a Serenity Edge API key: an estimate of the request's price in US dollars at the published prices, with cached tokens at the cached input price. It ignores contract rates and discounts, so it is informational and not the bill, which is computed from the token counts. Absent from non-streamed answers and from the Responses API. |
| `system_fingerprint` | string | no | Identifier of the backend configuration that served the request. |

Body (`text/event-stream`): `ChatCompletionChunk`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | Same for every chunk of one completion. |
| `object` | string | yes | Always `chat.completion.chunk`. |
| `created` | integer | yes |  |
| `model` | string | yes |  |
| `choices` | array of ChatCompletionChunkChoice (object) | yes | In the final usage chunk, one choice with an empty `delta` and no `finish_reason` (not an empty array): find the usage chunk by its `usage` object. |
| `choices[].index` | integer | yes |  |
| `choices[].delta` | ChatCompletionDelta (object) | yes | The incremental change carried by this chunk. Concatenate `content` across chunks to rebuild the message. |
| `choices[].delta.role` | string | no | Present in the first chunk only. Always `assistant`. |
| `choices[].delta.content` | string or null | no |  |
| `choices[].delta.reasoning` | string or null | no |  |
| `choices[].delta.tool_calls` | array of ToolCallDelta (object) | no | Tool call fragments. Match fragments by `index` and concatenate `function.arguments`. |
| `choices[].delta.tool_calls[].index` | integer | yes |  |
| `choices[].delta.tool_calls[].id` | string | no | Present in the first fragment of each tool call. |
| `choices[].delta.tool_calls[].type` | string | no | Always `function`. |
| `choices[].delta.tool_calls[].function` | object | no |  |
| `choices[].delta.tool_calls[].function.name` | string | no | Present in the first fragment of each tool call. |
| `choices[].delta.tool_calls[].function.arguments` | string | no | A fragment of the JSON-encoded arguments. |
| `choices[].finish_reason` | FinishReason (string or null) | no | `stop`: natural end or stop sequence. `length`: `max_tokens` or the context window was reached. `tool_calls`: the model wants to call a tool. `content_filter`: output was withheld. `null` in streaming chunks that are not the last one. One of `stop`, `length`, `tool_calls`, `content_filter`, `null`. |
| `usage` | one of Usage (object), null | no | Present only in the final chunk before `data: [DONE]`, which every stream sends; `null` or absent in the other chunks. |
| `usage (Usage).prompt_tokens` | integer | yes | Tokens in the prompt, including cached tokens. |
| `usage (Usage).completion_tokens` | integer | yes | Tokens generated, including reasoning tokens. |
| `usage (Usage).total_tokens` | integer | yes |  |
| `usage (Usage).prompt_tokens_details` | object | no |  |
| `usage (Usage).prompt_tokens_details.cached_tokens` | integer | no | Prompt tokens served from the prompt cache, billed at the cached input price. |
| `usage (Usage).completion_tokens_details` | object | no |  |
| `usage (Usage).completion_tokens_details.reasoning_tokens` | integer | no | Tokens spent on reasoning. |
| `usage (Usage).cost` | number | no | Streamed chat completions only, in the final usage chunk, on a Serenity Edge API key: an estimate of the request's price in US dollars at the published prices, with cached tokens at the cached input price. It ignores contract rates and discounts, so it is informational and not the bill, which is computed from the token counts. Absent from non-streamed answers and from the Responses API. |

### 400: The request is malformed or a parameter is invalid. More images than the model reads, counted over the whole conversation (from 1 to 8 depending on the model: `references.max` in `GET /v1/models`), are refused with `code: too_many_images` and `param: messages`. Two function tools with the same name in `tools` (compared exactly, letter case included) are refused with `param` pointing at the second one, such as `tools[1].function.name`.

Body (`application/json`): `ErrorResponse`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | Error (object) | yes | OpenAI-style error object. |
| `error.message` | string | yes | Human-readable description of the problem. |
| `error.type` | string | yes | Error category. One of `invalid_request_error`, `authentication_error`, `permission_error`, `not_found_error`, `rate_limit_error`, `server_error`. |
| `error.code` | string or null | no | Machine-readable error code, when available. |
| `error.param` | string or null | no | The request parameter the error refers to, when applicable. |

### 401: Missing or invalid API key.

Body (`application/json`): `ErrorResponse`, the same fields as under 400.

### 404: The requested model does not exist or is not available to this key.

Body (`application/json`): `ErrorResponse`, the same fields as under 400.

### 413: The request body is larger than the gateway accepts (4 MB).

Body (`application/json`): `ErrorResponse`, the same fields as under 400.

### 429: Rate limit exceeded, or the service is temporarily at capacity for this model. Wait for the number of seconds in the `Retry-After` header before retrying.

Header `Retry-After`: Seconds to wait before retrying.

Body (`application/json`): `ErrorResponse`, the same fields as under 400.

### 500: Unexpected server error: the model service returned an unexpected response (`upstream_error`), the request got no answer within 600 seconds (`timeout`), or an error in the gateway. Retry with backoff.

Body (`application/json`): `ErrorResponse`, the same fields as under 400.

### 503: The model service is temporarily unavailable. Retry later and check the status page at https://status.serenityedge.ai.

Body (`application/json`): `ErrorResponse`, the same fields as under 400.
