API reference

Messages

An Anthropic-compatible, stateless Messages surface for Claude Code, text or image input, tools and extended thinking.

POST https://router.omnitools.ai/v1/messages

Authentication and version

Send the Team API key and the supported Anthropic protocol version.

x-api-key: $PAI_API_KEY · anthropic-version: 2023-06-01

Authorization: Bearer is also accepted; dual credentials must match. Content-Type is application/json. Claude Code may use ?beta=true; beta-gated fields require anthropic-beta.

Create a message

max_tokens is required for every Messages request.

curl https://router.omnitools.ai/v1/messages \
  -H "x-api-key: $PAI_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "claude-fable-5",
  "max_tokens": 160,
  "messages": [
    {
      "role": "user",
      "content": "Name one property of a clear API contract."
    }
  ]
}'

Request parameters

The Claude Code native and beta envelope is accepted explicitly. Beta-gated fields require a valid anthropic-beta header.

Parameter	Requirement	Description
model	Required	Stable PAI model ID from the model catalog.
max_tokens	Required	Positive output-token limit below the selected model's maximum.
messages	Required	1–100,000 user, assistant or system messages with supported content blocks. A system role inside messages requires native Messages.
system	Optional	A non-empty string or array of text blocks used as the leading instruction.
stop_sequences	Optional	Up to four non-empty strings. The selected model route must support stop sequences.
temperature	Optional	Number from 0 through 1.
top_p	Optional	Number from 0 through 1.
stream	Optional · default false	Returns named Anthropic server-sent events when true.
tools	Optional	Up to 128 tools with object input_schema. strict is beta-gated; allowed_callers, cache_control, defer_loading, eager_input_streaming and input_examples also require native Messages.
tool_choice	Optional	Object type auto, any, none or tool. auto, any and tool accept disable_parallel_tool_use.
thinking	Optional	disabled, adaptive, or enabled with budget_tokens of at least 1024 and less than max_tokens. display is beta-gated.
cache_control / container / context_management / mcp_servers / output_config	Optional · beta	Claude Code envelope fields forwarded unchanged through a native Messages route.
inference_geo / metadata / service_tier / top_k / user_profile_id	Optional · native	Native Anthropic envelope fields forwarded unchanged through a native Messages route.

Content blocks and tool turns

Messages preserves Anthropic native shapes when their semantics require a native route; the common text/tool subset may use a compatible route.

User content

Accepts text, tool_result and image blocks. Images use URL sources or JPEG, PNG, GIF or WebP base64 and require a route with verified image support.

Assistant content

Accepts text, thinking, redacted_thinking and tool_use. Native routes preserve protocol extension blocks, cache_control, citations and caller; cache_control and caller are beta-gated.

Tool definitions

Custom tools require object input_schema. Native server-tool definitions and blocks round-trip opaquely; PAI does not execute them. strict and listed Claude Code fields are beta-gated.

Extended thinking

adaptive and enabled thinking allow only auto or none tool choice. adaptive requires native Messages; thinking.display also requires the beta header.

Native semantics

Native-only fields, a system role inside messages and image tool results select a native Messages route. Router never performs a lossy Chat Completions downgrade for them.

Automatic routing

Router prefers native Messages. Common semantics may use a compatible route; native-only Claude Code or Anthropic semantics restrict selection to native Messages routes.

Routing is automatic and private. Router first prefers native support for the requested protocol, then ranks compatible routes by recent availability and internal cost. Fallback does not change the public model ID or price.

Streaming events

With stream: true, every SSE event name matches the type in its JSON payload.

message_start opens the message; ping may appear while it is active.
content_block_start opens text, thinking, redacted_thinking, tool or native extension output.
content_block_delta carries standard deltas and preserves native protocol extensions.
content_block_stop closes the current block.
message_delta reports stop_reason and terminal usage; message_stop ends the stream.
error is the terminal stream failure event and preserves the native error type and message.

Message object

Native content preserves text, thinking, redacted_thinking, tool and protocol extension blocks. Router rewrites only its public id and model; usage, stop_details and unknown extensions remain intact.

Minimal response

{
  "id": "msg_…",
  "type": "message",
  "role": "assistant",
  "model": "claude-fable-5",
  "content": [
    {
      "type": "text",
      "text": "…"
    }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0,
    "output_tokens": 24,
    "output_tokens_details": {
      "thinking_tokens": 0
    }
  }
}

Unsupported parameters

Accepted native fields are not silently dropped. PAI does not execute hosted tools itself; eligible native routes may round-trip opaque server-tool definitions, blocks and deltas.

document input blocksRouter-hosted tool execution

Any unlisted top-level field returns unknown_parameter. Documents and unrecognized user input blocks remain unsupported. Native-only fields require an eligible Messages route, images require verified route capability, and beta-gated fields require anthropic-beta.

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, revoked 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.