Chat Completions

Try Chat Completions

Open the interactive request builder with authentication, body fields, and response examples.

Use a current public model ID from 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, or query the authenticated List models endpoint.

The endpoint

POST /chat/completions The body must be a JSON object with Content-Type: application/json. Authentication is a Bearer key; see Authentication.

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), plus video_url on supported models (see Video Inputs). Tool messages carry a tool_call_id and a string result; assistant messages may carry tool_calls with null content (see Function Calling). 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.

`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.

`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.

functions, function_call (legacy; use tools), logprobs, top_logprobs, audio, modalities, and prediction are rejected with 400 unsupported_parameter. See OpenAI Compatibility.

NoMask parameters

`reasoning`

Type: object {"enabled": true|false, "effort": "minimal"|"low"|"medium"|"high"|"xhigh"|"max"}. See Reasoning.

`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.

Response

Response
Request

{
  "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
  }
}

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.

Docs

Getting Started

Text & Chat

Image

Production

Coding Tools

Chat API

Image API

Model API

Account & Usage

Errors & Limits

Chat Completions

Try Chat Completions

The endpoint

Request parameters

`model`

`messages`

`tools`

`tool_choice`

`parallel_tool_calls`

`temperature`

`top_p`

`frequency_penalty`

`presence_penalty`

`max_tokens`

`stop`

`stream`

`stream_options`

`n`

`response_format`

NoMask parameters

`reasoning`

`reasoning_effort`

`nomask_system_prompt`

Response

Usage and cost

Try Chat Completions

​The endpoint

​Request parameters

​model

​messages

​tools

​tool_choice

​parallel_tool_calls

​temperature

​top_p

​frequency_penalty

​presence_penalty

​max_tokens

​stop

​stream

​stream_options

​n

​response_format

​NoMask parameters

​reasoning

​reasoning_effort

​nomask_system_prompt

​Response

​Usage and cost

The endpoint

Request parameters

`model`

`messages`

`tools`

`tool_choice`

`parallel_tool_calls`

`temperature`

`top_p`

`frequency_penalty`

`presence_penalty`

`max_tokens`

`stop`

`stream`

`stream_options`

`n`

`response_format`

NoMask parameters

`reasoning`

`reasoning_effort`

`nomask_system_prompt`

Response

Usage and cost