Chat

Create chat completion

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

POSThttps://api.numes.ai/api/v1/chat/completions

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). Models qualified with :e2ee need the encrypted route; this route rejects them.

Guides: Parameters · Streaming · Tool calling · Structured outputs · Reasoning · 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.

Authorization

AuthorizationheaderRequired

Bearer inference key. Charges settle in the key's billing currency. Authorization: Bearer $NUMES_API_KEY

Headers

X-Request-Idstring: 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.
Length1–128
X-Session-Idstring: Sticky-routing key; request-body session_id takes precedence.
Length1–256
X-OpenRouter-Metadatastring: Values are case-insensitive; unknown values behave as disabled.
X-OpenRouter-Experimental-MetadatastringDeprecated: Legacy alias for X-OpenRouter-Metadata.
HTTP-Refererstring<uri>: Length≤ 2,048
X-Titlestring: Length≤ 256

Request body

application/json

The contract declares a 10 MiB body limit. The size the service enforces is listed in Limits.

modelstring

Length≤ 393

Pattern^[a-z0-9][a-z0-9._-]{0,99}/[A-Za-z0-9][A-Za-z0-9._:-]{0,291}$

modelsarray<string>

Phase 1 accepts one model through either model or models; alternative-model fallback is rejected.

Items1–1

Itemlength ≤ 393

Itempattern ^[a-z0-9][a-z0-9._-]{0,99}/[A-Za-z0-9][A-Za-z0-9._:-]{0,291}$

messagesarray<object>

Show9 child attributes

rolestring

namestring

Provider-owned message name, forwarded with conversation data.

contentany

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_idstring

tool_callsarray<object>

Show3 child attributes

functionobjectRequired

Show2 child attributes

namestringRequired
argumentsstring

idstring

typestring

reasoningstring

reasoning_contentstring

reasoning_detailsarray<object>

Show8 child attributes

typeany
idany
formatany
indexany
textany
summaryany
signatureany
dataany

cache_controlobject

Show2 child attributes

typestringRequired: Value"ephemeral"
ttlenum<string>: One of5m1h

streamboolean

Defaultfalse

storeenum<boolean>

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.

Defaultfalse

Valuefalse

ninteger | null

Only one response choice is supported. Omit or send 1; larger counts are rejected before dispatch.

Range1–1

stream_optionsobject | null

Show1 child attribute

include_usagebooleanDeprecated

usageobjectDeprecated

Legacy usage opt-in accepted for OpenRouter SDK clients. Usage is always returned regardless of include.

Show1 child attribute

includeboolean

session_idstring

Length1–256

prompt_cache_keystring

Privacy-sensitive cache affinity input. The gateway forwards only its keyed digest.

Length1–256

prompt_cache_optionsobject

Show2 child attributes

modeenum<string>: One ofimplicitexplicit
ttlstring: Value"30m"

cache_controlobject

Show2 child attributes

typestringRequired: Value"ephemeral"
ttlenum<string>: One of5m1h

temperatureany

top_pany

top_kany

max_tokensinteger | null

Range≥ 1

max_completion_tokensinteger | null

Range≥ 1

stopstring | array<string> | any | null

One of 2 shapes

ShowOption 1string

A string value.

ShowOption 2array<string>

A array<string> value.

seedinteger | null

toolsarray<object>

One of 3 shapes

Showtype: "function"object

typestringRequired

Value"function"

functionobjectRequired

Show4 child attributes

namestringRequired
descriptionstring
parametersany
strictboolean

cache_controlobject

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.

Show2 child attributes

typestringRequired: Value"ephemeral"
ttlenum<string>: One of5m1h

ShowCommon Hosted Toolobject

typeenum<string>Required

One ofweb_searchweb_fetchdatetimeimage_generationcode_executionfile_searchshellmcptool_searchskillsmapsurl_contextadvisorapply_patchfusionsubagent

configurationobject

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.

Show35 child attributes

max_resultsinteger

Range1–100

max_usesinteger

Range1–20

max_content_tokensinteger

Range1–1,000,000

max_num_resultsinteger

Range1–100

top_kinteger

Range1–100

max_turnsinteger

Range1–64

output_compressioninteger

Range0–100

partial_imagesinteger

Range0–3

search_promptstring

Length1–4,096

search_context_sizeenum<string>

One oflowmediumhigh

engineenum<string>

One ofautonativeexa

timezonestring

Length1–128

modelstring

Length1–256

backgroundenum<string>

One ofautoopaquetransparent

input_fidelityenum<string>

One oflowhigh

moderationenum<string>

Valueauto

output_formatenum<string>

One ofpngjpegwebp

qualityenum<string>

One ofautolowmediumhigh

sizeenum<string>

One ofauto1024x10241024x15361536x1024

metadata_filterstring

Length1–4,096

server_labelstring

Length1–128

server_descriptionstring

Length1–4,096

executionenum<string>

Valueserver

descriptionstring

Length1–4,096

external_web_accessboolean

modelsarray<string>

Items≤ 16

Uniqueitems

Itemlength 1–256

allowed_toolsarray<string>

Items≤ 256

Uniqueitems

Itemlength 1–128

allowed_domainsarray<string>

Items≤ 100

Uniqueitems

Itemlength 1–253

blocked_domainsarray<string>

Items≤ 100

Uniqueitems

Itemlength 1–253

filtersobject

Show1 child attribute

allowed_domainsarray<string>: Items≤ 100
Uniqueitems
Itemlength 1–253

citationsobject

Show1 child attribute

enabledboolean

user_locationobject

Show5 child attributes

typeenum<string>: Valueapproximate
countrystring: Length1–2
citystring: Length1–128
regionstring: Length1–128
timezonestring: Length1–128

cachingobject

Show2 child attributes

typeenum<string>: Valueephemeral
ttlenum<string>: One of5m1h

search_typesobject

Show2 child attributes

web_searchobject
image_searchobject

time_range_filterobject

Show2 child attributes

start_timestring: Length1–128
end_timestring: Length1–128

resource_aliasesarray<string>

Items≤ 32

Uniqueitems

Itempattern ^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$

Showtype: "hosted"object

typestringRequired

Value"hosted"

idenum<string>Required

One ofopenrouter.web_search@1openrouter.web_fetch@1openrouter.datetime@1openrouter.image_generation@1openrouter.apply_patch@1openrouter.fusion@1openrouter.advisor@1openrouter.subagent@1openai.web_search@1openai.file_search@1openai.code_interpreter@1openai.image_generation@1openai.shell@1openai.mcp@1openai.connectors@1openai.tool_search@1openai.skills@1anthropic.web_search@1anthropic.web_fetch@1anthropic.code_execution@1anthropic.advisor@1anthropic.tool_search@1anthropic.mcp@1google.search@1google.maps@1google.url_context@1google.file_search@1google.code_execution@1

configurationobject

Show35 child attributes

max_resultsinteger

Range1–100

max_usesinteger

Range1–20

max_content_tokensinteger

Range1–1,000,000

max_num_resultsinteger

Range1–100

top_kinteger

Range1–100

max_turnsinteger

Range1–64

output_compressioninteger

Range0–100

partial_imagesinteger

Range0–3

search_promptstring

Length1–4,096

search_context_sizeenum<string>

One oflowmediumhigh

engineenum<string>

One ofautonativeexa

timezonestring

Length1–128

modelstring

Length1–256

backgroundenum<string>

One ofautoopaquetransparent

input_fidelityenum<string>

One oflowhigh

moderationenum<string>

Valueauto

output_formatenum<string>

One ofpngjpegwebp

qualityenum<string>

One ofautolowmediumhigh

sizeenum<string>

One ofauto1024x10241024x15361536x1024

metadata_filterstring

Length1–4,096

server_labelstring

Length1–128

server_descriptionstring

Length1–4,096

executionenum<string>

Valueserver

descriptionstring

Length1–4,096

external_web_accessboolean

modelsarray<string>

Items≤ 16

Uniqueitems

Itemlength 1–256

allowed_toolsarray<string>

Items≤ 256

Uniqueitems

Itemlength 1–128

allowed_domainsarray<string>

Items≤ 100

Uniqueitems

Itemlength 1–253

blocked_domainsarray<string>

Items≤ 100

Uniqueitems

Itemlength 1–253

filtersobject

Show1 child attribute

allowed_domainsarray<string>: Items≤ 100
Uniqueitems
Itemlength 1–253

citationsobject

Show1 child attribute

enabledboolean

user_locationobject

Show5 child attributes

typeenum<string>: Valueapproximate
countrystring: Length1–2
citystring: Length1–128
regionstring: Length1–128
timezonestring: Length1–128

cachingobject

Show2 child attributes

typeenum<string>: Valueephemeral
ttlenum<string>: One of5m1h

search_typesobject

Show2 child attributes

web_searchobject
image_searchobject

time_range_filterobject

Show2 child attributes

start_timestring: Length1–128
end_timestring: Length1–128

resource_aliasesarray<string>

Items≤ 32

Uniqueitems

Itempattern ^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$

max_tool_callsinteger

Gateway-enforced upper bound for provider and hosted tool calls.

Range1–1,024

tool_choiceenum<string> | object

Enforced by the gateway and not forwarded as an Ollama generation option.

One of 2 shapes

ShowOption 1enum<string>

A enum<string> value.

Showtype: "function"object

typestringRequired

Value"function"

functionobjectRequired

Show1 child attribute

namestringRequired: Length≥ 1

parallel_tool_callsboolean

Enforced by the gateway; false rejects a response containing multiple calls.

reasoningobject

Show4 child attributes

effortany
max_tokensany
excludeboolean
enabledboolean

reasoning_effortstring | null

OpenAI-compatible shorthand for reasoning.effort.

include_reasoningbooleanDeprecated

Deprecated compatibility alias for the inverse of reasoning.exclude.

response_formatany

Provider-owned output format, forwarded without a fixed local format vocabulary.

modalitiesarray<enum<string>>

One oftextimageaudio

audioobject

Show2 child attributes

voicestringRequired
formatenum<string>Required: One ofwavmp3

providerobject

Show11 child attributes

orderarray<string>

Items≤ 100

Itemlength 1–256

allow_fallbacksboolean

Defaulttrue

require_parametersboolean

Defaultfalse

data_collectionenum<string>

One ofallowdeny

zdrboolean

onlyarray<string>

Items≤ 100

Itemlength 1–256

ignorearray<string>

Items≤ 100

Itemlength 1–256

quantizationsarray<string>

Items≤ 100

Itemlength 1–256

regionsarray<string>

Numes extension filtering endpoint-declared country or region identifiers.

Items≤ 64

Uniqueitems

Itempattern ^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$

sortenum<string>

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.

One ofpricethroughputlatencyquality

max_priceobject

Show2 child attributes

promptnumber: Range≥ 0
completionnumber: Range≥ 0

userstring

Validated and ignored; never forwarded to a provider or retained as inference metadata.

Length≤ 256

Responses

200JSON completion when stream is false, otherwise SSE chunks followed by data colon space bracket DONE bracket.application/jsontext/event-stream

Headers

X-Request-Idstring: Correlation identifier assigned or accepted by the service.
X-Generation-Idstring: Generation identifier when inference reached generation setup.

BodyChatCompletionResponseapplication/json

idstringRequired

objectstringRequired

Value"chat.completion"

createdinteger<int64>Required

modelstringRequired

Pattern^[a-z0-9][a-z0-9._-]{0,99}/[A-Za-z0-9][A-Za-z0-9._:-]{0,291}$

choicesarray<object>Required

Show3 child attributes

indexintegerRequired

finish_reasonstring | nullRequired

messageobjectRequired

Show9 child attributes

rolestringRequired

Value"assistant"

contentstring | nullRequired

reasoningstring

reasoning_detailsarray<object>

Show8 child attributes

typeany
idany
formatany
indexany
textany
summaryany
signatureany
dataany

tool_callsarray<object>

Show3 child attributes

functionobjectRequired

Show2 child attributes

namestringRequired
argumentsstring

idstring

typestring

annotationsarray<object>

Show6 child attributes

typeenum<string>Required: One ofurl_citationfile_citation
titlestring: Length≤ 4,096
urlstring<uri>: Length≤ 8,192
filenamestring: Length≤ 255
start_indexinteger: Range≥ 0
end_indexinteger: Range≥ 0

artifactsarray<object>

Show4 child attributes

typeenum<string>Required: One offileimageaudio
media_typestringRequired: Length≤ 255
datastringRequired: Length≤ 8 Mi
Encodingbase64
filenamestring: Length≤ 255

imagesarray<object>

audioobject

usageobjectRequired

Show16 child attributes

prompt_tokensintegerRequired

Range≥ 0

completion_tokensintegerRequired

Range≥ 0

total_tokensintegerRequired

Range≥ 0

costnumberRequired

Settled cost in the inference key's immutable billing currency. For BTC keys, 1 is one satoshi and precision is one micro-satoshi.

Range≥ 0

usage_meterstring

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_basisenum<string>

One ofprovider_nativegateway_estimate

gateway_billing_unitsobject

Historical gateway billing quantities; absent for current native-meter inference.

Show3 child attributes

prompt_unitsinteger<int64>Required: Range≥ 0
completion_unitsinteger<int64>Required: Range≥ 0
reasoning_unitsinteger<int64>Required: Range≥ 0

native_tokensobject

Validated upstream native-token usage. Current native meters price these counts; reasoning partitions completion and cache partitions prompt.

Show5 child attributes

prompt_tokensinteger<int64>Required: Range≥ 0
completion_tokensinteger<int64>Required: Range≥ 0
reasoning_tokensinteger<int64>: Range≥ 0
cache_read_tokensinteger<int64>: Range≥ 0
cache_write_tokensinteger<int64>: Range≥ 0

prompt_tokens_detailsobject

Show3 child attributes

cached_tokensinteger: Range≥ 0
cache_write_tokensinteger: Range≥ 0
audio_tokensinteger: Range≥ 0

completion_tokens_detailsobject

Show2 child attributes

reasoning_tokensinteger: Range≥ 0
audio_tokensinteger: Range≥ 0

cost_detailsobject

Show3 child attributes

upstream_inference_costnumberRequired: Range≥ 0
upstream_inference_prompt_costnumber: Range≥ 0
upstream_inference_completions_costnumber: Range≥ 0

input_imagesinteger

Range≥ 0

output_imagesinteger

Range≥ 0

input_audio_secondsnumber

Range≥ 0

output_audio_secondsnumber

Range≥ 0

hosted_tool_usagemap<string, number>

Exact namespaced hosted-tool SKU quantities attributable to this response.

providerstring

openrouter_metadataobject

text/event-stream — SSE frames containing ChatCompletionChunk JSON and a terminal data colon space bracket DONE bracket frame.

503No eligible provider can serve the request. Unknown, unpublished, currency-mismatched and unauthorized shared model IDs receive the same bounded response (`error.code` 503, `error.metadata.error_type` "provider_unavailable", message "no provider is available"). Inference and encrypted resolution do not classify model existence after routing fails. Earlier validation and authorization errors remain unchanged. An interrupted server execution while the original HTTP caller remains connected also uses 503 provider_unavailable with the fixed message "service temporarily unavailable". Once streaming has started, the error is in-band and the HTTP status remains 200. If an otherwise eligible USD-indexed Bitcoin offer is blocked by an unavailable market reference, or its reference expires before dispatch, the response instead uses 503 with error_type "bitcoin_reference_price_unavailable" and message "Bitcoin pricing is unavailable. Try again shortly."application/json

Headers

X-Request-Idstring: Correlation identifier assigned or accepted by the service.

BodyErrorResponseapplication/json

errorobjectRequired

Show3 child attributes

codeintegerRequired
messagestringRequired
metadataobject

openrouter_metadataobject

ErrorCompatible error envelopeapplication/json

Headers

X-Request-Idstring: Correlation identifier assigned or accepted by the service.
Retry-Afterinteger: Optional delay in seconds for retryable rate or availability errors.
Range≥ 1

BodyErrorResponseapplication/json

errorobjectRequired

Show3 child attributes

codeintegerRequired
messagestringRequired
metadataobject

openrouter_metadataobject

curl -X POST "https://api.numes.ai/api/v1/chat/completions" \  -H "Authorization: Bearer $NUMES_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "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  }'

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