PAI

API reference

Responses

An OpenAI-compatible Responses surface for text, images, tools and reasoning. It is stateless by default; opt in with store: true and continue with a PAI previous_response_id.

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

Authentication

Authenticate every request with a Team API key.

Authorization: Bearer $PAI_API_KEY

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

Create a response

This minimal request returns one completed Response object.

curl https://router.omnitools.ai/v1/responses \
  -H "Authorization: Bearer $PAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "claude-fable-5",
  "input": "Summarize why deterministic errors matter in one sentence.",
  "max_output_tokens": 160
}'

Request parameters

Only the parameters below are accepted. Limits are validated before an upstream call begins.

ParameterRequirementDescription
modelRequiredStable PAI model ID from the model catalog.
inputRequiredA text string or an array of supported input items.
instructionsOptionalA leading developer instruction. Do not also place another system or developer instruction in input.
max_output_tokensOptionalPositive integer. Router also enforces the selected model's output limit.
temperatureOptionalNumber from 0 through 2.
top_pOptionalNumber from 0 through 1.
streamOptional · default falseReturns typed server-sent events when true.
storeOptional · default falseWith true, saves PAI canonical state for GET, DELETE and later continuation.
previous_response_idOptionalContinues from a stored PAI Response in the same Team. The current model may differ; prior instructions are not inherited.
toolsOptionalUp to 128 functions after namespace expansion. Supports function, namespace and custom tools; web_search is accepted only with external_web_access: false.
tool_choiceOptionalauto, none, required, or a named function/custom tool. Namespace functions include namespace.
parallel_tool_callsOptional · default trueAllows the model to request multiple functions in one turn.
reasoningOptionaleffort accepts none through max; summary accepts auto, concise or detailed; context accepts all_turns or current_turn.
includeOptionalCompatibility form: exactly ['reasoning.encrypted_content'].
prompt_cache_keyOptionalA validated non-empty compatibility key.
client_metadataOptionalUp to 32 bounded string entries used as compatibility metadata.
service_tierOptionalValidated compatibility value: auto, default, flex or priority.
stream_optionsOptionalAccepts the compatibility boolean include_obfuscation.
textOptionalAccepts verbosity: low, medium or high. text.format remains unsupported.

Input items and conversation history

Replay prior items when stateless, or use store: true and previous_response_id. Stored state is Team-owned, branchable and independent from internal routing.

Message items

Roles are system, developer, user and assistant. Text parts use text, input_text or output_text; user input accepts input_image by URL or data URL. Images require a route with verified image support.

Function and custom items

function_call may include namespace. custom_tool_call carries string input; each output item reuses its call_id and may return input_text or input_image parts. id and status are accepted replay metadata.

Codex tools

A developer additional_tools item may declare custom and namespace tools. PAI preserves their public identities while translating them to upstream functions. Hosted web search is never executed.

Reasoning and integrity

Reasoning accepts summary_text entries and optional encrypted_content replay metadata. Call IDs stay unique and every pending call requires a matching output before conversation continues.

Automatic routing

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

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, Content-Type is text/event-stream. Each event has a type and monotonically increasing sequence_number.

  • response.created and response.in_progress open the Response.
  • response.output_item.added and response.content_part.added open text or function output.
  • response.output_text.delta and response.function_call_arguments.delta carry incremental content.
  • response.output_text.done, response.function_call_arguments.done, response.content_part.done and response.output_item.done close output.
  • response.completed or response.incomplete is the terminal success state; response.failed is the terminal stream error.

Response object

The public model ID is preserved. Stored Responses can be retrieved or deleted at /v1/responses/{response_id}; deleting a node also deletes its descendants.

Minimal response
{
  "id": "resp_…",
  "object": "response",
  "created_at": 1783900800,
  "completed_at": 1783900801,
  "status": "completed",
  "error": null,
  "incomplete_details": null,
  "model": "claude-fable-5",
  "output": [
    {
      "id": "msg_…",
      "type": "message",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "…",
          "annotations": []
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 12,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 24,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 36
  }
}

Unsupported parameters

The following recognized Responses fields are explicitly rejected.

backgroundconversationmax_tool_callsmetadatapromptprompt_cache_retentionsafety_identifiertop_logprobstruncationuser

Any unlisted top-level field returns unknown_parameter. Text parts reject annotations and logprobs. Files, audio, computer use and hosted tool execution are unsupported; images are limited to user input and tool output and are 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.

HTTPRouter codeDescription
400invalid_parameterThe JSON shape, parameter value, protocol header or requested feature is invalid.
401invalid_api_keyThe API key is missing, malformed, expired, revoked or unknown.
402insufficient_creditsThe Team has no available Credits for a new request.
404model_not_foundThe requested model is unavailable.
413payload_too_largeThe JSON request body exceeds 8 MiB.
429api_key_spend_limit_exceededThe API key reached one of its rolling spend limits.
502upstream_error / invalid_upstream_responseModel execution was rejected or returned an invalid response.
503upstream_unavailable / route_unavailableNo 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.