Create a Model Response

Encountering errors? See the API Error Codes Reference for a complete list of error types and troubleshooting steps.

POST https://api.agipower.ai/v1/responses

The Create a Model Response endpoint is compatible with OpenAI’s Create a Model Response endpoint. It is used to create a single model response (supports text/image/file inputs; text or structured JSON outputs; built-in tools and function calling, etc.). Below is a list of all parameters that may be supported by different models. Parameter support varies by model; for the exact parameters supported by each model, see the model’s detail page.

Request headers

Authorization `string` Required

Bearer token authentication.

Content-Type `string` Required

Request content type. Default is application/json.

Request body

model `string` Required

The model ID for this inference call, in the format <provider>/<model_name>, e.g., openai/gpt-5. You can find it on each model’s detail page.

input `string | array` Optional

The content passed to the model.

`string`

Treated as plain-text input (equivalent to a single user text input).

`array` (Input item list)

Each element in the array is an Item (a context item). It can include messages, images, files, tool outputs, references, etc. Possible types include:

1. Input message `object`

type string Optional: fixed to message
role string Required: user / assistant / system / developer
content string | array Required: message content
- If string: plain text
- If array: a list of content parts (see Input content parts below)

Input content parts (possible input content part types)

Input text object

type string Required: input_text
text string Required: text content

Input image object

type string: input_image Required
detail string: high / low / auto Required: image processing detail level; affects token usage and recognition accuracy
file_id string Optional: ID of an uploaded file
image_url string (URL or data URL/base64) Optional: image URL or base64-encoded data

Input file object

type string: input_file Required
file_data string Optional: base64-encoded file data
file_id stringOptional: ID of an uploaded file
file_url stringOptional: file URL
filename stringOptional: file name

2. Item types overview

Input message `object`

type string Optional: fixed to message
role string Required: user / assistant / system / developer
status string Optional: in_progress / completed / incomplete item status
content string | array Required: message content
- If string: plain text
- If array: a list of content parts; each element can be input_text / input_image / input_file (same as above)

Output message (model output message) `object`

(Used when you “feed back the model’s previous output message item” into input.)

type stringRequired: message
role stringRequired: fixed to assistant
id stringRequired: unique ID of the output message
status stringRequired: in_progress / completed / incomplete
content arrayRequired: list of Output content parts (see below)

Output content parts (possible output content part types)

type stringRequired: output_text
text stringRequired: output text
annotations arrayRequired: annotations (see below)
logprobs arrayRequired: logprobs (see below)

annotations element types:

File citation object
- type stringRequired: file_citation
- file_id stringRequired: cited file ID
- filename stringRequired: cited file name
- index integerRequired: starting index position in the text
URL citation object
- type stringRequired: url_citation
- start_index integerRequired: starting index position of the citation in the text
- end_index integerRequired: ending index position of the citation in the text
- title stringRequired: cited page title
- url stringRequired: cited page URL
Container file citation object
- type stringRequired: container_file_citation
- container_id stringRequired: container file ID
- file_id stringRequired: actual cited file ID
- filename stringRequired: cited file name
- start_index integerRequired: starting index position of the citation in the text
- end_index integerRequired: ending index position of the citation in the text
File path object
- type stringRequired: file_path
- file_id stringRequired: file ID
- index integerRequired: index position in the list

logprobs (each element is logprob info for one token; field hierarchy below):

bytes arrayRequired: byte representation of the token
logprob numberRequired: token log probability
token stringRequired: token text
top_logprobs arrayRequired: most likely candidate tokens (each element includes bytes / logprob / token)

Refusal object

type stringRequired: refusal
refusal stringRequired: explanation for why the model refused to answer

Function tool call `object`

The model initiates a call to a function tool.

type string: function_call Required
call_id string Required: unique identifier for the function call
name string Required: name of the function to call
arguments string Required: function arguments as a JSON string
id string Optional: unique item ID
status string Optional: call status, in_progress / completed / incomplete

Function tool call output (function tool output) `object`

Send the result of executing the function back to the model (for the next step of reasoning).

type string: function_call_output Required
call_id stringRequired: corresponding function call identifier
output string | array Required: function execution result, either a string or a list of content parts
id string Optional: unique output item ID
status string Optional: output status, in_progress / completed / incomplete

When output is an array, elements can be input_text / input_image / input_file (same as above).

Custom tool call `object`

The model initiates a call to a “custom tool” (you must execute it on your side).

type string: custom_tool_callRequired
call_id stringRequired: unique identifier for the custom tool call
name stringRequired: name of the custom tool to call
input stringRequired: input passed to the tool
id string Optional: unique item ID

Custom tool call output (custom tool output) `object`

Send the execution result of the custom tool back to the model.

type string: custom_tool_call_outputRequired
call_id stringRequired: corresponding custom tool call identifier
output string | arrayRequired: tool result, either a string or a list of content parts
id stringOptional: unique output item ID

When output is an array, elements can be input_text / input_image / input_file (same as above).

Web search tool call `object`

type stringRequired: web_search_call
id stringRequired: unique ID for the web search tool call
status stringRequired
action objectRequired: describes what the web tool did in this call (search/open_page/find)

Possible action types

Search action object

type stringRequired: action type, fixed to search
query stringRequired: search query (deprecated)
queries arrayOptional: list of search queries
sources arrayOptional: list of sources
- each source:
  - type stringRequired: url
  - url stringRequired: source URL

Open page action object

type stringRequired: action type, fixed to open_page
url stringRequired: page URL to open

Find action object

type stringRequired: action type, fixed to find
url stringRequired: page URL to search
pattern stringRequired: search pattern or keyword

Computer tool call (Computer Use call) `object`

The model initiates a Computer Use action (you must execute it on your side). After execution, send results such as screenshots back via computer_call_output.

type stringRequired: computer_call
call_id string Required: unique identifier for the computer use call
action object Required: parameters for the specific computer action (see Action types below)
pending_safety_checks array Optional: list of safety checks pending user confirmation
- id string Optional: unique safety check identifier
- code string Optional: safety check code
- message string Optional: safety check message
id string Optional: unique item identifier
status string Optional: call status, in_progress (in progress) / completed (completed) / incomplete (incomplete)

Action types (possible `action` variants)

Click `object`

type string: click Required: action type, fixed to click
x number Required: click X coordinate (pixels)
y number Required: click Y coordinate (pixels)
button string Optional: mouse button, left / right / middle

Double click `object`

type string: double_click Required: action type, fixed to double_click
x integer Required: double-click X coordinate (pixels)
y integer Required: double-click Y coordinate (pixels)

Move `object`

type string: move Required: action type, fixed to move
x integer Required: target X coordinate (pixels)
y integer Required: target Y coordinate (pixels)

Screenshot `object`

type screenshot：screenshot Required: action type, fixed to screenshot

Drag `object`

type string: drag Required: action type, fixed to drag
path array Required: list of coordinates for the drag path
- x integer Required: X coordinate (pixels)
- y integer Required: Y coordinate (pixels)

Scroll `object`

type string: scroll Required: action type, fixed to scroll
x integer Optional: scroll anchor X (pixels; provided by some implementations)
y integer Optional: scroll anchor Y (pixels)
scroll_x integer Optional: horizontal scroll distance (pixels)
scroll_y integer Optional: vertical scroll distance (pixels)

Type `object`

type string: type Required: action type, fixed to type
text string Required: text to type

Keypress `object`

type string: keypress Required: action type, fixed to keypress
keys array Required: key combo to press, e.g. ["CTRL","L"] means Ctrl+L

Wait `object`

type string: wait Required: action type, fixed to wait

Computer tool call output (Computer Use output) `object`

type stringRequired: computer_call_output
call_id stringRequired: corresponding computer use call identifier
output object: output of the computer action (e.g., screenshots)
- type string: computer_screenshot: output type, fixed to computer screenshot
- file_id stringOptional: screenshot file ID
- image_url stringOptional: screenshot URL
acknowledged_safety_checks arrayOptional: list of acknowledged safety checks
- id stringOptional: acknowledged safety check identifier
- code stringOptional: acknowledged safety check code
- message stringOptional: acknowledged safety check message
id stringOptional: unique output item identifier
status stringOptional: output status, e.g. completed / failed

Local shell call (local shell call) `object`

type stringRequired: local_shell_call
id stringRequired: unique ID for the local shell call
call_id stringRequired: associated call ID
status stringRequired: call status, e.g. in_progress / completed / failed
action objectRequired: specific shell execution action
- type stringRequired: exec
- command arrayRequired: command arguments (array form)
- env mapRequired: environment variables for execution
- timeout_ms integerOptional: timeout (ms)
- user stringOptional: system user to run the command as
- working_directory stringOptional: working directory path

Local shell call output `object`

type stringRequired: local_shell_call_output
id stringRequired: unique ID for the output item
output stringRequired: command result output as a JSON string
status stringOptional: output status, e.g. completed / failed

Shell tool call `object`

type stringRequired: shell_call
call_id stringRequired: unique identifier for the shell call
id stringOptional: unique item ID
status stringOptional: call status, in_progress / completed / incomplete
action objectRequired: shell command execution config
- commands arrayRequired: list of shell commands to execute in order
- max_output_length integerOptional: maximum captured output length (stdout+stderr UTF-8)
- timeout_ms integerOptional: timeout (ms)

Shell tool call output `object`

type stringRequired: shell_call_output
call_id stringRequired: corresponding shell call identifier
id stringOptional: unique output item identifier
max_output_length integerOptional: maximum output length limit
output arrayRequired: list of output chunks; each element includes:
- stdout stringRequired: stdout content
- stderr stringRequired: stderr content
- outcome objectRequired: execution outcome (union type)
  - Timeout outcome object
    - type stringRequired: timeout: command timed out
  - Exit outcome object
    - type stringRequired: exit: command exited normally
    - exit_code integerRequired

Apply patch tool call (apply patch call) `object`

Used to create/delete/update files via a diff patch.

type stringRequired: apply_patch_call
call_id stringRequired: unique identifier for the apply patch call
id stringOptional: unique item identifier
status stringRequired: call status, in_progress / completed
operation objectRequired: specific file operation (union type: create/delete/update)

Possible operation types

Create file object

type stringRequired: create_file
path stringRequired: file path relative to the workspace root
diff stringRequired: unified diff patch content

Delete file object

type stringRequired: delete_file
path stringRequired: file path to delete

Update file object

type stringRequired: update_file
path stringRequired: file path to update
diff stringRequired: unified diff patch content

Apply patch tool call output `object`

type stringRequired: apply_patch_call_output
call_id stringRequired: corresponding apply patch call identifier
id stringOptional: unique output item identifier
status stringRequired: output status, completed / failed
output stringOptional: apply-patch logs or error description

MCP list tools `object`

type stringRequired: mcp_list_tools
id stringRequired: unique ID for the MCP list-tools call
server_label stringRequired: MCP server label
error stringOptional: error message when fetching tools (if any)
tools arrayRequired: available tools; each element includes:
- name stringRequired: tool name
- description stringOptional: tool description
- annotations objectOptional: additional tool annotations
- input_schema objectRequired: tool input JSON Schema

MCP approval request `object`

type stringRequired: mcp_approval_request
id stringRequired: unique ID for the approval request
server_label stringRequired: MCP server label
name stringRequired: requested tool name to run
arguments stringRequired: tool arguments as a JSON string

MCP approval response `object`

type stringRequired: mcp_approval_response
approval_request_id stringRequired: corresponding approval request ID
approve booleanRequired: whether to approve the tool call (true=approve, false=reject)
id stringOptional: unique response item ID
reason stringOptional: reason for approval or rejection

MCP tool call `object`

type stringRequired: mcp_call
id stringRequired: unique ID for the MCP tool call
server_label stringRequired: MCP server label
name stringRequired: tool name to call
arguments stringRequired: tool arguments as a JSON string
approval_request_id stringOptional: associated approval request ID (for subsequent approval response)
output stringOptional: tool output after execution
error stringOptional: tool execution error message
status stringOptional: call status, in_progress / completed / incomplete / calling / failed

Reasoning `object`

type stringRequired: reasoning
id stringRequired: unique ID for the reasoning content
summary arrayRequired: reasoning summary parts
- Summary text object
  - type stringRequired: summary_text
  - text stringRequired: summary text
content arrayOptional: full reasoning text parts
- Reasoning text object
  - type stringRequired: reasoning_text
  - text stringRequired: full reasoning text
encrypted_content stringOptional: encrypted full reasoning content (requires enabling via include)
status stringOptional: reasoning status, in_progress / completed / incomplete

Compaction item `object`

Generated by v1/responses/compact. Used to compress long conversations into an opaque encrypted summary and can be fed back into later input.

type stringRequired: compaction
id stringOptional: compaction item ID
encrypted_content stringRequired: compressed summary (encrypted, opaque)

3. Item reference `object`

Used to reference an existing item (internal identifier).

type stringRequired: item_reference
id stringOptional

instructions `string` Optional

System/developer instructions inserted into the context. When used with previous_response_id, it will not inherit the previous round’s instructions, making it easier to replace the system prompt.

previous_response_id `string` Optional

ID of the previous Response for continuing multi-turn conversations; cannot be used together with conversation.

conversation `string | object` Optional (default `null`)

Associates this response with a conversation. The conversation’s items will be prepended to this request’s input context, and after completion this request’s input/output will be automatically appended to the conversation.

Conversation ID string: unique conversation ID used to identify and reuse conversation history
Conversation object object
- id stringRequired: unique conversation ID for persistence and retrieval

prompt `object` Optional

Reference a prompt template and pass variables.

id string Required: prompt template ID
variables objectOptional: template variable key-value pairs for placeholder substitution
version stringOptional: prompt template version

include `array` Optional

Specifies additional output data to include in the response. Supported values include (string enum):

web_search_call.action.sources: include source info for web search calls
computer_call_output.output.image_url: include screenshot URL from Computer Use tool outputs
message.input_image.image_url: include image URLs in input messages
message.output_text.logprobs: include per-token log probabilities for output text
reasoning.encrypted_content: include encrypted reasoning content

max_output_tokens `integer` Optional

Caps the maximum tokens the response can generate (includes visible output tokens and reasoning tokens).

max_tool_calls `integer` Optional

Caps the total number of built-in tool calls that can be processed within this response (accumulated across tools).

parallel_tool_calls `boolean` Optional (default `true`)

Whether to allow parallel tool calls.

reasoning `object` Optional (reasoning models only)

Reasoning model configuration.

effort string Optional (default medium)
Controls reasoning intensity, affecting reasoning depth and compute time. Supported: none / minimal / low / medium / high / xhigh
summary string Optional
Reasoning summary level: auto / concise / detailed
generate_summary string (Deprecated)
Deprecated: use summary instead

text `object` Optional

Text output configuration (including structured output formats).

format object Optional: output format (default \{ "type": "text" \})
Possible types:
1. Text object
  - type stringRequired: text: plain text output
2. JSON schema object (Structured Outputs)
  - type stringRequired: json_schema: structured JSON output
  - name stringRequired: output format name identifier
  - schema objectRequired: JSON Schema defining the output structure
  - description string Optional: description of the output format
  - strict boolean Optional (default false): whether to strictly enforce the schema; when true, validation is enforced
3. JSON object object (legacy JSON mode)
  - type stringRequired: json_object: JSON object output
verbosity string Optional (default medium)
Constrains response verbosity. Lower values produce more concise responses; higher values produce more detailed responses. Supported values: low / medium / high

temperature `number` Optional (default `1`)

Sampling temperature, typically 0–2. Prefer tuning either this or top_p, not both.

top_p `number` Optional (default `1`)

Nucleus sampling parameter.

top_logprobs `integer` Optional

0–20. Number of most likely tokens to return at each position.

truncation `string` Optional (default `disabled`)

Context truncation strategy for handling prompts that exceed the model’s context window:

auto: when content exceeds the context window, automatically drop the earliest items from the start of the conversation to make room
disabled: disables auto-truncation; requests that exceed the context window will fail (400)

tools `array` Optional

Declares the list of tools the model is allowed to call in this request. The model may choose to call these tools as needed to enhance its capabilities.

Possible `tools[i]` types

Below are the supported tool type definitions. Each tool type has specific configuration parameters:

Function tool (function tool definition) `object`

type stringRequired: function: tool type, fixed to function tool
name stringRequired: unique function name identifier
parameters objectRequired: JSON Schema defining function parameters (structure + validation rules)
strict booleanRequired (default true): whether to strictly validate parameters against the schema
description string Optional: detailed function description to help the model decide when to use it

Web search (generally available) `object`

type string Required: web_search or web_search_2025_08_26
filters object Optional: result filters
- allowed_domains array[string] Optional (default []): allowed domain allowlist (subdomains allowed)
search_context_size string Optional (default medium): search context size level
user_location object Optional: approximate user location for localized results
- type string Required: approximate
- city string Optional
- country string Optional: 2-letter ISO (e.g. US)
- region string Optional
- timezone string Optional: IANA TZ (e.g. America/Los_Angeles)

Web search preview `object`

type stringRequired: web_search_preview or web_search_preview_2025_03_11
search_context_size string Optional: low / medium / high
user_location object Optional: user location
- type stringRequired: approximate
- city string Optional
- country string Optional (2-letter ISO)
- region string Optional
- timezone string Optional (IANA TZ)

Computer use preview (Computer Use tool) `object`

type string Required: computer_use_preview
display_width integer Required: display width (pixels)
display_height integer Required: display height (pixels)
environment string Required: environment type (e.g. browser / mac / windows / ubuntu)

Apply patch tool (apply patch) `object`

type stringRequired: apply_patch

MCP tool (remote MCP tool) `object` (if enabled)

type string Required: mcp
server_label string Required: MCP server label (for tool-call routing)
server_url string Optional: remote MCP server
authorization string Optional: OAuth access token (for remote MCP server or service connector)
allowed_tools array[string] | object Optional: allowed tools list or filter
- MCP allowed tools array[string]
- MCP tool filter object
  - read_only boolean Optional: filter by read-only tools
  - tool_names array[string] Optional: tool name allowlist
require_approval string | object Optional: which tools require approval (example uses never; supports finer granularity)
- string: always / never
- object: approval filter (schema in docs)

Shell tool (generic Shell) `object`

type string Required: shell

(Usually no extra configuration is needed; execution parameters are in the model output’s shell_call.action.)

Local shell tool (legacy local Shell) `object`

type string Required: local_shell

(The official guidance notes that local shell is legacy; for new use cases, shell is recommended.)

Custom tool (custom tool definition; non-function “free input / optionally constrained format”) `object`

type string Required: custom
name string Required: tool name
description string Optional: tool description
format object Optional: input format (defaults to free text)
- Text format object
  - type string Required: text
- Grammar format object
  - type string Required: grammar
  - syntax string Required: lark / regex
  - definition string Required: grammar definition

tool_choice `string | object` Optional

Controls how the model selects tools and whether it must call tools.

Tool choice mode `string`

none: do not call tools
auto: let the model decide
required: must call ≥1 tool

Allowed tools `object`

type stringRequired: allowed_tools
mode stringRequired: auto / required
tools arrayRequired: allowed tool set (e.g. \{ "type":"function","name":"get_weather" \}, etc.)

Hosted tool (force a built-in tool) `object`

type stringRequired: one of: / web_search_preview / computer_use_preview /

Function tool (force a specific function) `object`

type stringRequired: function
name stringRequired

MCP tool (force a specific MCP tool) `object`

type stringRequired: mcp
server_label stringRequired
name stringOptional

Custom tool (force a specific custom tool) `object`

type stringRequired: custom
name stringRequired

Specific apply patch tool choice (force the model to call apply_patch) `object`

type stringRequired: apply_patch

Specific shell tool choice (force the model to call Shell when a tool call is needed) `object`

type stringRequired: shell

store `boolean` Optional (default `true`)

Whether to store this Response for later retrieval.

stream `boolean` Optional (default `false`)

Whether to enable SSE streaming output.

stream_options `object` Optional (default `null`)

Streaming response options. Used only when stream: true.

include_usage boolean Optional: whether to include usage info in the stream

prompt_cache_key `string` Optional

A key to improve cache hit rate (replaces the legacy user field).

prompt_cache_retention `string` Optional

Prompt cache retention policy (e.g. 24h).

safety_identifier `string` Optional

A stable user identifier for safety/abuse detection (recommended to hash).

provider `object` Optional

Used to configure routing and failover strategies across multiple model providers (e.g., OpenAI, Anthropic, Google) for this request. If not configured, the project or model’s default routing strategy is used.

routing `object` Required

Routing strategy configuration that determines how requests are selected and distributed across multiple providers.

type `string` Required

Routing type. Supported values:

priority Select providers by priority order: try the first one, then try the next upon failure (can be combined with fallback).
round_robin Round-robin distribution: evenly distribute traffic across providers.
least_latency Lowest-latency first: choose the provider with the fastest response based on historical/real-time stats.

primary_factor `string` Optional

Primary factor when multiple providers are available. For example:

cost Prefer lower-cost providers
speed Prefer faster providers
quality Prefer higher-quality providers (e.g., stronger models / more stable)

Actual behavior combines with type. For example, when type = "priority", primary_factor mainly affects how priorities are ordered.

providers `array` Required

List of model providers that can participate in routing. Example: ["openai", "anthropic", "google"]

fallback `string` Optional

Failover strategy. When the currently selected provider fails (e.g., timeout, insufficient quota, service unavailable), how to switch automatically: "true": enable automatic failover. When the current provider is unavailable, try other available providers according to the routing strategy. "false": disable failover. If the current provider call fails, return the error directly without trying other providers. "<provider_name>": explicitly specify a fixed backup provider, e.g. "anthropic": Use the provider selected by primary routing first
If it fails, switch to the specified fallback provider
If both primary and fallback fail, return an error

model_routing_config `object` Optional

Used to configure selection and routing among different models within the same provider for the current request (e.g., choosing between gpt-4o, gpt-4-turbo, claude-3-5-sonnet). If not configured, the project or SDK’s default model selection strategy is used (e.g., default model, default task-type mapping).

available_models `array` Required

List of model names that can be used for routing or fallback.

preference `string` Optional

Preferred model name.

task_info `object` Optional

Task metadata used to determine the model or parameters based on task type and complexity. Internal fields:

task_type `string` Required

Task type describing the purpose of the request for routing or automatic parameter selection.

Example supported values:
- "chat" — conversational tasks (multi-turn chat, assistant Q&A)
- "completion" — general text generation/completion
- "embedding" — vectorization/semantic embeddings
Usage:
- Can set different default models or quota strategies per task type
- Can be combined with complexity to decide whether to use a stronger model

complexity `string` Optional

Task complexity indicating the difficulty or importance of the request.

Supported values:
- "low" — simple tasks (short answers, simple rewrites, etc.)
- "medium" — medium complexity (general Q&A, basic code, standard analysis)
- "high" — high complexity (long document analysis, complex programming, large-scale reasoning)
Usage:
- Select different tiers of models by complexity (e.g., cheaper models for low complexity; stronger models for high complexity)
- Can also be used to control timeouts, retry strategies, etc.

additional_properties `object` Optional

Additional task-related fields as an extensible key-value map.

additional_properties `object` Optional

Additional fields for the model routing config itself, used to attach extra control info beyond the standard structure.

Unsupported fields

Field name	Type	Supported	Description
service_tier	string	<span style=“white-space: nowrap;”>❌ Not supported</span>	Service tier
user	string	❌ Not supported	Legacy user identifier; its main role is now replaced by `safety_identifier` and `prompt_cache_key`.
background	boolean	❌ Not supported	Whether to run this response in the background
metadata	object(map)	❌ Not supported	Up to 16 key-value metadata pairs
tools(Code interpreter)	object	❌ Not supported	Code interpreter
tools(Image generation tool)	object	❌ Not supported	Image generation tool
tools(File search)	object	❌ Not supported	File search

Note: agipower does not support three tool types: tools(Code interpreter), tools(Image generation tool), and tools(File search). Therefore, any fields related to these three tool types will not take effect. This document has already filtered out those fields.

Response (non-streaming)

When stream: false, a Response object is returned.

Top-level fields (Response object)

background `boolean`

Whether this Response runs in the background. Not supported as an input; defaults to false.

completed_at `number`

Response completion timestamp (Unix seconds); present only when status is completed.

conversation `object`

The conversation this Response belongs to; input/output items are automatically appended to that conversation.

id string: unique conversation ID.

created_at `number`

Response creation timestamp (Unix seconds).

error `object | null`

Error object when generation fails.

code string: error code.
message string: error message.

id `string`

Unique Response ID.

incomplete_details `object | null`

Reason information for an incomplete Response.

reason string: reason (e.g., reached max_output_tokens).

instructions `string | array`

System/developer instructions inserted into the model context.

max_output_tokens `integer | null`

Generation cap (includes visible output and reasoning tokens).

max_tool_calls `integer | null`

Total built-in tool call cap (accumulated across tools).

model `string`

Model ID that generated this Response.

object `string`

Object type, fixed to response.

output `array`

Array of model output items (order/length determined by the model). See details below.

output_text `string` (SDK Only)

SDK convenience field: concatenation of all output_text text.

parallel_tool_calls `boolean`

Whether parallel tool calls are allowed.

previous_response_id `string | null`

Previous Response ID; used for multi-turn conversations (mutually exclusive with conversation).

prompt `object`

Referenced prompt template and variables.

id string: prompt template ID.
version string: template version (optional).
variables object(map): variable substitution values.

prompt_cache_key `string`

Stable identifier for cache optimization (replaces user).

prompt_cache_retention `string`

Prompt cache retention policy (e.g. 24h).

reasoning `object`

Reasoning configuration (gpt-5 / o series).

effort string | null: reasoning intensity; supported values: none, minimal, low, medium, high, xhigh.
summary string | null: whether to generate a reasoning summary; one of auto, concise, or `detailed.

safety_identifier `string`

Stable user identifier for safety monitoring (recommended to hash).

service_tier `string`

Service tier. Not supported as an input; defaults to default in the response.

store `boolean`

Whether to store the Response for later retrieval (appears in example responses).

status `string`

Generation status: completed / failed / in_progress / cancelled / queued / incomplete.

temperature `number`

Sampling temperature (0–2).

text `object`

Text output configuration.

text.format `object`

Specifies the model’s text output format. Default \{ type: "text" \}. Possible text.format types:

Text format

type string

Fixed to text, meaning plain text output.

JSON Object format

type string

Fixed to json_object, enabling JSON mode (guarantees valid JSON output).

JSON Schema format (Structured Outputs)

type string: fixed to json_schema.
name string: format name (≤64, alphanumeric/underscore/hyphen).
description string: format description.
schema object: JSON Schema definition.
strict boolean: strict mode; when enabled, output must strictly follow the schema.

⚠ How to enable JSON Schema / JSON Mode (Responses API)

Structured Outputs:
text: \{ format: \{ type: "json_schema", strict: true, schema: ... \} \}
JSON mode:
text: \{ format: \{ type: "json_object" \} \}

text.verbosity `string`

Constrains response verbosity. Lower values produce more concise responses; higher values produce more detailed responses. Supported values: low / medium / high

tool_choice `string | object`

Controls whether/how the model calls tools.

Tool choice mode`string`

none: do not call tools; generate text directly
auto: the model may decide to call one or more tools
required: the model must call one or more tools

Allowed tools`object`

Used to restrict the available tool subset (after providing a full set in tools, allow the model to choose only within a subset).

tool_choice.type string

Fixed to allowed_tools.

tool_choice.mode string
- auto: the model may freely choose among allowed tools or not call tools
- required: the model must call one of the allowed tools
tool_choice.tools array

List of allowed tool definitions (can mix function / mcp, etc.). Example:

  { &quot;type&quot;: &quot;function&quot;, &quot;name&quot;: &quot;get_weather&quot; },
  { &quot;type&quot;: &quot;mcp&quot;, &quot;server_label&quot;: &quot;deepwiki&quot; }
"

Hosted tool choice`object`

Force a built-in tool (Hosted / Built‑in tools) call.

tool_choice.type string Allowed values:
- web_search_preview
- computer_use_preview

Function tool choice`object`

Force a specific custom function call.

tool_choice.type string

Fixed to function.

tool_choice.name string

Function name.

MCP tool choice`object`

Force a specific MCP remote tool call.

tool_choice.type string

Fixed to mcp.

tool_choice.server_label string

MCP server identifier.

tool_choice.name string

MCP tool name to call.

Custom tool choice`object`

Force a specific custom tool call.

tool_choice.type string

Fixed to custom.

tool_choice.name string

Custom tool name to call.

Specific apply_patch tool choice`object`

Force the model to call the apply_patch tool.

tool_choice.type string

Fixed to apply_patch.

Specific shell tool choice`object`

Force the model to call the shell tool.

tool_choice.type string

Fixed to shell.

tools `array`

List of callable tools.

Possible `tools[i]` types

Function tool (function tool definition) `object`

type string: function
name string: function name
parameters object (JSON Schema): function parameter definition
strict boolean (default true): strict mode
description string: function description

Web search (generally available) `object`

type string : web_search or web_search_2025_08_26
filters object : search filters
- allowed_domains array[string] (default []): allowed domain allowlist (subdomains allowed)
search_context_size string (default medium): low / medium / high: search context size
user_location object : approximate user location
- type string : approximate
- city string: city name
- country string : 2-letter ISO (e.g. US)
- region string: region/state code
- timezone string : IANA TZ (e.g. America/Los_Angeles)

Web search preview `object`

type string: web_search_preview or web_search_preview_2025_03_11
search_context_size string : low / medium / high
user_location object: user location
- type string: approximate
- city string: city name
- country string (2-letter ISO)
- region string: region/state code
- timezone string (IANA TZ)

Computer use preview (Computer Use tool) `object`

type string : computer_use_preview
display_width integer : display width (pixels)
display_height integer : display height (pixels)
environment string : environment type (e.g. browser / mac / windows / ubuntu)

Apply patch tool (apply patch) `object`

type string: apply_patch

MCP tool (remote MCP tool) `object` (if enabled)

type string : mcp
server_label string : MCP server label (for tool-call routing)
server_url string : remote MCP server
authorization string : OAuth access token (for remote MCP server or service connector)
allowed_tools array[string] | object : allowed tools list or filter
- MCP allowed tools array[string]
- MCP tool filter object
  - read_only boolean : filter by read-only tools
  - tool_names array[string] : tool name allowlist
require_approval string | object : which tools require approval (example uses never; supports finer granularity)
- string: always / never
- object: approval filter (schema in docs)

Shell tool (generic Shell) `object`

type string : shell

(Usually no extra configuration is needed; execution parameters are in the model output’s shell_call.action.)

Local shell tool (legacy local Shell) `object`

type string : local_shell

(The official guidance notes that local shell is legacy; for new use cases, shell is recommended.)

Custom tool (custom tool definition; non-function “free input / optionally constrained format”) `object`

type string : custom
name string : tool name
description string : tool description
format object : input format config (defaults to free text)
- Text format object: text format
  - type string : text: format type, fixed to text
- Grammar format object: grammar format
  - type string : grammar: format type, fixed to grammar
  - syntax string : lark / regex: grammar syntax
  - definition string : grammar definition

top_logprobs `integer`

Top-N probabilities for each token (0–20).

top_p `number`

Nucleus sampling parameter.

truncation `string`

Truncation strategy: auto / disabled.

usage `object`

Token usage information.

input_tokens integer: number of input tokens
input_tokens_details object: input token details
- cached_tokens integer: number of cached tokens
output_tokens integer: number of output tokens
output_tokens_details object: output token details
- reasoning_tokens integer: number of reasoning tokens
total_tokens integer: total number of tokens

user `string | null` (Deprecated)

Deprecated. Defaults to null. Use prompt_cache_key / safety_identifier instead.

output[i]: Possible Output item types

Output message (output message) `object`

type string: fixed to message.
id string: message item ID.
role string: fixed to assistant.
status string: in_progress / completed / incomplete.
content array: list of content parts.

Possible `message.content[j]` types

A) Output text object

type string: fixed to output_text.
text string: model output text.
annotations array: citation/annotation list.
logprobs array: token probability info (requires include).

B) Refusal object

type string: fixed to refusal.
refusal string: refusal explanation.

Possible `Output text.annotations[k]` types

File citation object

type string: fixed to file_citation.
file_id string: file ID.
filename string: file name.
index integer: file index.

URL citation object

type string: fixed to url_citation.
url string: page URL.
title string: page title.
start_index integer: citation start position.
end_index integer: citation end position.

Container file citation object

type string: fixed to container_file_citation.
container_id string: container ID.
file_id string: file ID.
filename string: file name.
start_index integer: citation start position.
end_index integer: citation end position.

File path object

type string: fixed to file_path.
file_id string: file ID.
index integer: file index.

Output text.logprobs[m] (token logprob schema)

token string: token text.
logprob number: log probability.
bytes array: byte representation.
top_logprobs array: candidate tokens and logprobs.

Reasoning (reasoning item) `object`

type string: fixed to reasoning.
id string: reasoning item ID.
summary array: reasoning summary parts.
- type string: fixed to summary_text.
- text string: summary text.
content array: optional reasoning body parts.
- type string: fixed to reasoning_text.
- text string: reasoning body text.
encrypted_content string: encrypted reasoning content (requires include).
status string: in_progress / completed / incomplete.

Function tool call (function call request) `object`

type string: fixed to function_call.
id string: call item ID.
call_id string: correlated call ID.
name string: function name.
arguments string: JSON string arguments.
status string: in_progress / completed / incomplete.

Web search tool call (web search call result) `object`

type string: fixed to web_search_call.
id string: search call ID.
status string: search call status.
action object: specific action.
- Search action object
  - type string: action type (search).
  - query string: query (deprecated).
  - queries array: query list.
  - sources array: source list (requires include).
- Open page action object
  - type string: open_page.
  - url string: opened URL.
- Find action object
  - type string: find.
  - url string: page searched.
  - pattern string: find pattern.

Compaction item `object`

Generated by v1/responses/compact. Used to compress long conversations into an opaque encrypted summary and can be fed back into later input.

type string: compaction
id string: compaction item ID
encrypted_content string: compressed summary (encrypted, opaque)
created_by string: identifier of the entity that created this item

Local shell call (local shell call) `object`

type string: fixed to local_shell_call
id string: unique identifier for the tool call
call_id string: call ID
status string: call status
action object: execution action config
- type string: exec: action type, fixed to executing a command
- command array: command to execute (array form)
- env map: environment variables
- timeout_ms integer: timeout (ms)
- user string: execution user
- working_directory string: working directory path

Computer tool call (Computer Use call) `object`

type string: fixed to computer_call.
id string: call ID.
call_id string: correlated call ID.
status string: call status.
pending_safety_checks array: pending safety checks.
action object: specific action.

Action types (possible `action` variants)

Click `object`

type string: click
x number
y number
button string : left / right / middle

Double click `object`

type string: double_click
x integer
y integer

Move `object`

type string: move
x integer
y integer

Screenshot `object`

type screenshot: move

Drag `object`

type string: drag
path array: drag
- x integer
- y integer

Scroll `object`

type string: scroll
x integer (scroll anchor; some implementations provide it)
y integer
scroll_x integer
scroll_y integer

Type `object`

type string: type
text string

Keypress `object`

type string: keypress
keys array (key combo, e.g. ["CTRL","L"])

Wait `object`

type string: wait

Shell tool call `object`

type string: shell_call
call_id string
id string
status string: in_progress / completed / incomplete
action object: shell commands and limits
- commands array: list of commands to run in order
- max_output_length integer: max captured stdout+stderr UTF-8 chars
- timeout_ms integer: timeout in ms
created_by string: entity ID that created this tool call

Shell tool call output `object`

type string: fixed to shell_call_output
call_id string: call ID
id string: unique identifier for the output item
max_output_length integer: max output length limit
output array: list of stdout/stderr chunks; each element:
- stdout string: stdout content
- stderr string: stderr content
- outcome object: execution outcome (union type)
  - Timeout outcome object: timeout outcome
    - type string: timeout: outcome type, fixed to timeout
  - Exit outcome object: exit outcome
    - type string: exit: outcome type, fixed to exit
    - exit_code integer: exit code
created_by string: identifier of the entity that created this item

Apply patch tool call (apply patch call) `object`

Used to create/delete/update files via a diff patch.

type string: fixed to apply_patch_call
call_id string: call ID
id string: unique identifier for the call
status string: in_progress / completed: call status
created_by string: creator identifier
operation object: operation (union type)

Possible operation types

Create file object: create file operation

type string: create_file: operation type, fixed to create file
path string: relative to workspace root
diff string: unified diff content

Delete file object: delete file operation

type string: delete_file: operation type, fixed to delete file
path string: file path

Update file object: update file operation

type string: update_file: operation type, fixed to update file
path string: file path
diff string: unified diff content

Apply patch tool call output `object`

type string: fixed to apply_patch_call_output
call_id string: call ID
id string: unique identifier for the output item
status string: completed / failed: execution status
output string: human-readable logs/errors
created_by string: creator identifier

MCP tool call `object`

type string: fixed to mcp_call
id string: unique identifier for the tool call
server_label string: MCP server label
name string: tool name
arguments string: JSON string arguments
approval_request_id string: ID for subsequent approval response
output string: tool output
error string: error message
status string: in_progress / completed / incomplete / calling / failed: call status

MCP list tools `object`

type string: fixed to mcp_list_tools
id string: unique identifier for the call
server_label string: MCP server label
error string: error message
tools array: tool list; each element:
- name string: tool name
- description string: tool description
- annotations object: tool annotations
- input_schema object: JSON Schema input parameter definition

MCP approval request `object`

type string: fixed to mcp_approval_request
id string: unique approval request ID
server_label string: MCP server label
name string: requested tool name to run
arguments string: tool arguments as a JSON string

Custom tool call (custom tool call) `object`

The model initiates a call to a “custom tool” (you must execute it on your side).

type string: fixed to custom_tool_call
call_id string: call ID
name string: tool name
input string: input parameters
id string: unique identifier for the call

Response (streaming)

When stream: true, POST /v1/responses does not return the full Response object in one shot. Instead, it continuously pushes a sequence of Streaming events via SSE (Server-Sent Events). (platform.openai.com)

Transport format (SSE)

HTTP responses are typically Content-Type: text/event-stream
The server sends multiple events in order
Each event, at the “wire protocol” level, typically looks like this (example):

data: {"type":"response.output_text.delta","item_id":"msg_123","output_index":0,"content_index":0,"delta":"Hello","sequence_number":12}

Note: SSE also supports an event: ... line, but in Responses streaming semantics, the event type is determined by the JSON type field. SDKs also parse each event directly into an object for consumption. (platform.openai.com)

General notes on Streaming events

Each event includes:
- type: event type string (e.g., response.created)
- sequence_number: event sequence number for ordering (examples may start from 0 or 1)
Many events include indexes/association fields such as output_index, item_id, content_index to precisely merge delta events back into the specific item in output[] and the specific content part within that item.

Streaming events

Below, each event lists fields in the same order as on the official reference page. The exact structures of objects like response / item / part / annotation match the earlier “non-streaming Response object / output items” section (or the corresponding official schemas).

response.created

Emitted when the response is created. Fields:

response object: the created Response (the Response object described above)
sequence_number integer: event sequence number
type string: fixed to response.created

response.in_progress

Emitted while the response is being generated. Fields:

response object: in-progress Response
sequence_number integer
type string: fixed to response.in_progress

response.completed

Emitted when the response completes (includes the final Response). Fields:

response object: completed Response (includes final output, usage, etc.)
sequence_number integer
type string: fixed to response.completed

response.failed

Emitted when the response fails (includes error info). Fields:

response object: failed Response (status="failed", non-empty error)
sequence_number integer
type string: fixed to response.failed

response.incomplete

Emitted when the response ends as incomplete (e.g., hitting a limit). Fields:

response object: incomplete Response (status="incomplete", incomplete_details may be non-empty)
sequence_number integer
type string: fixed to response.incomplete

response.output_item.added

Emitted when a new output item is added. Fields:

item object: the newly added output item (message / tool call / reasoning, etc.; see output[i] above)
output_index integer: index of the item in response.output[]
sequence_number integer
type string: fixed to response.output_item.added

response.output_item.done

Emitted when an output item is done. Fields:

item object: completed output item
output_index integer
sequence_number integer
type string: fixed to response.output_item.done

response.content_part.added

Emitted when a message’s content[] adds a new content part. Fields:

content_index integer: index of the part in message.content[]
item_id string: ID of the owning output item (usually the message item’s id)
output_index integer: owning output item index
part object: newly added content part (e.g., output_text / refusal; see above)
sequence_number integer
type string: fixed to response.content_part.added

response.content_part.done

Emitted when a content part is done. Fields:

content_index integer
item_id string
output_index integer
part object: finalized content part
sequence_number integer
type string: fixed to response.content_part.done

response.output_text.delta

Delta event for output text. Fields:

content_index integer: content part index that owns the text
delta string: newly generated text fragment
item_id string: owning output item ID
logprobs array: token probabilities (appears only with include/config; schema matches the logprobs definition above)
output_index integer: owning output item index
sequence_number integer
type string: fixed to response.output_text.delta

response.output_text.done

Emitted when a text segment is finalized. Fields:

content_index integer
item_id string
logprobs array: token probabilities (as above; appears as needed)
output_index integer
sequence_number integer
text string: final full text
type string: fixed to response.output_text.done

response.refusal.delta

Delta event for refusal text. Fields:

content_index integer
delta string: refusal text delta
item_id string
output_index integer
sequence_number integer
type string: fixed to response.refusal.delta

response.refusal.done

Final refusal text event. Fields:

content_index integer
item_id string
output_index integer
refusal string: final refusal explanation
sequence_number integer
type string: fixed to response.refusal.done

response.function_call_arguments.delta

Delta event for function call arguments (arguments is incrementally concatenated as a JSON string). Fields:

delta string: incremental arguments fragment
item_id string: ID of the function_call item
output_index integer
sequence_number integer
type string: fixed to response.function_call_arguments.delta

response.function_call_arguments.done

Final function call arguments event. Fields:

arguments string: final arguments (JSON string)
item_id string
name string: function name
output_index integer
sequence_number integer
type string: fixed to response.function_call_arguments.done

response.web_search_call.in_progress

Web search tool call start event. Fields:

item_id string: ID of the web_search_call item
output_index integer
sequence_number integer
type string: fixed to response.web_search_call.in_progress

response.web_search_call.searching

Web search in-progress event. Fields:

item_id string
output_index integer
sequence_number integer
type string: fixed to response.web_search_call.searching

response.web_search_call.completed

Web search completed event (sources and similar fields require include). Fields:

item_id string
output_index integer
sequence_number integer
type string: fixed to response.web_search_call.completed

response.reasoning_summary_part.added

Emitted when a new reasoning summary part is added. Fields:

item_id string: reasoning item ID
output_index integer
part object: newly added summary part (e.g., summary_text)
sequence_number integer
summary_index integer: index of the summary part
type string: fixed to response.reasoning_summary_part.added

response.reasoning_summary_part.done

Emitted when a reasoning summary part is done. Fields:

item_id string
output_index integer
part object: finalized summary part
sequence_number integer
summary_index integer
type string: fixed to response.reasoning_summary_part.done

response.reasoning_summary_text.delta

Delta event for reasoning summary text. Fields:

delta string: summary text delta
item_id string
output_index integer
sequence_number integer
summary_index integer
type string: fixed to response.reasoning_summary_text.delta

response.reasoning_summary_text.done

Final reasoning summary text event. Fields:

item_id string
output_index integer
sequence_number integer
summary_index integer
text string: final full summary text
type string: fixed to response.reasoning_summary_text.done

response.reasoning_text.delta

Delta event for reasoning body text. Fields:

content_index integer: reasoning content part index
delta string
item_id string
output_index integer
sequence_number integer
type string: fixed to response.reasoning_text.delta

response.reasoning_text.done

Final reasoning body text event. Fields:

content_index integer
item_id string
output_index integer
sequence_number integer
text string: final full reasoning text
type string: fixed to response.reasoning_text.done

response.mcp_call_arguments.delta

Delta event for MCP tool call arguments (JSON string incremental). Fields:

delta string: arguments delta (JSON string fragment)
item_id string
output_index integer
sequence_number integer
type string: fixed to response.mcp_call_arguments.delta

response.mcp_call_arguments.done

Final MCP tool call arguments event. Fields:

arguments string: final arguments (JSON string)
item_id string
output_index integer
sequence_number integer
type string: fixed to response.mcp_call_arguments.done

response.mcp_call.completed

Emitted when an MCP tool call completes successfully. Fields:

item_id string
output_index integer
sequence_number integer
type string: fixed to response.mcp_call.completed

response.mcp_call.failed

Emitted when an MCP tool call fails. Fields:

item_id string
output_index integer
sequence_number integer
type string: fixed to response.mcp_call.failed

response.mcp_call.in_progress

Emitted while an MCP tool call is in progress. Fields:

item_id string
output_index integer
sequence_number integer
type string: fixed to response.mcp_call.in_progress

response.mcp_list_tools.completed

Emitted when MCP list-tools completes successfully. Fields:

item_id string
output_index integer
sequence_number integer
type string: fixed to response.mcp_list_tools.completed

response.mcp_list_tools.failed

Emitted when MCP list-tools fails. Fields:

item_id string
output_index integer
sequence_number integer
type string: fixed to response.mcp_list_tools.failed

response.mcp_list_tools.in_progress

Emitted while MCP list-tools is in progress. Fields:

item_id string
output_index integer
sequence_number integer
type string: fixed to response.mcp_list_tools.in_progress

response.output_text.annotation.added

Delta event for adding an annotation to a text output’s annotations array. Fields:

annotation object: newly added annotation (schema matches the annotation types above / official schema)
annotation_index integer: index in the annotations array
content_index integer
item_id string
output_index integer
sequence_number integer
type string: fixed to response.output_text.annotation.added

response.queued

Emitted when the response enters the queued state. Fields:

response object: queued Response (same schema as Response object; examples may show only a subset)
sequence_number integer
type string: fixed to response.queued

response.custom_tool_call_input.delta

Delta event for custom tool input. Fields:

delta string: input delta fragment
item_id string: ID of the custom_tool_call item
output_index integer
sequence_number integer
type string: event type identifier (fixed to response.custom_tool_call_input.delta)

response.custom_tool_call_input.done

Final custom tool input event. Fields:

input string: final full input
item_id string
output_index integer
sequence_number integer
type string: event type identifier (fixed to response.custom_tool_call_input.done)

error

Emitted when an error occurs during streaming. Fields:

code string: error code
message string: error message
param string: error parameter (may be null)
sequence_number integer
type string: fixed to error

POST /v1/responses

import OpenAI from "openai";

const openai = new OpenAI({
  baseURL: 'https://api.agipower.ai/v1',
  apiKey: '<AGIPower_API_KEY>',
});

async function main() {
  const response = await openai.responses.create({
    model: "openai/gpt-5",
    input: "What is the meaning of life?"
  })

  print(response)
}

main();

from openai import OpenAI

client = OpenAI(
    base_url="https://api.agipower.ai/v1",
    api_key="<your_AGIPower_API_KEY>",
)

response = client.responses.create(
    model: "openai/gpt-5",
    input: "What is the meaning of life?"
)

print(response)

curl https://api.agipower.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGIPower_API_KEY" \
  -d '{
    "model": "openai/gpt-5",
    "input": "What is the meaning of life?"
  }'

API Response

{
  "id": "resp_0140d07a600e72a30069733ecadb508194b7cd84f200b593c7",
  "object": "response",
  "created_at": 1769160394,
  "status": "completed",
  "background": false,
  "content_filters": [
    {
      "blocked": false,
      "source_type": "prompt",
      "content_filter_raw": null,
      "content_filter_results": {},
      "content_filter_offsets": {
        "start_offset": 0,
        "end_offset": 0,
        "check_offset": 0
      }
    },
    {
      "blocked": false,
      "source_type": "completion",
      "content_filter_raw": null,
      "content_filter_results": {},
      "content_filter_offsets": {
        "start_offset": 0,
        "end_offset": 0,
        "check_offset": 0
      }
    }
  ],
  "error": null,
  "incomplete_details": null,
  "instructions": null,
  "max_output_tokens": null,
  "max_tool_calls": null,
  "model": "openai/gpt-5",
  "output": [
    {
      "id": "rs_0140d07a600e72a30069733ecbf4c88194b2a1d173c1b500fa",
      "type": "reasoning",
      "summary": []
    },
    {
      "id": "msg_0140d07a600e72a30069733edc988881948160d23b617f9994",
      "type": "message",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "annotations": [],
          "logprobs": [],
          "text": "There isn’t a single agreed-on meaning of life. Different lenses offer different answers:\n- Evolutionary: to survive, reproduce, and pass on genes.\n- Religious/spiritual: to know, serve, or unite with the divine.\n- Existential: life has no built-in meaning; we create it through choices.\n- Humanistic/psychological: meaning arises from relationships, growth, and contribution.\n\nFor most people, meaning tends to cluster around a few pillars:\n- Love and connection\n- Growth and mastery\n- Service and impact\n- Curiosity, beauty, and wonder\n\nIf you’re seeking your own, try:\n- Clarify values: list your top 5 and rank them.\n- Track aliveness: note when you feel most engaged and why.\n- Contribute: find a problem you care about and help, even in small ways.\n- Commit: choose a long-term project that matters to you and stick with it.\n\nMeaning is less a destination than a practice. If you share what matters to you, I can help you shape it into a clear life purpose."
        }
      ],
      "role": "assistant"
    }
  ],
  "parallel_tool_calls": true,
  "previous_response_id": null,
  "prompt_cache_key": null,
  "prompt_cache_retention": null,
  "reasoning": {
    "effort": "medium",
    "summary": null
  },
  "safety_identifier": null,
  "service_tier": "default",
  "store": true,
  "temperature": 1,
  "text": {
    "format": {
      "type": "text"
    },
    "verbosity": "medium"
  },
  "tool_choice": "auto",
  "tools": [],
  "top_logprobs": 0,
  "top_p": 1,
  "truncation": "disabled",
  "usage": {
    "input_tokens": 13,
    "input_tokens_details": {
      "cached_tokens": 0,
      "web_search": 0
    },
    "output_tokens": 801,
    "output_tokens_details": {
      "reasoning_tokens": 576
    },
    "total_tokens": 814
  },
  "user": null,
  "metadata": {}
}

​Create a Model Response

​Request headers

​Authorization string Required

​Content-Type string Required

​Request body

​model string Required

​input string | array Optional

​string

​array (Input item list)

1. Input message object

​Input content parts (possible input content part types)

2. Item types overview

​Input message object

​Output message (model output message) object

Output content parts (possible output content part types)

​Function tool call object

​Function tool call output (function tool output) object

​Custom tool call object

​Custom tool call output (custom tool output) object

​Web search tool call object

Possible action types

​Computer tool call (Computer Use call) object

Action types (possible action variants)

Click object

Double click object

Move object

Screenshot object

Drag object

Scroll object

Type object

Keypress object

Wait object

​Computer tool call output (Computer Use output) object

​Local shell call (local shell call) object

​Local shell call output object

​Shell tool call object

​Shell tool call output object

​Apply patch tool call (apply patch call) object

Possible operation types

​Apply patch tool call output object

​MCP list tools object

​MCP approval request object

​MCP approval response object

​MCP tool call object

​Reasoning object

​Compaction item object

3. Item reference object

​instructions string Optional

​previous_response_id string Optional

​conversation string | object Optional (default null)

​prompt object Optional

​include array Optional

​max_output_tokens integer Optional

​max_tool_calls integer Optional

​parallel_tool_calls boolean Optional (default true)

​reasoning object Optional (reasoning models only)

​text object Optional

​temperature number Optional (default 1)

​top_p number Optional (default 1)

​top_logprobs integer Optional

​truncation string Optional (default disabled)

​tools array Optional

​Possible tools[i] types

​Function tool (function tool definition) object

​Web search (generally available) object

​Web search preview object

​Computer use preview (Computer Use tool) object

​Apply patch tool (apply patch) object

​MCP tool (remote MCP tool) object (if enabled)

​Shell tool (generic Shell) object

​Local shell tool (legacy local Shell) object

​Custom tool (custom tool definition; non-function “free input / optionally constrained format”) object

​tool_choice string | object Optional

​Tool choice mode string

​Allowed tools object

​Hosted tool (force a built-in tool) object

​Function tool (force a specific function) object

​MCP tool (force a specific MCP tool) object

​Custom tool (force a specific custom tool) object

​Specific apply patch tool choice (force the model to call apply_patch) object

Create a Model Response

Request headers

Authorization `string` Required

Content-Type `string` Required

Request body

model `string` Required

input `string | array` Optional

`string`

`array` (Input item list)

1. Input message `object`

Input content parts (possible input content part types)

Input message `object`

Output message (model output message) `object`

Function tool call `object`

Function tool call output (function tool output) `object`

Custom tool call `object`

Custom tool call output (custom tool output) `object`

Web search tool call `object`

Computer tool call (Computer Use call) `object`

Action types (possible `action` variants)

Click `object`

Double click `object`

Move `object`

Screenshot `object`

Drag `object`

Scroll `object`

Type `object`

Keypress `object`

Wait `object`

Computer tool call output (Computer Use output) `object`

Local shell call (local shell call) `object`

Local shell call output `object`

Shell tool call `object`

Shell tool call output `object`

Apply patch tool call (apply patch call) `object`

Apply patch tool call output `object`

MCP list tools `object`

MCP approval request `object`

MCP approval response `object`

MCP tool call `object`

Reasoning `object`

Compaction item `object`

3. Item reference `object`

instructions `string` Optional

previous_response_id `string` Optional

conversation `string | object` Optional (default `null`)

prompt `object` Optional

include `array` Optional

max_output_tokens `integer` Optional

max_tool_calls `integer` Optional

parallel_tool_calls `boolean` Optional (default `true`)

reasoning `object` Optional (reasoning models only)

text `object` Optional

temperature `number` Optional (default `1`)

top_p `number` Optional (default `1`)

top_logprobs `integer` Optional

truncation `string` Optional (default `disabled`)

tools `array` Optional

Possible `tools[i]` types

Function tool (function tool definition) `object`

Web search (generally available) `object`

Web search preview `object`

Computer use preview (Computer Use tool) `object`

Apply patch tool (apply patch) `object`

MCP tool (remote MCP tool) `object` (if enabled)

Shell tool (generic Shell) `object`

Local shell tool (legacy local Shell) `object`

Custom tool (custom tool definition; non-function “free input / optionally constrained format”) `object`

tool_choice `string | object` Optional

Tool choice mode `string`

Allowed tools `object`

Hosted tool (force a built-in tool) `object`

Function tool (force a specific function) `object`

MCP tool (force a specific MCP tool) `object`

Custom tool (force a specific custom tool) `object`

Specific apply patch tool choice (force the model to call apply_patch) `object`

Specific shell tool choice (force the model to call Shell when a tool call is needed) `object`

store `boolean` Optional (default `true`)

stream `boolean` Optional (default `false`)

stream_options `object` Optional (default `null`)