> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trynito.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Chat Completions API

> Request fields, response shape, and status codes for POST /v1/chat/completions.

## Endpoint

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
POST /v1/chat/completions
```

Unknown fields at gateway-owned objects are dropped for compatibility. Multipart/form-data (a `request` JSON part plus image files) is also accepted.

## Request

| Field | Type | Required | Notes |
| - | - | - | - |
| `messages` | array | Yes | Conversation so far. Empty array is rejected (`messages is required`). See [Message format](/api/api-reference/chat-and-text/message-format). |
| `model` | string | No | A logical ID from `GET /v1/models`, such as `z-ai/glm-5.2`. Append `:confidential` for a model that serves the Confidential level. `:encrypted` for the Encrypted level, with the Encrypted headers. |
| `temperature` | number | No | Sampling temperature. Nil passthrough. |
| `top_p` | number | No | Nucleus sampling. Nil passthrough. |
| `max_tokens` | integer | No | Cap on generated tokens. |
| `max_completion_tokens` | integer | No | Newer alias for the completion cap. |
| `stream` | boolean | No | Stream the reply as Server-Sent Events. See [SSE transport](/api/api-reference/streaming-format/server-sent-events). |
| `stream_options.include_usage` | boolean | No | Append a trailing usage chunk to the stream. See [Stream termination](/api/api-reference/streaming-format/stream-termination). |
| `reasoning` | object | No | Ask a capable model to think first. See [Reasoning parameters](/api/api-reference/chat-and-text/reasoning-parameters). |
| `reasoning_effort` | string | No | Flat OpenAI-style effort: `minimal`, `low`, `medium`, or `high`. A nested `reasoning.effort` wins when both are present. |
| `response_format` | object | No | `{"type":"json_object"}` on models that advertise `json_mode`; `{"type":"json_schema", ...}` on models that advertise `structured_outputs`. |
| `prompt_cache_key` | string | No | Provider cache affinity key, forwarded where the route supports it. |
| `cache_control` | object | No | Provider cache hints (raw JSON object), passed through. Model must support it. |
| `web_search` | bool or object | No | Search the web and ground the prompt before the model answers. |
| `web_fetch` | boolean | No | Fetch URLs named in the prompt before the model answers. |
| `tools` | array | No | Function tools and hosted tools. See [Tool calling](/api/features/tool-calling). |
| `tool_choice` | string or object | No | `auto` / `none` / `required`, or `{type, function:{name}}`. |
| `user` | string | No | Opaque end-user identifier for your own bookkeeping. |

Duplicate feature keys (for example sending `web_search` twice) are rejected with `request body contains duplicate feature fields`.

## Example

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://app.trynito.ai/v1/chat/completions \
  -H "Authorization: Bearer $NITO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-ai/glm-5.2",
    "messages": [
      {"role": "system", "content": "You are concise."},
      {"role": "user", "content": "Explain a gateway in one sentence."}
    ]
  }'
```

## Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "...",
  "object": "chat.completion",
  "created": 1751299200,
  "model": "z-ai/glm-5.2",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "A gateway is a single entry point that routes your request to the right backend."
      },
      "finish_reason": "stop"
    }
  ],
  "system_fingerprint": null,
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 17,
    "total_tokens": 41
  }
}
```

### Top-level fields

| Field | Type | Notes |
| - | - | - |
| `id` | string | Completion identifier. |
| `object` | string | Always `chat.completion`. |
| `created` | integer | Unix seconds. |
| `model` | string | The model that served the call. |
| `choices` | array | Always exactly one element. Nito does not return `n > 1`. Read `choices[0]`. |
| `system_fingerprint` | null | Always serialized as `null`. Present for OpenAI compatibility; never populated. Do not build logic on it. |
| `usage` | object | Token accounting. See below. |
| `nito_operation_id` | string | Durable, privacy-safe operation ID for support. |
| `web_search` | object | Optional. Present when a web-search tool ran. |
| `free_tier` | object | Optional. Present on Free plan-eligible calls. |

### Choice and message

| Field | Type | Notes |
| - | - | - |
| `choices[].index` | integer | Choice index (always `0`). |
| `choices[].message.role` | string | Always `assistant` on the response. |
| `choices[].message.content` | string | Always present. May be empty when the model is calling a tool. |
| `choices[].message.tool_calls` | array | Optional. Present when the model requests tool calls. |
| `choices[].message.reasoning_details` | array | Optional. Present when reasoning is enabled. See [Reasoning parameters](/api/api-reference/chat-and-text/reasoning-parameters). |
| `choices[].finish_reason` | string | One of `stop`, `length`, `tool_calls`, `error`. See [Finish reasons](/api/api-reference/chat-and-text/finish-reasons). |

### Usage object

| Field | Type | Notes |
| - | - | - |
| `prompt_tokens` | integer | Tokens in the prompt. |
| `completion_tokens` | integer | Tokens generated. |
| `total_tokens` | integer | Sum of the two. |
| `prompt_tokens_details` | object | Optional. `cached_tokens`. |
| `cache_read_input_tokens` | integer | Optional. Tokens read from a provider prompt cache. |
| `cache_write_input_tokens` | integer | Optional. Tokens written to a provider prompt cache. |
| `reasoning_tokens` | integer | Optional. Tokens spent on reasoning. |
| `server_tool_use` | object | Optional. `web_search_requests`, `web_search_results`, `web_fetch_requests`. |

## Status codes

| Status | When |
| - | - |
| `200` | Success. |
| `400` | Decode, validation, feature, or attachment error. Envelope `{"error":{message,code,param}}`. |
| `405` | Non-POST request. Sets the `Allow` header. |
| `401` / `402` / `403` / `429` / `502` / `503` / `500` | Authentication, funding, and provider failures. See [Error codes](/api/api-reference/errors-and-rate-limits/error-codes). |

All responses set `Cache-Control: no-store`.

## Compatibility endpoints

`POST /v1/responses` (stateless, plus `POST /v1/responses/compact`) and `POST /v1/messages` with `POST /v1/messages/count_tokens` validate their native shapes and map onto the same pipeline. Schemas: [Create a response](/api/api-reference/endpoints/responses/createopenairesponse), [Create a message](/api/api-reference/endpoints/messages/createanthropicmessage).

## Encrypted

An `:encrypted` model with the `nito-encrypted-*` headers runs the call with client-side encryption. Streaming works; hosted web tools, content arrays, and attachment parts are rejected. See [Encrypted](/api/api-reference/chat-and-text/encrypted).

## Related

* [Chat Completions (feature guide)](/api/features/chat-completions)
* [Message format](/api/api-reference/chat-and-text/message-format)
* [Reasoning parameters](/api/api-reference/chat-and-text/reasoning-parameters)
* [Finish reasons](/api/api-reference/chat-and-text/finish-reasons)
* [Fusion](/api/api-reference/chat-and-text/chat-fusion)
* [SSE transport](/api/api-reference/streaming-format/server-sent-events)
* [Error format](/api/api-reference/overview/error-format)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.