Responses

Create a response

Changed on

Creates a streaming or non-streaming response using OpenResponses API format

post/responses

Request

  • Base URL: https://openrouter.ai/api/v1
  • URL: https://openrouter.ai/api/v1/responses
  • Auth: HTTP bearer

Headers

X-OpenRouter-Metadata'disabled' | 'enabled'

Opt-in level for surfacing routing metadata on the response under openrouter_metadata.

Example:enabled

Opt-in to surface routing metadata on the response under openrouter_metadata. Defaults to disabled. The legacy header X-OpenRouter-Experimental-Metadata is also accepted for backward compatibility.

Request body

backgroundboolean nullable
frequency_penaltynumber double nullable
image_configImageConfig

Provider-specific image configuration options. Keys and values vary by model/provider. See https://openrouter.ai/docs/guides/overview/multimodal/image-generation for more details.

includeResponseIncludesEnum[] nullable
instructionsstring nullable
max_output_tokensinteger nullable
max_tool_callsinteger nullable

Maximum number of server-tool (e.g. openrouter:web_search) agent steps the model may take during a request. Defaults to 30, which is also the maximum. Ignored when stop_server_tools_when is set.

metadataRequestMetadata nullable

Metadata key-value pairs for the request. Keys must be ≤64 characters and cannot contain brackets. Values must be ≤512 characters. Maximum 16 pairs allowed.

modalitiesOutputModalityEnum[]

Output modalities for the response. Supported values are "text" and "image".

modelstring
modelsstring[]
parallel_tool_callsboolean nullable
presence_penaltynumber double nullable
previous_response_idunknown
prompt_cache_keystring nullable
route'fallback' | 'sort' | 'null' nullable

DEPRECATED Use providers.sort.partition instead. Backwards-compatible alias for providers.sort.partition. Accepts legacy values: "fallback" (maps to "model"), "sort" (maps to "none").

safety_identifierstring nullable

Recommended per-end-user identifier for abuse isolation. Use a stable ID, hash, or pseudonym. When a provider requires a user identity, OpenRouter folds it into the hashed identity sent upstream and never forwards it raw. If omitted, requests use an account-level identity, so provider policy blocks can affect the whole account.

service_tier'auto' | 'default' | 'fast' | 'flex' | 'priority' | 'scale' | 'ultrafast' | 'null' nullable

The service tier to use for processing this request. fast is accepted as an alias for priority. ultrafast prefers ultrafast endpoints and falls back to priority, then default endpoints.

session_idstring

A unique identifier for grouping related requests (e.g., a conversation or agent workflow). When provided, OpenRouter uses it as the sticky routing key, routing all requests in the session to the same provider to maximize prompt cache hits. Also used for observability grouping. If provided in both the request body and the x-session-id header, the body value takes precedence. Maximum of 256 characters.

storefalse
streamboolean
temperaturenumber double nullable
top_kinteger
top_logprobsinteger nullable
top_pnumber double nullable
truncation'auto' | 'disabled' | 'null' nullable
userstring

A unique identifier representing your end-user, which helps distinguish between different users of your app. This allows your app to identify specific users in case of abuse reports, preventing your entire app from being affected by the actions of individual users. Maximum of 256 characters.

Example request

{
  "input": [
    {
      "content": "Hello, how are you?",
      "role": "user",
      "type": "message"
    }
  ],
  "model": "anthropic/claude-4.5-sonnet-20250929",
  "temperature": 0.7,
  "tools": [
    {
      "description": "Get the current weather in a given location",
      "name": "get_current_weather",
      "parameters": {
        "properties": {
          "location": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "type": "function"
    }
  ],
  "top_p": 0.9
}

Response

Successful response

backgroundboolean nullable
completed_atinteger nullable required
created_atinteger required
frequency_penaltynumber double nullable required
idstring required
max_output_tokensinteger nullable
max_tool_callsinteger nullable
metadataRequestMetadata nullable required

Metadata key-value pairs for the request. Keys must be ≤64 characters and cannot contain brackets. Values must be ≤512 characters. Maximum 16 pairs allowed.

modelstring required
object'response' required
output_textstring
parallel_tool_callsboolean required
presence_penaltynumber double nullable required
previous_response_idstring nullable
prompt_cache_keystring nullable
safety_identifierstring nullable
service_tier'auto' | 'default' | 'flex' | 'priority' | 'scale' | 'ultrafast' | 'null' nullable
status'completed' | 'incomplete' | 'in_progress' | 'failed' | 'cancelled' | 'queued' required
storeboolean
temperaturenumber double nullable required
top_logprobsinteger
top_pnumber double nullable required
truncation'auto' | 'disabled' | 'null' nullable
userstring nullable
error_type'context_length_exceeded' | 'max_tokens_exceeded' | 'token_limit_exceeded' | 'string_too_long' | 'authentication' | 'permission_denied' | 'payment_required' | 'rate_limit_exceeded' | 'provider_overloaded' | 'provider_unavailable' | 'invalid_request' | 'invalid_prompt' | 'not_found' | 'precondition_failed' | 'payload_too_large' | 'unprocessable' | 'content_policy_violation' | 'refusal' | 'invalid_image' | 'image_too_large' | 'image_too_small' | 'unsupported_image_format' | 'image_not_found' | 'image_download_failed' | 'server' | 'timeout' | 'unmapped'

Canonical OpenRouter error type, stable across all API formats

Example response

{
  "completed_at": 1704067210,
  "created_at": 1704067200,
  "error": null,
  "frequency_penalty": null,
  "id": "resp-abc123",
  "incomplete_details": null,
  "instructions": null,
  "max_output_tokens": null,
  "metadata": null,
  "model": "gpt-4",
  "object": "response",
  "output": [
    {
      "content": [
        {
          "annotations": [],
          "text": "Hello! How can I help you today?",
          "type": "output_text"
        }
      ],
      "id": "msg-abc123",
      "role": "assistant",
      "status": "completed",
      "type": "message"
    }
  ],
  "parallel_tool_calls": true,
  "presence_penalty": null,
  "status": "completed",
  "temperature": null,
  "tool_choice": "auto",
  "tools": [],
  "top_p": null,
  "usage": {
    "input_tokens": 10,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 25,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 35
  }
}

Changes

  • f74f1bdec913Revision changes
    • info

      added the new optional request property

  • 412686c1d2c7Revision changes
    • info

      added armor discriminator mapping keys to the / request property

    • info

      added to the / request property oneOf list

    • info

      added the optional property / to the response with the status (media type: application/json)

    • info

      added the optional property //////// to the response with the status (media type: text/event-stream)

    • info

      added the optional property //////// to the response with the status (media type: text/event-stream)

    • info

      added the optional property //////// to the response with the status (media type: text/event-stream)

    • info

      added the optional property //////// to the response with the status (media type: text/event-stream)

    • info

      added the optional property //////// to the response with the status (media type: text/event-stream)