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

# Chat Completions

> POST /chat/completions: every parameter, the full response shape, and examples.

Text models: [JSON](https://nomask.ai/llm/models) · [Markdown](https://nomask.ai/llm/models.md) · [Text](https://nomask.ai/llm/models.txt)

> [card] [Try Chat Completions](https://docs.nomask.ai/api-reference/chat-completions.md)
>
> Open the interactive request builder with authentication, body fields, and response examples.

> [!NOTE]
>
> Use a current public model ID from [Models](https://nomask.ai/models) or `GET /models`. Example IDs and options must match the selected model's advertised capabilities and limits.

The core endpoint. Send a conversation, get a completion back, streaming or not.

Choose a text model in your [Models dashboard](https://nomask.ai/models), or query the authenticated [List models endpoint](https://docs.nomask.ai/api-reference/list-models.md).

## The endpoint

`POST /chat/completions`

The body must be a JSON object with `Content-Type: application/json`. Authentication is a Bearer key; see [Authentication](https://docs.nomask.ai/authentication.md).

## Request parameters

### `model`

**Type:** string · **Required**

The public model id, e.g. `nomask-1.2`. Unknown ids return `404 model_not_found`. List ids with `GET /models`.

### `messages`

**Type:** array · **Required**

The conversation so far. Each message has a `role` (`system`, `user`, `assistant`, or `tool`) and `content`. Content is a string, or an array of parts: `text` and `image_url` on vision models (see [Vision](https://docs.nomask.ai/vision.md)), plus `video_url` on supported models (see [Video Inputs](https://docs.nomask.ai/video-inputs.md)). Tool messages carry a `tool_call_id` and a string result; assistant messages may carry `tool_calls` with null content (see [Function Calling](https://docs.nomask.ai/function-calling.md)).

Extract file text in your code and send it as a text message.

### `tools`

**Type:** array

Function definitions the model may call: up to 64 entries of `{"type": "function", "function": {name, description, parameters}}`. Requires a model with the `function_calling` capability. See [Function Calling](https://docs.nomask.ai/function-calling.md).

### `tool_choice`

**Type:** string or object · **Default:** `"auto"`

`auto`, `none`, `required`, or `{"type": "function", "function": {"name": "..."}}` to force one tool. Only valid together with `tools`.

### `parallel_tool_calls`

**Type:** boolean · **Default:** `true`

Whether the model may request several tool calls in a single turn.

### `temperature`

**Type:** number · **Default:** `model default`

Sampling temperature, 0 to 2. Lower is more deterministic, higher is more creative.

### `top_p`

**Type:** number · **Default:** `model default`

Nucleus sampling, 0 to 1. Use temperature or top\_p, not usually both.

### `frequency_penalty`

**Type:** number · **Default:** `0`

Between -2 and 2. Positive values reduce verbatim repetition.

### `presence_penalty`

**Type:** number · **Default:** `0`

Between -2 and 2. Positive values push the model toward new topics.

### `max_tokens`

**Type:** integer · **Default:** `model ceiling`

Caps the length of the reply, including reasoning tokens, and therefore caps the output cost of the request. Each model has its own ceiling (`max_output_tokens` on `GET /models`); values above it are clamped down to it. `max_completion_tokens` is accepted as an alias and wins when both are present.

### `stop`

**Type:** string or array

Up to 4 sequences where generation stops. The stop sequence itself is not included in the output.

### `stream`

**Type:** boolean · **Default:** `false`

Stream the response as server-sent events. See [Streaming](https://docs.nomask.ai/streaming.md).

### `stream_options`

**Type:** object

`{"include_usage": true}` adds a final usage chunk to streams, carrying token totals and `nomask.cost_usd`.

### `n`

**Type:** integer · **Default:** `1`

Only `1` is supported. Other values return `400 unsupported_parameter`.

### `response_format`

**Type:** object

Omit this field or send `{"type": "text"}`. JSON mode (`json_object`) and structured output (`json_schema`) are not supported and return `400 unsupported_parameter`.

> [!NOTE]
>
> `functions`, `function_call` (legacy; use `tools`), `logprobs`, `top_logprobs`, `audio`, `modalities`, and `prediction` are rejected with `400 unsupported_parameter`. See [OpenAI Compatibility](https://docs.nomask.ai/openai-compatibility.md).

## NoMask parameters

### `reasoning`

**Type:** object

`{"enabled": true|false, "effort": "minimal"|"low"|"medium"|"high"|"xhigh"|"max"}`. See [Reasoning](https://docs.nomask.ai/reasoning.md).

### `reasoning_effort`

**Type:** string

Shorthand for `reasoning.effort`: `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`. `none` is an Off alias. The model’s supported efforts determine the effective level.

### `nomask_system_prompt`

**Type:** boolean · **Default:** `false`

Prepend the per-model NoMask chat persona before your messages. See [NoMask System Prompt](https://docs.nomask.ai/system-prompt.md).

## Response

> [tab] Response
>
> ```json theme={"system"}
> {
>   "id": "chatcmpl_01jz...",
>   "object": "chat.completion",
>   "created": 1783140000,
>   "model": "nomask-1.2",
>   "choices": [{
>     "index": 0,
>     "message": {
>       "role": "assistant",
>       "content": "HTTP caching stores copies of responses..."
>     },
>     "finish_reason": "stop"
>   }],
>   "usage": {
>     "prompt_tokens": 21,
>     "completion_tokens": 48,
>     "total_tokens": 69
>   },
>   "nomask": {
>     "prompt_cache": {
>       "enabled": false,
>       "usage_status": "unreported",
>       "read_tokens": null,
>       "write_tokens": null,
>       "usd_per_1m_cached_input": null,
>       "savings_usd": null
>     },
>     "model_cost_usd": 0.000098,
>     "cost_usd": 0.000098
>   }
> }
> ```

> [tab] Request
>
> ```bash theme={"system"}
> curl https://api.nomask.ai/v1/chat/completions \
>   -H "Authorization: Bearer $NOMASK_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "model": "nomask-1.2",
>     "messages": [{"role": "user", "content": "Explain HTTP caching in two sentences."}]
>   }'
> ```

* `finish_reason` is currently normalized to `stop` for a completed answer or `tool_calls` when the model requests function calls. The API does not currently emit `length`, so do not rely on that value to detect an output-token ceiling.
* `message.tool_calls` is present when the model calls your functions. `content` is null for a pure tool-call turn; a model may also return text alongside its calls.
* `reasoning_content` is present when the model thought before answering.
* `nomask.warnings` appears when a request option could not be honored (for example disabling reasoning on an always-on model).
* Every response also carries an `X-Request-Id` header; include it in support requests.

## Usage and cost

Every completion reports what it consumed: `usage.prompt_tokens` (input, including images and any injected persona), `usage.completion_tokens` (output, including reasoning), and `nomask.cost_usd`, the exact USD amount charged to your balance. `nomask.model_cost_usd` reports the model charge. On streams the same data arrives in the final usage chunk when `stream_options.include_usage` is set. Historical records are available at `GET /usage`.


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