curl --request POST \
--url https://api.example.com/v1/responses \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"input": "<string>"
}
'{
"created_at": 123,
"id": "<string>",
"model": "<string>",
"object": "response",
"output": [
{
"content": [
{
"text": "<string>",
"type": "output_text",
"annotations": [
{
"end_index": 123,
"start_index": 123,
"title": "<string>",
"type": "<string>",
"url": "<string>"
}
]
}
],
"id": "<string>",
"role": "assistant",
"status": "completed",
"type": "message"
}
],
"status": "completed",
"error": {
"message": "<string>",
"code": "<string>",
"type": "<string>"
},
"usage": {
"input_tokens": 123,
"output_tokens": 123,
"total_tokens": 123,
"cost": {
"currency": "USD",
"input_cost": 123,
"output_cost": 123,
"total_cost": 123,
"cache_creation_cost": 123,
"cache_read_cost": 123,
"tool_calls_cost": 123
},
"input_tokens_details": {
"cache_creation_input_tokens": 123,
"cache_read_input_tokens": 123
},
"tool_calls_details": {}
}
}Generate a response for the provided input with optional web search and reasoning.
curl --request POST \
--url https://api.example.com/v1/responses \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"input": "<string>"
}
'{
"created_at": 123,
"id": "<string>",
"model": "<string>",
"object": "response",
"output": [
{
"content": [
{
"text": "<string>",
"type": "output_text",
"annotations": [
{
"end_index": 123,
"start_index": 123,
"title": "<string>",
"type": "<string>",
"url": "<string>"
}
]
}
],
"id": "<string>",
"role": "assistant",
"status": "completed",
"type": "message"
}
],
"status": "completed",
"error": {
"message": "<string>",
"code": "<string>",
"type": "<string>"
},
"usage": {
"input_tokens": 123,
"output_tokens": 123,
"total_tokens": 123,
"cost": {
"currency": "USD",
"input_cost": 123,
"output_cost": 123,
"total_cost": 123,
"cache_creation_cost": 123,
"cache_read_cost": 123,
"tool_calls_cost": 123
},
"input_tokens_details": {
"cache_creation_input_tokens": 123,
"cache_read_input_tokens": 123
},
"tool_calls_details": {}
}
}Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Input content - either a string or array of input messages
System instructions for the model
ISO 639-1 language code for response language
Maximum tokens to generate
x >= 1Maximum number of research loop steps. If provided, overrides the preset's max_steps value. Must be >= 1 if specified. Maximum allowed is 10.
1 <= x <= 10Model ID in provider/model format (e.g., "xai/grok-4-1", "openai/gpt-4o"). If models is also provided, models takes precedence. Required if neither models nor preset is provided.
Model fallback chain. Each model is in provider/model format. Models are tried in order until one succeeds. Max 5 models allowed. If set, takes precedence over single model field. The response.model will reflect the model that actually succeeded.
1 - 5 elementsPreset configuration name (e.g., "sonar-pro", "sonar-reasoning"). Pre-configured model with system prompt and search parameters. Required if model is not provided.
Show child attributes
Specifies the desired output format for the model response
Show child attributes
If true, returns SSE stream instead of JSON
Tools available to the model
Show child attributes
Successful response. Content type depends on stream parameter:
stream: false (default): application/json with Responsestream: true: text/event-stream with SSE eventsNon-streaming response returned when stream is false
Object type in API responses
response Show child attributes
Status of a response or output item
completed, failed, in_progress Show child attributes
Show child attributes
Was this page helpful?