API reference

Chat Completions

An OpenAI-compatible, stateless messages API for multi-turn text or image input, function calling and reasoning.

POST https://router.omnitools.ai/v1/chat/completions

Authentication

Authenticate every request with a Team API key.

Authorization: Bearer $OTRouter_API_KEY

Content-Type must be application/json. Query parameters are not accepted.

Create a chat completion

Send the full conversation history required for this turn.

curl https://router.omnitools.ai/v1/chat/completions \
  -H "Authorization: Bearer $OTRouter_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "claude-fable-5",
  "messages": [
    {
      "role": "user",
      "content": "Give one practical rule for reliable API clients."
    }
  ],
  "max_completion_tokens": 160
}'

Request parameters

Only the parameters below are accepted. Unsupported OpenAI fields return an error.

Parameter	Requirement	Description
model	Required	Stable OTRouter model ID from the model catalog.
messages	Required	Non-empty array of supported system, developer, user, assistant and tool messages. User content may contain image_url parts.
max_completion_tokens	Optional	Positive output-token limit. Do not combine with max_tokens.
max_tokens	Optional	Supported compatibility alias for max_completion_tokens.
temperature	Optional	Number from 0 through 2.
top_p	Optional	Number from 0 through 1.
stop	Optional	One string or up to four strings. The selected model route must support stop sequences.
stream	Optional · default false	Returns data-only server-sent event chunks when true.
stream_options	Optional	With streaming, accepts include_usage. include_obfuscation is not supported.
tools	Optional	Up to 128 unique function tools in the OpenAI function wrapper.
tool_choice	Optional	auto, none, required, or a named function object.
parallel_tool_calls	Optional · default true	Allows multiple function calls in one assistant turn.
reasoning_effort	Optional	none, minimal, low, medium, high, xhigh or max, subject to model support.
thinking	Optional	{ type: 'enabled' } or { type: 'disabled' }. Must not conflict with reasoning_effort.
n	Optional · 1 only	OTRouter returns exactly one choice.
store	Optional · false only	When present, it must be false. OTRouter does not store conversation state.

Messages and tools

Text, images and function calls can be replayed across turns. Provider-private reasoning is not returned or replayed; validated reasoning-token counts remain in usage. Image input uses only routes with verified image capability.

Instruction and user messages

System and developer messages are text-only and must form one leading instruction. User content accepts text plus image_url parts with URL/data URL and auto, low or high detail.

Assistant messages

Assistant content may be null when tool_calls is present. Provider-private reasoning_content/reasoning is not portable history; refusal must be null and annotations must be empty.

Tool results

A tool message requires text content and tool_call_id. It must answer a pending assistant function call before the conversation continues.

Function schema

Each tool uses type function and a function object with a unique name, optional description, JSON-object parameters and optional strict.

Automatic routing

The stable model ID is the only routing input. Internal route selection is automatic.

Routing is automatic and private. Router filters by the requested protocol and capabilities, then applies configured priority and internal cost. Fallback keeps the public model ID. Fixed-price models use their published model rates; supply-priced models use the applicable quote for the route actually used, so fallback may change the rate charged.

Streaming chunks

With stream: true, each SSE data line contains a chat.completion.chunk object.

Public delta chunks may contain assistant role, content, refusal or incremental tool_calls. Provider-private reasoning_content/reasoning is validated and stripped.
A finish_reason of stop, length, content_filter or tool_calls closes the choice. A complete function call is normalized to tool_calls if an upstream reports stop.
When stream_options.include_usage is true, a final usage chunk has no choices.
The stream terminates with data: [DONE].

Completion object

OTRouter returns exactly one choice and normalized cached-input and reasoning-token usage details.

Minimal response

{
  "id": "chatcmpl_…",
  "object": "chat.completion",
  "created": 1783900800,
  "model": "claude-fable-5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "…",
        "refusal": null,
        "annotations": []
      },
      "finish_reason": "stop",
      "logprobs": null
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "prompt_tokens_details": {
      "cached_tokens": 0
    },
    "completion_tokens": 24,
    "completion_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 36
  }
}

Unsupported parameters

The following recognized Chat Completions fields are explicitly rejected.

audiofrequency_penaltyfunction_callfunctionslogit_biaslogprobsmetadatamodalitiespredictionpresence_penaltyprompt_cache_keyprompt_cache_retentionresponse_formatsafety_identifierseedservice_tiertop_logprobsuserverbosityweb_search_options

Any unlisted top-level field returns unknown_parameter. Message name, assistant audio and legacy function_call, text-part annotations and logprobs, and stream_options.include_obfuscation are explicitly unsupported. Audio parts, structured output and multiple choices are not supported; images are user-only and capability-gated.

Errors

Responses and Chat Completions return message, type, param and code with x-request-id. Messages maps the HTTP status to the Anthropic error shape, omits code and also includes request-id.

HTTP	Router code	Description
400	invalid_parameter	The JSON shape, parameter value, protocol header or requested feature is invalid.
401	invalid_api_key	The API key is missing, malformed, expired, deleted or unknown.
402	insufficient_credits	The Team has no available Credits for a new request.
404	model_not_found	The requested model is unavailable.
413	payload_too_large	The JSON request body exceeds 8 MiB.
429	api_key_spend_limit_exceeded	The API key reached one of its rolling spend limits.
502	upstream_error / invalid_upstream_response	Model execution was rejected or returned an invalid response.
503	upstream_unavailable / route_unavailable	No eligible route completed the request before the routing deadline.

Keep x-request-id (or request-id for Messages) when contacting support or inspecting the request in Console.