Chat Completions API

Endpoint

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.
`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.
`stream_options.include_usage`	boolean	No	Append a trailing usage chunk to the stream. See Stream termination.
`reasoning`	object	No	Ask a capable model to think first. See 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.
`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

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

{
  "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.
`choices[].finish_reason`	string	One of `stop`, `length`, `tool_calls`, `error`. See 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.

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, Create a message.

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.

Basics

Features

Server-Side Tools

Multimodal

Best Practices

SDKs

API Reference

Chat Completions API

Endpoint

Request

Example

Response

Top-level fields

Choice and message

Usage object

Status codes

Compatibility endpoints

Encrypted

​Endpoint

​Request

​Example

​Response

​Top-level fields

​Choice and message

​Usage object

​Status codes

​Compatibility endpoints

​Encrypted

​Related

Endpoint

Request

Example

Response

Top-level fields

Choice and message

Usage object

Status codes

Compatibility endpoints

Encrypted

Related