# Create chat completion

> Generate a model response for a conversation, as one JSON object or as a stream of Server-Sent Events.

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

Source: https://0.0.0.0:3000/docs/api-reference/chat/create-chat-completion
Authorization: Bearer inference key

The OpenAI Chat Completions shape, routed across provider endpoints. Conversation fields, reasoning state and ordinary generation extensions are forwarded to the upstream provider. Routing, cache isolation, privacy, execution and billing controls remain validated. Native adapters can reject conversation shapes they cannot translate. Send a fresh `X-Request-Id` on every request, or omit it; a reused ID returns `400` (see [Request and generation IDs](/docs/api-reference/errors#request-and-generation-ids)). Models qualified with `:e2ee` need the [encrypted route](/docs/inference/encrypted); this route rejects them.

Guides: [Parameters](/docs/api-reference/parameters) · [Streaming](/docs/features/streaming) · [Tool calling](/docs/features/tool-calling) · [Structured outputs](/docs/features/structured-outputs) · [Reasoning](/docs/features/reasoning) · [Provider routing](/docs/routing/provider-routing).

`store` may be omitted or set to boolean `false`; `true`, `null` and other types return `400`. It doesn't require a provider capability and isn't forwarded. It doesn't change metadata retention or provider data policies; see [Data retention](/docs/privacy/data-retention).

```request
{
  "method": "POST",
  "path": "/chat/completions",
  "body": {
    "model": "openai/gpt-6-luna",
    "messages": [
      { "role": "system", "content": "You are a concise assistant." },
      { "role": "user", "content": "Explain Server-Sent Events in one sentence." }
    ],
    "max_tokens": 200,
    "store": false
  }
}
```

```json title="Response 200"
{
  "id": "0f5b5c9a-3a7e-4c6f-9d1e-2b8f7a6c5d4e",
  "object": "chat.completion",
  "created": 1790000000,
  "model": "openai/gpt-6-luna",
  "provider": "Example Provider",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "Server-Sent Events let a server push a stream of text events to a client over one long-lived HTTP response."
      }
    }
  ],
  "usage": {
    "prompt_tokens": 27,
    "completion_tokens": 24,
    "total_tokens": 51,
    "token_count_basis": "provider_native",
    "cost": 0.000013,
    "cost_details": { "upstream_inference_cost": 0.000013 }
  }
}
```

```sse title="Response stream"
data: {"id":"0f5b5c9a-3a7e-4c6f-9d1e-2b8f7a6c5d4e","object":"chat.completion.chunk","created":1790000000,"model":"openai/gpt-6-luna","choices":[{"index":0,"delta":{"role":"assistant","content":"Server-Sent"},"finish_reason":null}]}

data: {"id":"0f5b5c9a-3a7e-4c6f-9d1e-2b8f7a6c5d4e","object":"chat.completion.chunk","created":1790000000,"model":"openai/gpt-6-luna","choices":[{"index":0,"delta":{"content":" Events let a server push…"},"finish_reason":null}]}

data: {"id":"0f5b5c9a-3a7e-4c6f-9d1e-2b8f7a6c5d4e","object":"chat.completion.chunk","created":1790000000,"model":"openai/gpt-6-luna","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"id":"0f5b5c9a-3a7e-4c6f-9d1e-2b8f7a6c5d4e","object":"chat.completion.chunk","created":1790000000,"model":"openai/gpt-6-luna","choices":[],"usage":{"prompt_tokens":27,"completion_tokens":24,"total_tokens":51,"cost":0.000013,"cost_details":{"upstream_inference_cost":0.000013}}}

data: [DONE]
```

```json title="Response 402"
{
  "error": {
    "code": 402,
    "message": "insufficient credits",
    "metadata": { "error_type": "insufficient_credits" }
  }
}
```

## Headers

- `X-Request-Id` (string; Length 1–128): Correlation ID, not an idempotency key. Inference request IDs recorded with a generation are unique per account. A traffic-admitted request reusing a recorded ID returns 400 invalid_request. Traffic admission rejection takes precedence over this conflict, including for reused IDs; it performs no generation lookup and writes no generation, result or attempt. Rate-limit rejection returns 429 rate_limited with Retry-After; an inference limiter outage retains 500 server.
- `X-Session-Id` (string; Length 1–256): Sticky-routing key; request-body session_id takes precedence.
- `X-OpenRouter-Metadata` (string): Values are case-insensitive; unknown values behave as disabled.
- `X-OpenRouter-Experimental-Metadata` (string): Legacy alias for X-OpenRouter-Metadata.
- `HTTP-Referer` (string<uri>; Length ≤ 2,048)
- `X-Title` (string; Length ≤ 256)

## Request body (application/json)

- `model` (string; Length ≤ 393; Pattern ^[a-z0-9][a-z0-9._-]{0,99}/[A-Za-z0-9][A-Za-z0-9._:-]{0,291}$)
- `models` (array<string>; Items 1–1; Item length ≤ 393; Item pattern ^[a-z0-9][a-z0-9._-]{0,99}/[A-Za-z0-9][A-Za-z0-9._:-]{0,291}$): Phase 1 accepts one model through either model or models; alternative-model fallback is rejected.
- `messages` (array<object>)
  - `role` (string)
  - `name` (string): Provider-owned message name, forwarded with conversation data.
  - `content` (any): Provider-owned text or structured content; matching compatible adapters preserve unfamiliar non-media shapes. Media must use supported image_url, file or input_audio parts and pass gateway acquisition. Native adapters reject media on roles they cannot translate without loss.
  - `tool_call_id` (string)
  - `tool_calls` (array<object>)
    - `id` (string)
    - `type` (string)
    - `function` (object; required)
      - `name` (string; required)
      - `arguments` (string)
  - `reasoning` (string)
  - `reasoning_content` (string)
  - `reasoning_details` (array<object>)
    - `type` (any)
    - `id` (any)
    - `format` (any)
    - `index` (any)
    - `text` (any)
    - `summary` (any)
    - `signature` (any)
    - `data` (any)
  - `cache_control` (object)
    - `type` (string; required)
    - `ttl` (enum<string>; one of 5m, 1h)
- `stream` (boolean; default false)
- `store` (enum<boolean>; default false; one of false): Only false is accepted, equivalent to omission. Stored completions are unsupported. This field is not forwarded and does not change billing metadata or provider retention policies; use provider.zdr and provider.data_collection for provider privacy requirements.
- `n` (integer | null; Range 1–1): Only one response choice is supported. Omit or send 1; larger counts are rejected before dispatch.
- `stream_options` (object | null)
  - `include_usage` (boolean)
- `usage` (object): Legacy usage opt-in accepted for OpenRouter SDK clients. Usage is always returned regardless of include.
  - `include` (boolean)
- `session_id` (string; Length 1–256)
- `prompt_cache_key` (string; Length 1–256): Privacy-sensitive cache affinity input. The gateway forwards only its keyed digest.
- `prompt_cache_options` (object)
  - `mode` (enum<string>; one of implicit, explicit)
  - `ttl` (string)
- `cache_control` (object)
  - `type` (string; required)
  - `ttl` (enum<string>; one of 5m, 1h)
- `temperature` (any)
- `top_p` (any)
- `top_k` (any)
- `max_tokens` (integer | null; Range ≥ 1)
- `max_completion_tokens` (integer | null; Range ≥ 1)
- `stop` (string | array<string> | any | null)
  - variant Option 1
  - variant Option 2
- `seed` (integer | null)
- `tools` (array<object>)
  - variant type: "function"
    - `type` (string; required)
    - `cache_control` (object): Accepted cache hint for this tool definition. It is validated but not sent to the endpoint and never affects routing; mark a system or message block to cache the prompt prefix.
      - `type` (string; required)
      - `ttl` (enum<string>; one of 5m, 1h)
    - `function` (object; required)
      - `name` (string; required)
      - `description` (string)
      - `parameters` (any)
      - `strict` (boolean)
  - variant Common Hosted Tool
    - `type` (enum<string>; required; one of web_search, web_fetch, datetime, image_generation, code_execution, file_search, shell, mcp, tool_search, skills, maps, url_context, advisor, apply_patch, fusion, subagent)
    - `configuration` (object): Strict union of the public configuration fields accepted by the frozen hosted-tool registry. Each tool accepts only its documented subset; secret-backed upstream resource identifiers are supplied through resource aliases instead.
      - `max_results` (integer; Range 1–100)
      - `max_uses` (integer; Range 1–20)
      - `max_content_tokens` (integer; Range 1–1,000,000)
      - `max_num_results` (integer; Range 1–100)
      - `top_k` (integer; Range 1–100)
      - `max_turns` (integer; Range 1–64)
      - `output_compression` (integer; Range 0–100)
      - `partial_images` (integer; Range 0–3)
      - `search_prompt` (string; Length 1–4,096)
      - `search_context_size` (enum<string>; one of low, medium, high)
      - `engine` (enum<string>; one of auto, native, exa)
      - `timezone` (string; Length 1–128)
      - `model` (string; Length 1–256)
      - `background` (enum<string>; one of auto, opaque, transparent)
      - `input_fidelity` (enum<string>; one of low, high)
      - `moderation` (enum<string>; one of auto)
      - `output_format` (enum<string>; one of png, jpeg, webp)
      - `quality` (enum<string>; one of auto, low, medium, high)
      - `size` (enum<string>; one of auto, 1024x1024, 1024x1536, 1536x1024)
      - `metadata_filter` (string; Length 1–4,096)
      - `server_label` (string; Length 1–128)
      - `server_description` (string; Length 1–4,096)
      - `execution` (enum<string>; one of server)
      - `description` (string; Length 1–4,096)
      - `external_web_access` (boolean)
      - `models` (array<string>; Items ≤ 16; Unique items; Item length 1–256)
      - `allowed_tools` (array<string>; Items ≤ 256; Unique items; Item length 1–128)
      - `allowed_domains` (array<string>; Items ≤ 100; Unique items; Item length 1–253)
      - `blocked_domains` (array<string>; Items ≤ 100; Unique items; Item length 1–253)
      - `filters` (object)
        - `allowed_domains` (array<string>; Items ≤ 100; Unique items; Item length 1–253)
      - `citations` (object)
        - `enabled` (boolean)
      - `user_location` (object)
        - `type` (enum<string>; one of approximate)
        - `country` (string; Length 1–2)
        - `city` (string; Length 1–128)
        - `region` (string; Length 1–128)
        - `timezone` (string; Length 1–128)
      - `caching` (object)
        - `type` (enum<string>; one of ephemeral)
        - `ttl` (enum<string>; one of 5m, 1h)
      - `search_types` (object)
        - `web_search` (object)
        - `image_search` (object)
      - `time_range_filter` (object)
        - `start_time` (string; Length 1–128)
        - `end_time` (string; Length 1–128)
    - `resource_aliases` (array<string>; Items ≤ 32; Unique items; Item pattern ^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$)
  - variant type: "hosted"
    - `type` (string; required)
    - `id` (enum<string>; required; one of openrouter.web_search@1, openrouter.web_fetch@1, openrouter.datetime@1, openrouter.image_generation@1, openrouter.apply_patch@1, openrouter.fusion@1, openrouter.advisor@1, openrouter.subagent@1, openai.web_search@1, openai.file_search@1, openai.code_interpreter@1, openai.image_generation@1, openai.shell@1, openai.mcp@1, openai.connectors@1, openai.tool_search@1, openai.skills@1, anthropic.web_search@1, anthropic.web_fetch@1, anthropic.code_execution@1, anthropic.advisor@1, anthropic.tool_search@1, anthropic.mcp@1, google.search@1, google.maps@1, google.url_context@1, google.file_search@1, google.code_execution@1)
    - `configuration` (object): Strict union of the public configuration fields accepted by the frozen hosted-tool registry. Each tool accepts only its documented subset; secret-backed upstream resource identifiers are supplied through resource aliases instead.
      - `max_results` (integer; Range 1–100)
      - `max_uses` (integer; Range 1–20)
      - `max_content_tokens` (integer; Range 1–1,000,000)
      - `max_num_results` (integer; Range 1–100)
      - `top_k` (integer; Range 1–100)
      - `max_turns` (integer; Range 1–64)
      - `output_compression` (integer; Range 0–100)
      - `partial_images` (integer; Range 0–3)
      - `search_prompt` (string; Length 1–4,096)
      - `search_context_size` (enum<string>; one of low, medium, high)
      - `engine` (enum<string>; one of auto, native, exa)
      - `timezone` (string; Length 1–128)
      - `model` (string; Length 1–256)
      - `background` (enum<string>; one of auto, opaque, transparent)
      - `input_fidelity` (enum<string>; one of low, high)
      - `moderation` (enum<string>; one of auto)
      - `output_format` (enum<string>; one of png, jpeg, webp)
      - `quality` (enum<string>; one of auto, low, medium, high)
      - `size` (enum<string>; one of auto, 1024x1024, 1024x1536, 1536x1024)
      - `metadata_filter` (string; Length 1–4,096)
      - `server_label` (string; Length 1–128)
      - `server_description` (string; Length 1–4,096)
      - `execution` (enum<string>; one of server)
      - `description` (string; Length 1–4,096)
      - `external_web_access` (boolean)
      - `models` (array<string>; Items ≤ 16; Unique items; Item length 1–256)
      - `allowed_tools` (array<string>; Items ≤ 256; Unique items; Item length 1–128)
      - `allowed_domains` (array<string>; Items ≤ 100; Unique items; Item length 1–253)
      - `blocked_domains` (array<string>; Items ≤ 100; Unique items; Item length 1–253)
      - `filters` (object)
        - `allowed_domains` (array<string>; Items ≤ 100; Unique items; Item length 1–253)
      - `citations` (object)
        - `enabled` (boolean)
      - `user_location` (object)
        - `type` (enum<string>; one of approximate)
        - `country` (string; Length 1–2)
        - `city` (string; Length 1–128)
        - `region` (string; Length 1–128)
        - `timezone` (string; Length 1–128)
      - `caching` (object)
        - `type` (enum<string>; one of ephemeral)
        - `ttl` (enum<string>; one of 5m, 1h)
      - `search_types` (object)
        - `web_search` (object)
        - `image_search` (object)
      - `time_range_filter` (object)
        - `start_time` (string; Length 1–128)
        - `end_time` (string; Length 1–128)
    - `resource_aliases` (array<string>; Items ≤ 32; Unique items; Item pattern ^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$)
- `max_tool_calls` (integer; Range 1–1,024): Gateway-enforced upper bound for provider and hosted tool calls.
- `tool_choice` (enum<string> | object): Enforced by the gateway and not forwarded as an Ollama generation option.
  - variant Option 1
  - variant type: "function"
    - `type` (string; required)
    - `function` (object; required)
      - `name` (string; required; Length ≥ 1)
- `parallel_tool_calls` (boolean): Enforced by the gateway; false rejects a response containing multiple calls.
- `reasoning` (object)
  - `effort` (any)
  - `max_tokens` (any)
  - `exclude` (boolean)
  - `enabled` (boolean)
- `reasoning_effort` (string | null): OpenAI-compatible shorthand for reasoning.effort.
- `include_reasoning` (boolean): Deprecated compatibility alias for the inverse of reasoning.exclude.
- `response_format` (any): Provider-owned output format, forwarded without a fixed local format vocabulary.
- `modalities` (array<enum<string>>; one of text, image, audio)
- `audio` (object)
  - `voice` (string; required)
  - `format` (enum<string>; required; one of wav, mp3)
- `provider` (object)
  - `order` (array<string>; Items ≤ 100; Item length 1–256)
  - `allow_fallbacks` (boolean; default true)
  - `require_parameters` (boolean; default false)
  - `data_collection` (enum<string>; one of allow, deny)
  - `zdr` (boolean)
  - `only` (array<string>; Items ≤ 100; Item length 1–256)
  - `ignore` (array<string>; Items ≤ 100; Item length 1–256)
  - `quantizations` (array<string>; Items ≤ 100; Item length 1–256)
  - `regions` (array<string>; Items ≤ 64; Unique items; Item pattern ^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$): Numes extension filtering endpoint-declared country or region identifiers.
  - `sort` (enum<string>; one of price, throughput, latency, quality): Deterministic provider sort. `quality` is a deliberate Numes compatibility extension that ranks endpoints by exact task-scoped content-free validation evidence; it is opt-in and never changes the default routing order.

  - `max_price` (object)
    - `prompt` (number; Range ≥ 0)
    - `completion` (number; Range ≥ 0)
- `user` (string; Length ≤ 256): Validated and ignored; never forwarded to a provider or retained as inference metadata.

## Response 200 (application/json)

- `id` (string; required)
- `object` (string; required)
- `created` (integer<int64>; required)
- `model` (string; required; Pattern ^[a-z0-9][a-z0-9._-]{0,99}/[A-Za-z0-9][A-Za-z0-9._:-]{0,291}$)
- `provider` (string)
- `choices` (array<object>; required)
  - `index` (integer; required)
  - `finish_reason` (string | null; required)
  - `message` (object; required)
    - `role` (string; required)
    - `content` (string | null; required)
    - `reasoning` (string)
    - `reasoning_details` (array<object>)
      - `type` (any)
      - `id` (any)
      - `format` (any)
      - `index` (any)
      - `text` (any)
      - `summary` (any)
      - `signature` (any)
      - `data` (any)
    - `tool_calls` (array<object>)
      - `id` (string)
      - `type` (string)
      - `function` (object; required)
        - `name` (string; required)
        - `arguments` (string)
    - `annotations` (array<object>)
      - `type` (enum<string>; required; one of url_citation, file_citation)
      - `title` (string; Length ≤ 4,096)
      - `url` (string<uri>; Length ≤ 8,192)
      - `filename` (string; Length ≤ 255)
      - `start_index` (integer; Range ≥ 0)
      - `end_index` (integer; Range ≥ 0)
    - `artifacts` (array<object>)
      - `type` (enum<string>; required; one of file, image, audio)
      - `filename` (string; Length ≤ 255)
      - `media_type` (string; required; Length ≤ 255)
      - `data` (string; required; Length ≤ 8 Mi; Encoding base64)
    - `images` (array<object>)
    - `audio` (object)
- `usage` (object; required)
  - `usage_meter` (string): Opaque identifier of the billing basis this request was charged under. Treat it as a label; the charged amounts are in the cost fields.
  - `token_count_basis` (enum<string>; one of provider_native, gateway_estimate)
  - `gateway_billing_units` (object): Historical gateway billing quantities; absent for current native-meter inference.
    - `prompt_units` (integer<int64>; required; Range ≥ 0)
    - `completion_units` (integer<int64>; required; Range ≥ 0)
    - `reasoning_units` (integer<int64>; required; Range ≥ 0)
  - `native_tokens` (object): Validated upstream native-token usage. Current native meters price these counts; reasoning partitions completion and cache partitions prompt.
    - `prompt_tokens` (integer<int64>; required; Range ≥ 0)
    - `completion_tokens` (integer<int64>; required; Range ≥ 0)
    - `reasoning_tokens` (integer<int64>; Range ≥ 0)
    - `cache_read_tokens` (integer<int64>; Range ≥ 0)
    - `cache_write_tokens` (integer<int64>; Range ≥ 0)
  - `prompt_tokens` (integer; required; Range ≥ 0)
  - `completion_tokens` (integer; required; Range ≥ 0)
  - `total_tokens` (integer; required; Range ≥ 0)
  - `cost` (number; required; Range ≥ 0): Settled cost in the inference key's immutable billing currency. For BTC keys, 1 is one satoshi and precision is one micro-satoshi.

  - `prompt_tokens_details` (object)
    - `cached_tokens` (integer; Range ≥ 0)
    - `cache_write_tokens` (integer; Range ≥ 0)
    - `audio_tokens` (integer; Range ≥ 0)
  - `completion_tokens_details` (object)
    - `reasoning_tokens` (integer; Range ≥ 0)
    - `audio_tokens` (integer; Range ≥ 0)
  - `cost_details` (object)
    - `upstream_inference_cost` (number; required; Range ≥ 0)
    - `upstream_inference_prompt_cost` (number; Range ≥ 0)
    - `upstream_inference_completions_cost` (number; Range ≥ 0)
  - `input_images` (integer; Range ≥ 0)
  - `output_images` (integer; Range ≥ 0)
  - `input_audio_seconds` (number; Range ≥ 0)
  - `output_audio_seconds` (number; Range ≥ 0)
  - `hosted_tool_usage` (map<string, number>): Exact namespaced hosted-tool SKU quantities attributable to this response.
- `openrouter_metadata` (object)

## Response 503 (application/json)

- `error` (object; required)
  - `code` (integer; required)
  - `message` (string; required)
  - `metadata` (object)
- `openrouter_metadata` (object)

## Response default (application/json)

- `error` (object; required)
  - `code` (integer; required)
  - `message` (string; required)
  - `metadata` (object)
- `openrouter_metadata` (object)