Sign in
beta.responses

Create a response

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

post/responses

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
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_idstring nullable
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
service_tier'auto' | 'default' | 'flex' | 'priority' | 'scale' | 'null' nullable
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' | '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

Example response

{
  "created_at": 1704067200,
  "error": 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,
  "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