Create a chat completion

Compatible with OpenAI Chat Completions, for inference against conversational models. The official SDKs work as-is.

post/v1/chat/completions

Request

  • Base URL: https://gateway.amux.ai
  • URL: https://gateway.amux.ai/v1/chat/completions
  • Auth: HTTP bearer

Headers

Content-Typestring required

Always application/json.

anthropic-betastring

Anthropic beta feature switch. Not supported on this endpoint — it is not forwarded even when the request is converted and routed to an Anthropic upstream. Use /v1/messages if you need it.

Request body

modelstring required

Canonical ID shaped like vendor/model. The colon suffix does one of two things: :provider pins one provider (anthropic/claude-opus-5:anthropic; a pinned provider that fails means the request fails, with no automatic failover), and :@strategy chooses the ordering for this call (:@price / :@latency / :@throughput / :@reliability / :@balanced). They cannot be combined — see the overview for what each means.

max_tokensinteger

Maximum tokens to generate. Values above the model's ceiling are clamped to it, and the adjustment is recorded in the conversion notes.

max_completion_tokensinteger

Same as max_tokens; the field name newer OpenAI models use. If both are given, this one wins.

temperaturenumber

Sampling temperature, 0–2. Clamped to 1 when the upstream speaks Anthropic (its ceiling); the clamp is recorded in the conversion notes.

top_pnumber

Nucleus sampling. Pick this or temperature; the vendors recommend against tuning both.

ninteger

How many candidates to generate. Not carried across protocols — the other three have no equivalent. On same-protocol requests the upstream decides.

streamboolean

Return an SSE stream. Usage arrives in the final data chunk.

presence_penaltynumber

Presence penalty, -2 to 2. Anthropic and Responses have no equivalent, so it is dropped with a note.

frequency_penaltynumber

Frequency penalty, -2 to 2. Same as above.

logit_biasobject

Per-token bias map. Chat-only; not carried across protocols by default.

logprobsboolean

Return token log probabilities. Not carried across protocols.

top_logprobsinteger

How many alternatives to return per position; requires logprobs. Not carried across protocols.

seedinteger

Sampling seed. Gemini has an equivalent; Anthropic and Responses do not.

toolsobject[]

Callable tools, shaped { type: "function", function: { name, description, parameters } }. The four protocols shape tools differently; cross-protocol requests are rewritten for you.

tool_choicestring

auto / none / required, or { type: "function", function: { name } } to force one. All four protocols have matching values and are mapped automatically.

parallel_tool_callsboolean

Whether the model may issue several tool calls at once. On Anthropic it is inverted into tool_choice.disable_parallel_tool_use; Gemini has no such switch. Only sent when tools is present, otherwise the upstream rejects the whole request.

reasoning_effort'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'

Reasoning effort level. The accepted values follow the model generation; the list here is the union. minimal belongs to GPT-5.4 / 5.5 and is gone from GPT-5.6 on; xhigh and max are the reverse, 5.6 and later only. none means no reasoning at all. Passing a level a given model does not know is rejected upstream — we do not gate it. none is translated into each vendor's "thinking off": no thinking block for Anthropic, thinkingBudget: 0 for Gemini. The other levels convert to thinking.budget_tokens for Anthropic and to thinkingLevel for Gemini.

userstring

End-user identifier, used upstream for abuse detection. Written to metadata.user_id for Anthropic. It also drives session affinity: passing it keeps one conversation on one provider, which is what makes prompt caching hit. OpenAI is replacing it with safety_identifier plus prompt_cache_key. We accept both and user keeps working; but if you have already moved to safety_identifier, switch session affinity to prompt_cache_key — safety_identifier is passed through untouched and takes no part in routing.

prompt_cache_keystring

Session key, taking precedence over user. Requests sharing a value are routed to the same provider so the upstream prompt cache hits. Without it we infer the session from the system prompt and the first message.

metadataobject

Free-form key/value pairs passed through to the upstream.

storeboolean

Whether the upstream should retain this conversation. Passed through unchanged; we do not retain request bodies ourselves.

service_tier'auto' | 'default' | 'flex' | 'scale' | 'priority' | 'fast'

Service tier. Not supported — we forward it to no upstream, on either path. Sending it is not an error. What was stripped is reported back: amux.droppedParams in the body, or the x-amux-dropped-params header when streaming.

verbosity'low' | 'medium' | 'high'

Output verbosity, available from the GPT-5 family on. Written to text.verbosity for Responses (different place, same thing). Anthropic and Gemini have no equivalent, so it is dropped there with a note.

safety_identifierstring

End-user identifier; OpenAI uses it in place of user for abuse detection. Passed through unchanged, not carried across protocols by default — the other vendors have no equivalent field. Note that it takes no part in session affinity: sending only this and no prompt_cache_key lets one conversation land on different providers, and the upstream prompt cache misses every time.

prompt_cache_retention'in_memory' | '24h'

How long prompt cache entries survive. in_memory is minutes to an hour, 24h keeps them up to a day. This is the field for models before gpt-5.6; 5.6 and later use prompt_cache_options. Passed through unchanged, no effect on pricing, not carried across protocols by default.

predictionobject

Predicted Outputs, { type: "content", content }. Cuts latency noticeably when most of the output is known ahead of time (editing a few lines in a file). Passed through unchanged, not carried across protocols by default.

web_search_optionsobject

Built-in web search, { user_location, search_context_size }. Passed through to upstreams that support it, not carried across protocols by default — the built-in tools have entirely different shapes per vendor and do not map onto one another.

moderationobject

Moderation configuration, { model, policy }. Passed through unchanged, not carried across protocols by default.

Example request

{
  "model": "anthropic/claude-opus-5",
  "messages": [
    {
      "role": "user",
      "content": "Hello!"
    }
  ]
}

Response

Inference succeeded. model comes back as the canonical ID — the same value you sent.

idstring

The ID of this completion.

objectstring

Object type; always chat.completion.

modelstring

The Amux model ID — the same value you sent.

Example response

{
  "id": "chatcmpl-8f3c1a",
  "object": "chat.completion",
  "model": "anthropic/claude-opus-5",
  "choices": [
    {
      "message": {
        "role": "user",
        "content": "Hello!"
      },
      "finish_reason": "stop"
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.