Skip to main content
POST
openai-python

Authorizations

Authorization
string
header
required

An account API key. Send it as Authorization: Bearer <key>.

Headers

x-naga-routing-strategy
enum<string>

The routing strategy when the body names none. An unknown name is ignored. A NagaAI extension. The order in which NagaAI tries providers at the same price: reliability best recent success rate, balanced speed among near-best success, latency first token, throughput tokens per second, cache providers that read a cached prefix. A NagaAI extension.

Available options:
reliability,
balanced,
latency,
throughput,
cache

Body

application/json

The OpenAI-compatible Chat Completions request. The gateway takes an unrecognized key and drops it.

model
string
required

The model to run, named by an id or alias from NagaAI's catalog. An entry without the chat.completions capability draws a refusal.

messages
object[]
required

The conversation so far, oldest first; one entry at least.

Minimum array length: 1
routing
object

How NagaAI picks the providers for this request: strategy reorders them, max_price removes the dearer ones and can fail the request. A NagaAI extension.

service_tier
enum<string>

flex sends the request only to providers at the model's base price in GET /v1/models, and fails it when none can serve it. Any other value, an unknown one included, or none: any provider, at its price.

Available options:
auto,
default,
flex,
scale,
priority
models
string[] | null

Fallback models, tried in order when model cannot answer: none of its providers served it, or the request does not fit it. At most 3; the answer's model names the one that answered, and only that one is billed. A NagaAI extension in OpenRouter's shape.

Maximum array length: 3
tools
object[] | null

The tools the model is allowed to call.

One entry of tools[], told apart by type.

functions
any[] | null

The pre-tools function-calling surface. A request carrying it draws a refusal.

tool_choice

Which tool, if any, the model calls. An explicit null draws a refusal.

response_format
object

The shape the model's output must take.

temperature
number<double> | null

How much randomness goes into the reply, between 0 and 2, and an alternative to top_p.

Required range: 0 <= x <= 2
top_p
number<double> | null

The sampling cut-off, between 0 and 1, and an alternative to temperature.

Required range: 0 <= x <= 1
stream
boolean | null

Whether the reply arrives incrementally as the model writes it.

stream_options
object | null

Extra streaming behavior. include_usage adds one trailing chunk carrying the totals.

stop

Strings that end generation the moment the model produces one.

max_completion_tokens
integer<int64> | null

The ceiling on generated tokens, reasoning included. At least 1.

Required range: x >= 1
max_tokens
integer<int64> | null

An alias of max_completion_tokens, read only when that key is absent.

Required range: x >= 1
reasoning_effort
enum<string> | null

How much reasoning to spend before answering, from none to max. A model without the level runs the nearest one it has.

Available options:
none,
minimal,
low,
medium,
high,
xhigh,
max
presence_penalty
number<double> | null

How hard a token is penalized for having appeared, from -2 to 2.

Required range: -2 <= x <= 2
frequency_penalty
number<double> | null

How hard repetition is penalized, scaled by how often, from -2 to 2.

Required range: -2 <= x <= 2
parallel_tool_calls
boolean | null

Whether the model may return several tool calls in one turn.

web_search_options
object | null

Turns on the built-in web search for this request. A model none of whose providers can search right now answers without it, and the reply says so in x-naga-dropped-tools.

truncation
enum<string> | null

auto lets NagaAI drop whole turns from the middle of a conversation that does not fit the model's context window, keeping the system prompt, the first and the latest turn; disabled, the default, refuses it with context_length_exceeded. A NagaAI extension, the same key as in the Responses API.

Available options:
auto,
disabled
cache_control
object | null

Automatic prompt caching: one breakpoint on the last part that can be cached, moving forward as the conversation grows. A NagaAI extension in OpenRouter's shape.

prompt_cache_key
string | null

Groups requests that share a prompt prefix, so they reach the same prompt cache. At most 64 characters. NagaAI passes it to the providers that document it and drops it at the rest.

Maximum string length: 64
prompt_cache_retention
enum<string> | null

How long OpenAI keeps the cached prefix on models before GPT-5.6: in_memory or 24h. NagaAI drops a value the model does not take, and drops the field at providers that do not document it.

Available options:
in_memory,
24h

Response

The completion. application/json carries one chat.completion object when stream is false; text/event-stream carries one chat.completion.chunk per event, then the data: [DONE] sentinel, when it is true.

The completion. The gateway answers a request it does not forward with the second shape, which omits logprobs and refusal.

id
string
required

This answer's identifier, repeated on every frame of a stream.

object
string
required

What kind of object this is. Always chat.completion.

Example:

"chat.completion"

created
integer<int64>
required

When the answer was created, in seconds since the Unix epoch.

model
string
required

The model that answered, by its id in the NagaAI catalog.

choices
object[]
required

The answers the model produced — one entry, see index.

usage
object | null

What the request cost in tokens, absent when the provider reported none.