Pular para o conteúdo principal
POST
Guia relacionado: guia da Responses API. Consulte o guia da Responses API para um passo a passo com exemplos.
Este endpoint implementa a especificação OpenResponses, uma interface de LLM interoperável e multiprovedor. O Toqan Router estende a especificação com recursos da plataforma, como variáveis, memória, identidade e ferramentas do Toqan Router. Para um guia completo com exemplos, consulte a documentação da Responses API. Para a continuação de function tools, consulte o guia passo a passo.

Autorizações

Authorization
string
header
obrigatório

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Corpo

application/json
background
boolean

If true, the response runs asynchronously in the background.

cache
object

Exact-match response cache configuration for this request.

cache_control
Cache control · object

Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request.

context_management
object[] | null

Context management entries. One compaction entry summarizes history older than compact_threshold into a single item. See the Context Compaction guide.

conversation
object

Conversation context for multi-turn interactions.

fallback_on_codes
integer<int64>[] | null

HTTP status codes that trigger fallback. Defaults to [408,429,500,502,503,504,529]. Each code must be unique and between 400 and 599.

Maximum array length: 20
fallbacks
object[] | null

Fallback models to try if the primary model fails. Each entry specifies a model in provider/model format.

frequency_penalty
number<double>

Penalize new tokens based on their frequency in the text so far. Between -2.0 and 2.0.

guardrails
object[]

Guardrails to evaluate the request against.

identity
object

Identity/contact information for the end-user.

include
string[]

Additional fields to include in the response. Use web_search_call.action.sources to add source URLs and titles to a web search action, or web_search_call.results for detailed results. See the Web search guide.

input

Input to the model: a string or an array of input items (messages, files, etc.).

instructions
string

System prompt / instructions for the model.

integration_id
string

Integration ID used to resolve provider credentials for this request.

limits
object

Bound agent-loop execution. Fields: max_iterations (LLM turns), max_execution_time (seconds), max_cost (USD; send 0 to disable a manifest-configured cap), max_depth (sub-agent nesting), tool_timeout (seconds). Body values override agent-manifest defaults.

load_balancer
object

Load balancing configuration for selecting among multiple models.

max_output_tokens
integer<int64>

Maximum number of tokens in the response output.

max_tool_calls
integer<int64>

Maximum number of tool call rounds in the agentic loop.

memory
object

Attach a memory store entity to enable persistent memory across requests. See Memory Stores documentation for setup.

metadata
object

Developer-defined key-value pairs attached to the response (OpenAI spec: Map<string, string>). Non-string values are rejected with a 400.

model
string

The model to use in provider/model format (e.g. openai/gpt-4o). Use agent/<key> to invoke a pre-configured agent from this platform.

parallel_tool_calls
boolean

Whether to allow parallel tool calls.

plugins
object[] | null

Request-scoped transforms applied to the text exchanged with the model. Supports pii_redaction, which replaces PII with placeholders before the provider sees it and restores the original values in the response; response_healing, which repairs malformed JSON in non-streaming model output; and trace_scrubbing, which removes selected sensitive fields from exported traces.

presence_penalty
number<double>

Penalize new tokens based on their presence in the text so far. Between -2.0 and 2.0.

previous_response_id
string

The ID of a previous response to continue from. Requires store to be true (default) on the original response.

prompt_cache_key
string

Key for prompt caching across requests.

prompt_cache_options
object

OpenAI prompt cache options. GPT-5.6 and later support ttl=30m (default) or 12h. 12h cache writes cost twice the 30m rate.

reasoning
object

Configure reasoning behavior. Set effort (none, minimal, low, medium, high, xhigh, max) to control how much the model thinks before answering. Higher effort means more reasoning tokens and better answers for complex tasks, at higher cost.

retry
object

Retry configuration. Specify the number of retries and which HTTP status codes should trigger a retry.

safety_identifier
string

Safety identifier for content filtering.

security
object

Trace masking configuration for request and response data.

service_tier
enum<string>

Processing mode for the request. Ultrafast is available for GPT-6 Astra on US/global processing. Fast uses premium low-latency processing; priority remains a backward-compatible alias.

Opções disponíveis:
auto,
default,
flex,
fast,
ultrafast,
scale,
priority
speed
enum<string>

Inference speed for direct Anthropic models. Fast mode is available on Claude Opus 4.8, Opus 5, and Opus 5.5 at premium pricing, and cannot be combined with batch or priority processing.

Opções disponíveis:
standard,
fast
stop_sequences
string[]

Custom text sequences that cause the model to stop generating. Forwarded to providers that support it (e.g. Anthropic); ignored otherwise.

store
boolean

Whether to persist the response (default: true). When false, the response cannot be retrieved later and previous_response_id will not work for follow-up requests.

stream
boolean

If true, returns a stream of server-sent events.

stream_options
object
temperature
number<double>

Sampling temperature between 0 and 2.

template_engine
enum<string>

Template engine for variable substitution in instructions. Defaults to the agent manifest's engine when invoking an agent, otherwise text.

Opções disponíveis:
text,
jinja,
mustache
text
object

Configuration for text output.

thinking
object

Extended thinking configuration for Google Gemini and Anthropic models. Carries type, budget_tokens, and thinking_level. See the Reasoning guide.

thread
object

Thread for grouping related requests.

timeout
object

Provider call timeout configuration in milliseconds.

tool_choice

How the model should use the provided tools. Can be a string shorthand or a specific function selector.

Opções disponíveis:
auto,
none,
required
tools
(Function · object | Custom · object | Advisor · object | Subagent · object | Toqan Router Tool · object | MCP Tool · object)[]

Tools available to the model.

A tool definition. The "type" field determines the tool kind.

top_k
integer<int64>

Only sample from the top K options for each subsequent token. Forwarded to providers that support it (e.g. Anthropic); ignored otherwise.

top_logprobs
integer<int64>

Number of most likely tokens to return at each position.

top_p
number<double>

Nucleus sampling parameter.

variables
object

Template variables for prompt substitution. Plain values fill {{variable}} placeholders in instructions. For secrets, use {"secret": true, "value": "sensitive-data"} — secrets are automatically passed to platform tools (Python, HTTP, MCP) and redacted from traces.

Resposta

Returns a response object or a stream of events.

background
boolean
obrigatório
completed_at
integer<int64> | null
obrigatório
created_at
integer<int64>
obrigatório
error
object | null
obrigatório
frequency_penalty
number<double>
obrigatório
id
string
obrigatório
incomplete_details
object | null
obrigatório
input
any[] | null
obrigatório

Always null. Retained for compatibility with older SDKs; input content is not returned.

instructions
string | null
obrigatório
max_output_tokens
integer<int64> | null
obrigatório
max_tool_calls
integer<int64> | null
obrigatório
metadata
object
obrigatório

Developer-defined key-value pairs attached to the response (OpenAI spec: Map<string, string>).

model
string
obrigatório
object
string
obrigatório

Always "response"

output
any[] | null
obrigatório

Array of output items (messages, function calls, reasoning, etc.)

parallel_tool_calls
boolean
obrigatório
presence_penalty
number<double>
obrigatório
previous_response_id
string | null
obrigatório
prompt_cache_key
string | null
obrigatório
prompt_cache_options
object | null
obrigatório
prompt_cache_retention
string | null
obrigatório
reasoning
object | null
obrigatório
safety_identifier
string | null
obrigatório
service_tier
enum<string>
obrigatório
Opções disponíveis:
auto,
default,
flex,
fast,
ultrafast,
scale,
priority
status
enum<string>
obrigatório
Opções disponíveis:
queued,
in_progress,
completed,
failed,
incomplete
store
boolean
obrigatório
temperature
number<double>
obrigatório
text
any
obrigatório

Text output configuration including format and verbosity

tool_choice
any
obrigatório

Tool choice setting: "auto", "none", "required", or a specific function

tools
any[] | null
obrigatório

Array of tool configurations used in this response

top_logprobs
integer<int64>
obrigatório
top_p
number<double>
obrigatório
truncation
enum<string>
obrigatório
Opções disponíveis:
disabled,
auto
usage
object | null
obrigatório
user
string | null
obrigatório
conversation
object
memory
object
telemetry
object

OpenTelemetry trace and span identifiers for this response.

top_k
integer<int64>

Only sample from the top K options for each subsequent token. Present only when set on the request.

variables
object