> ## Documentation Index
> Fetch the complete documentation index at: https://docs.haitoken.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Responses format
> Create chat completions compatible with the OpenAI Responses protocol, supporting streaming and non-streaming responses
This endpoint is compatible with the OpenAI Responses protocol for creating chat completion requests.
## Features
* Supports both streaming (SSE) and non-streaming response modes
* Supports function calling and tool calling
* Supports structured output (JSON Schema)
* Supports reasoning effort configuration
* Supports web search options
## Use cases
Suitable for scenarios requiring interaction with OpenAI-compatible models, including:
* Single-turn or multi-turn conversations
* Function calling and tool orchestration
* Structured JSON output
* Real-time streaming responses
## Authentication
Include the `Authorization` header in the format `Bearer YOUR_API_KEY`.
Never expose API keys in client-side code. Use a server-side proxy to forward requests.
Session state management is not supported
The current API does not support the server-side state management capability of the OpenAI Responses API.
The following fields are not supported:
* `previous_response_id`
* `conversation`
This endpoint runs in a stateless mode. It does not store past responses, and subsequent requests do not automatically carry previous conversation context.
To implement multi-turn conversations, maintain the message history on your side and explicitly pass the full context via the `input` parameter.
## Quick example
```python Python theme={null}
import requests
url = "https://api.haitoken.ai/v1/responses"
headers = {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
}
data = {
"model": "gpt-5.4",
"input": "Hello, please introduce yourself"
}
response = requests.post(url, json=data, headers=headers)
print(response.json())
```
```javascript Node.js theme={null}
const response = await fetch('https://api.haitoken.ai/v1/responses', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
model: 'gpt-5.4',
input: 'Hello, please introduce yourself'
})
});
const data = await response.json();
console.log(data);
```
```curl cURL theme={null}
curl -X POST 'https://api.haitoken.ai/v1/responses' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"model": "gpt-5.4",
"input": "Hello, please introduce yourself"
}'
```
## OpenAPI
````yaml en/api-reference/chat/responses/responses-openapi.json POST /v1/responses
openapi: 3.0.1
info:
title: API Documentation
version: '1.0'
servers:
- url: https://api.haitoken.ai
security: []
paths:
/v1/responses:
post:
summary: Create a response
description: Create a response
parameters:
- name: Authorization
in: header
description: API Key token (Bearer sk-xxx)
required: true
schema:
type: string
default: 'Bearer '
example: 'Bearer '
- name: Content-Type
in: header
description: ''
schema:
type: string
example: application/json
default: application/json
requestBody:
content:
application/json:
schema:
required:
- input
- model
type: object
properties:
context_management:
type: array
description: Context management configuration.
items:
type: object
properties:
compact_threshold:
type: integer
description: Token threshold that triggers compaction
format: int64
type:
type: string
description: >-
Context management type, currently only supports
compaction
description: OpenAI Responses API context management configuration
max_output_tokens:
type: integer
description: >-
Maximum number of output tokens (including visible output
and reasoning tokens).
format: int64
max_tool_calls:
type: integer
description: Maximum total number of built-in tool calls.
format: int64
parallel_tool_calls:
type: boolean
description: Whether to enable parallel tool calls.
previous_response_id:
type: string
description: Previous response ID, used for multi-turn conversations.
prompt_cache_key:
type: string
description: >-
Prompt cache key, used to replace user to improve cache hit
rate.
prompt_cache_retention:
type: string
description: Prompt cache retention policy
enum:
- in_memory
- 24h
safety_identifier:
type: string
description: Safety identifier.
service_tier:
type: string
description: >-
{auto=auto, default=default, flex=flex, scale=scale,
priority=priority}
enum:
- auto
- default
- flex
- scale
- priority
stream_options:
type: object
properties:
include_obfuscation:
type: boolean
description: >-
Whether to include streaming obfuscation fields to
mitigate certain side-channel attacks.
description: >-
Streaming response options, only set when {@code stream:
true}.
tool_choice:
oneOf:
- type: string
enum:
- none
- auto
- required
description: Built-in tool selection mode
- type: object
properties:
type:
type: string
description: Tool selection type
name:
type: string
description: Function name (when type=function)
description: Specified tool object
description: >-
Tool selection strategy: none, auto, required, or a tool
selection object with type/name.
top_logprobs:
type: integer
description: >-
Number of most likely tokens to return per token position
(0-20).
format: int64
top_p:
type: number
description: Nucleus sampling.
background:
type: boolean
description: Whether to run the response in the background.
conversation:
type: object
properties: {}
description: >-
Associated conversation. Can be a conversation ID string or
a conversation object with id {@link
ResponseConversationParam}.
include:
type: array
description: Additional data items to include.
items:
type: string
input:
oneOf:
- type: string
description: Text input
- type: array
description: >-
List of input items, including messages, tool call
outputs, item references, etc.
items:
$ref: '#/components/schemas/ResponseInputItem'
description: Input content, can be a string or a list of input items.
instructions:
type: string
description: System/developer instructions.
metadata:
type: object
properties:
metadata:
type: object
properties:
key:
type: string
description: Custom metadata key-value pairs.
default: new java.util.HashMap<>()
description: Metadata, up to 16 key-value pairs.
model:
type: string
description: Model ID, e.g. gpt-4o, gpt-5, etc.
moderation:
type: object
properties:
input:
type: object
properties:
category_applied_input_types:
type: object
properties:
key:
type: object
properties: {}
description: >-
Input types applied per category (ModerationResult
type).
category_scores:
type: object
properties:
key:
type: object
properties: {}
description: Category scores (ModerationResult type).
categories:
type: object
properties:
key:
type: object
properties: {}
description: Moderation category results (ModerationResult type).
flagged:
type: boolean
description: >-
Whether flagged as violating (ModerationResult
type).
model:
type: string
description: Moderation model name (ModerationResult type).
type:
type: string
description: Type identifier (ModerationResult or Error).
code:
type: string
description: Error code (Error type).
message:
type: string
description: Error message (Error type).
description: >-
Input moderation result (union type: ModerationResult or
Error).
output:
type: object
properties:
category_applied_input_types:
type: object
properties:
key:
type: object
properties: {}
description: >-
Input types applied per category (ModerationResult
type).
category_scores:
type: object
properties:
key:
type: object
properties: {}
description: Category scores (ModerationResult type).
categories:
type: object
properties:
key:
type: object
properties: {}
description: Moderation category results (ModerationResult type).
flagged:
type: boolean
description: >-
Whether flagged as violating (ModerationResult
type).
model:
type: string
description: Moderation model name (ModerationResult type).
type:
type: string
description: Type identifier (ModerationResult or Error).
code:
type: string
description: Error code (Error type).
message:
type: string
description: Error message (Error type).
description: >-
Output moderation result (union type: ModerationResult
or Error).
description: Content moderation configuration.
prompt:
required:
- id
type: object
properties:
id:
type: string
description: Prompt template ID (required)
variables:
type: object
properties: {}
description: Template variables
version:
type: string
description: Prompt template version
description: Reusable prompt template reference.
reasoning:
type: object
properties:
generate_summary:
type: string
description: '{auto=auto, concise=concise, detailed=detailed}'
enum:
- auto
- concise
- detailed
context:
type: string
description: >-
{auto=auto, current_turn=current_turn,
all_turns=all_turns}
enum:
- auto
- current_turn
- all_turns
effort:
type: string
description: >-
{none=none, minimal=minimal, low=low, medium=medium,
high=high, xhigh=xhigh}
enum:
- none
- minimal
- low
- medium
- high
- xhigh
summary:
type: string
description: '{auto=auto, concise=concise, detailed=detailed}'
enum:
- auto
- concise
- detailed
description: Reasoning model configuration (gpt-5 and o-series models).
store:
type: boolean
default: false
description: Whether to store the response.
stream:
type: boolean
default: false
description: >-
Whether to enable streaming output (native OpenAI Responses
API field, also used for gateway streaming judgment).
temperature:
type: number
description: Sampling temperature.
text:
type: object
properties:
format:
type: object
properties:
type:
type: string
description: >-
{text=text, json_schema=json_schema,
json_object=json_object}
enum:
- text
- json_schema
- json_object
name:
type: string
description: Schema name (when type=json_schema)
description:
type: string
description: Schema description (when type=json_schema)
schema:
type: object
properties: {}
description: JSON Schema definition (when type=json_schema)
strict:
type: boolean
description: >-
Whether to strictly follow the schema (when
type=json_schema)
description: >-
Output format:
- "text" object
-{@link ResponseFormatTextConfig} object (json_schema /
json_object)
verbosity:
type: string
description: 'Response detail level: low, medium, high.'
description: >-
Text/structured output configuration, replaces the old
response_format.
tools:
type: array
description: >-
Tool list, supports function, web_search_preview,
file_search, computer_use_preview, etc.
items:
$ref: '#/components/schemas/ResponseTool'
truncation:
type: string
description: '{auto=auto, disabled=disabled}'
enum:
- auto
- disabled
user:
type: string
description: >-
User identifier (deprecated, use safety_identifier /
prompt_cache_key instead).
description: ''
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
created_at:
type: number
description: Creation time (Unix timestamp, seconds)
incomplete_details:
type: object
properties:
reason:
type: string
description: >-
{max_output_tokens=max_output_tokens,
content_filter=content_filter}
enum:
- max_output_tokens
- content_filter
description: Incomplete details
parallel_tool_calls:
type: boolean
description: Whether to enable parallel tool calls
tool_choice:
oneOf:
- type: string
enum:
- none
- auto
- required
description: Built-in tool selection mode
- type: object
properties:
type:
type: string
description: Tool selection type
name:
type: string
description: Function name (when type=function)
description: Specified tool object
description: Tool selection strategy
top_p:
type: number
description: Nucleus sampling
completed_at:
type: number
description: Completion time (Unix timestamp, seconds)
max_output_tokens:
type: integer
description: Maximum output token count
format: int64
max_tool_calls:
type: integer
description: Maximum total number of built-in tool calls
format: int64
previous_response_id:
type: string
description: Previous response ID
prompt_cache_key:
type: string
description: Prompt cache key
prompt_cache_retention:
type: string
description: '{in_memory=in_memory, 24h=24h}'
enum:
- in_memory
- 24h
safety_identifier:
type: string
description: Safety identifier
service_tier:
type: string
description: >-
{auto=auto, default=default, flex=flex, scale=scale,
priority=priority}
enum:
- auto
- default
- flex
- scale
- priority
top_logprobs:
type: integer
description: Number of most likely tokens to return per token position
format: int64
id:
type: string
description: Response unique ID
error:
type: object
properties:
code:
type: string
description: >-
{server_error=server_error,
rate_limit_exceeded=rate_limit_exceeded,
invalid_prompt=invalid_prompt,
vector_store_timeout=vector_store_timeout,
invalid_image=invalid_image,
invalid_image_format=invalid_image_format,
invalid_base64_image=invalid_base64_image,
invalid_image_url=invalid_image_url,
image_too_large=image_too_large,
image_too_small=image_too_small,
image_parse_error=image_parse_error,
image_content_policy_violation=image_content_policy_violation,
invalid_image_mode=invalid_image_mode,
image_file_too_large=image_file_too_large,
unsupported_image_media_type=unsupported_image_media_type,
empty_image_file=empty_image_file,
failed_to_download_image=failed_to_download_image,
image_file_not_found=image_file_not_found}
enum:
- server_error
- rate_limit_exceeded
- invalid_prompt
- vector_store_timeout
- invalid_image
- invalid_image_format
- invalid_base64_image
- invalid_image_url
- image_too_large
- image_too_small
- image_parse_error
- image_content_policy_violation
- invalid_image_mode
- image_file_too_large
- unsupported_image_media_type
- empty_image_file
- failed_to_download_image
- image_file_not_found
message:
type: string
description: ''
description: Error message
instructions:
oneOf:
- type: string
description: Text instructions
- type: array
description: Instruction input item list
items:
$ref: '#/components/schemas/ResponseInputItem'
description: >-
System/developer instructions. Can be a string or a list
of input items.
metadata:
type: object
properties:
key:
type: string
description: Metadata, up to 16 key-value pairs
model:
type: string
description: Model ID in use
object:
type: string
description: Object type, always "response"
default: response
output:
type: array
description: Output item list
items:
type: object
properties: {}
description: >-
com.haitoken.core.interfaces.dto.response.input.ResponseOutputItem
temperature:
type: number
description: Sampling temperature
tools:
type: array
description: Tool list
items:
$ref: '#/components/schemas/ResponseTool'
background:
type: boolean
default: false
description: Whether to run the response in the background
conversation:
type: object
properties:
id:
type: string
description: Conversation unique ID
description: Associated conversation
moderation:
type: object
properties:
input:
type: object
properties:
category_applied_input_types:
type: object
properties:
key:
type: object
properties: {}
description: >-
Input types applied per category (ModerationResult
type).
category_scores:
type: object
properties:
key:
type: object
properties: {}
description: Category scores (ModerationResult type).
categories:
type: object
properties:
key:
type: object
properties: {}
description: >-
Moderation category results (ModerationResult
type).
flagged:
type: boolean
description: >-
Whether flagged as violating (ModerationResult
type).
model:
type: string
description: Moderation model name (ModerationResult type).
type:
type: string
description: Type identifier (ModerationResult or Error).
code:
type: string
description: Error code (Error type).
message:
type: string
description: Error message (Error type).
description: >-
Input moderation result (union type: ModerationResult
or Error).
output:
type: object
properties:
category_applied_input_types:
type: object
properties:
key:
type: object
properties: {}
description: >-
Input types applied per category (ModerationResult
type).
category_scores:
type: object
properties:
key:
type: object
properties: {}
description: Category scores (ModerationResult type).
categories:
type: object
properties:
key:
type: object
properties: {}
description: >-
Moderation category results (ModerationResult
type).
flagged:
type: boolean
description: >-
Whether flagged as violating (ModerationResult
type).
model:
type: string
description: Moderation model name (ModerationResult type).
type:
type: string
description: Type identifier (ModerationResult or Error).
code:
type: string
description: Error code (Error type).
message:
type: string
description: Error message (Error type).
description: >-
Output moderation result (union type: ModerationResult
or Error).
description: Input/output content moderation configuration
prompt:
required:
- id
type: object
properties:
id:
type: string
description: Prompt template ID (required)
variables:
type: object
properties: {}
description: Template variables
version:
type: string
description: Prompt template version
description: Reusable prompt template reference
reasoning:
type: object
properties:
generate_summary:
type: string
description: '{auto=auto, concise=concise, detailed=detailed}'
enum:
- auto
- concise
- detailed
context:
type: string
description: >-
{auto=auto, current_turn=current_turn,
all_turns=all_turns}
enum:
- auto
- current_turn
- all_turns
effort:
type: string
description: >-
{none=none, minimal=minimal, low=low, medium=medium,
high=high, xhigh=xhigh}
enum:
- none
- minimal
- low
- medium
- high
- xhigh
summary:
type: string
description: '{auto=auto, concise=concise, detailed=detailed}'
enum:
- auto
- concise
- detailed
description: Reasoning model configuration
status:
type: string
description: >-
{completed=completed, failed=failed,
in_progress=in_progress, cancelled=cancelled,
queued=queued, incomplete=incomplete}
enum:
- completed
- failed
- in_progress
- cancelled
- queued
- incomplete
text:
type: object
properties:
format:
type: object
properties:
type:
type: string
description: >-
{text=text, json_schema=json_schema,
json_object=json_object}
enum:
- text
- json_schema
- json_object
name:
type: string
description: Schema name (when type=json_schema)
description:
type: string
description: Schema description (when type=json_schema)
schema:
type: object
properties: {}
description: JSON Schema definition (when type=json_schema)
strict:
type: boolean
description: >-
Whether to strictly follow the schema (when
type=json_schema)
description: >-
Output format:
- "text" object
-{@link ResponseFormatTextConfig} object (json_schema
/ json_object)
verbosity:
type: string
description: 'Response detail level: low, medium, high.'
description: Text/structured output configuration
truncation:
type: string
description: '{auto=auto, disabled=disabled}'
enum:
- auto
- disabled
usage:
type: object
properties:
input_tokens:
type: integer
description: Input token count
format: int64
output_tokens:
type: integer
description: Output token count
format: int64
total_tokens:
type: integer
description: Total token count
format: int64
input_tokens_details:
type: object
properties:
cached_tokens:
type: integer
description: Number of tokens retrieved from cache
format: int64
default: 0
cache_write_tokens:
type: integer
description: ''
format: int64
default: 0
description: Input token details
output_tokens_details:
type: object
properties:
reasoning_tokens:
type: integer
description: Reasoning token count
format: int64
description: Output token details
description: Usage statistics
user:
type: string
description: User identifier (deprecated)
components:
schemas:
ResponseInputItem:
type: object
oneOf:
- description: >-
type=message, simplified text message, content can be string or
content object array
type: object
properties:
type:
type: string
enum:
- message
description: Type, fixed as message
role:
type: string
description: 'Message role: user, assistant, system, developer'
content:
oneOf:
- type: string
description: Text message content
- type: array
description: Content block list
items:
type: object
description: Message content, can be a string or a list of content blocks
phase:
type: string
description: 'Phase marker (assistant message): commentary, final_answer'
- description: >-
type=message, full message, content is an array of content objects,
includes status
type: object
properties:
type:
type: string
enum:
- message
description: Type, fixed as message
role:
type: string
description: 'Message role: user, assistant, system, developer'
content:
type: array
description: Message content list
items:
type: object
status:
type: string
description: 'Status: in_progress, completed, incomplete'
- description: type=item_reference, reference an existing item by ID
type: object
properties:
type:
type: string
enum:
- item_reference
description: Type, fixed as item_reference
id:
type: string
description: Referenced item ID
- description: >-
type=message, response output message, includes id, role, content,
status
type: object
properties:
type:
type: string
enum:
- message
description: Type, fixed as message
id:
type: string
description: Message unique ID
role:
type: string
description: Message role, defaults to assistant
content:
type: array
description: Message content list
items:
type: object
status:
type: string
description: 'Status: in_progress, completed, incomplete'
phase:
type: string
description: 'Phase marker: commentary, final_answer'
- description: type=function_call, function call, includes call_id, arguments, name
type: object
properties:
type:
type: string
enum:
- function_call
description: Type, fixed as function_call
id:
type: string
description: Unique ID
call_id:
type: string
description: Tool call ID
name:
type: string
description: Function name
arguments:
type: string
description: Function arguments, JSON string
status:
type: string
description: 'Status: in_progress, completed, incomplete'
namespace:
type: string
description: Namespace
caller:
type: object
description: Caller information
- description: >-
type=function_call_output, function call output, includes call_id,
output
type: object
properties:
type:
type: string
enum:
- function_call_output
description: Type, fixed as function_call_output
id:
type: string
description: Unique ID
call_id:
type: string
description: Tool call ID
output:
oneOf:
- type: string
description: Text output
- type: array
description: Output content list
items:
type: object
description: Output content
status:
type: string
description: 'Status: in_progress, completed, incomplete'
- description: >-
type=computer_call, computer interaction call, includes action,
screenshot
type: object
properties:
type:
type: string
enum:
- computer_call
description: Type, fixed as computer_call
id:
type: string
description: Computer call unique ID
call_id:
type: string
description: Tool call ID
action:
type: object
description: Tool call action
actions:
type: array
description: Tool call action list
items:
type: object
pending_safety_checks:
type: array
description: Pending safety check list
items:
type: object
status:
type: string
description: 'Status: in_progress, completed, incomplete'
- description: >-
type=computer_call_output, computer interaction output, includes
call_id, output
type: object
properties:
type:
type: string
enum:
- computer_call_output
description: Type, fixed as computer_call_output
id:
type: string
description: Unique ID
call_id:
type: string
description: Tool call ID
output:
type: object
description: Output content (screenshot)
acknowledged_safety_checks:
type: array
description: Acknowledged safety check list
items:
type: string
status:
type: string
description: 'Status: in_progress, completed, incomplete'
- description: type=web_search_call, web search call
type: object
properties:
type:
type: string
enum:
- web_search_call
description: Type, fixed as web_search_call
id:
type: string
description: Web search tool call unique ID
action:
type: object
description: Tool call action
status:
type: string
description: 'Status: in_progress, searching, completed, failed'
- description: type=file_search_call, file search call
type: object
properties:
type:
type: string
enum:
- file_search_call
description: Type, fixed as file_search_call
id:
type: string
description: File search tool call unique ID
queries:
type: array
description: Search query list
items:
type: string
results:
type: array
description: Search result list
items:
type: object
status:
type: string
description: 'Status: in_progress, searching, incomplete, failed'
- description: type=code_interpreter_call, code interpreter call
type: object
properties:
type:
type: string
enum:
- code_interpreter_call
description: Type, fixed as code_interpreter_call
id:
type: string
description: Code interpreter tool call unique ID
code:
type: string
description: Code content
container_id:
type: string
description: Container ID
outputs:
type: array
description: Output list
items:
type: object
status:
type: string
description: 'Status: in_progress, completed, incomplete, interpreting, failed'
- description: type=reasoning, reasoning process summary
type: object
properties:
type:
type: string
enum:
- reasoning
description: Type, fixed as reasoning
id:
type: string
description: Reasoning item unique ID
summary:
type: array
description: Reasoning summary list
items:
type: object
properties:
text:
type: string
type:
type: string
default: summary_text
content:
type: array
description: Reasoning content list
items:
type: object
properties:
text:
type: string
type:
type: string
default: reasoning_text
encrypted_content:
type: string
description: Encrypted reasoning content
status:
type: string
description: 'Status: in_progress, completed, incomplete'
- description: type=compaction, message compaction result
type: object
properties:
type:
type: string
enum:
- compaction
description: Type, fixed as compaction
id:
type: string
description: Unique ID
encrypted_content:
type: string
description: Encrypted compaction content
- description: type=image_generation_call, image generation call
type: object
properties:
type:
type: string
enum:
- image_generation_call
description: Type, fixed as image_generation_call
id:
type: string
description: Image generation call unique ID
result:
type: string
description: Generated image, base64 encoded
status:
type: string
description: Status
- description: type=tool_search_call, tool search call
type: object
properties:
type:
type: string
enum:
- tool_search_call
description: Type, fixed as tool_search_call
id:
type: string
description: Unique ID
call_id:
type: string
description: Tool call ID
arguments:
type: object
description: Tool search arguments
execution:
type: string
description: Execution mode
status:
type: string
description: Status
- description: type=tool_search_output, tool search output, includes output, tools
type: object
properties:
type:
type: string
enum:
- tool_search_output
description: Type, fixed as tool_search_output
id:
type: string
description: Unique ID
call_id:
type: string
description: Tool call ID
tools:
type: array
description: Tool definition list
items:
type: object
execution:
type: string
description: Execution mode
status:
type: string
description: Status
- description: >-
type=custom_tool_call, custom tool call, includes name, input,
namespace
type: object
properties:
type:
type: string
enum:
- custom_tool_call
description: Type, fixed as custom_tool_call
id:
type: string
description: Unique ID
call_id:
type: string
description: Tool call ID
name:
type: string
description: Tool name
input:
type: string
description: Input content
namespace:
type: string
description: Namespace
caller:
type: object
description: Caller information
- description: >-
type=custom_tool_call_output, custom tool output, includes call_id,
output
type: object
properties:
type:
type: string
enum:
- custom_tool_call_output
description: Type, fixed as custom_tool_call_output
id:
type: string
description: Unique ID
call_id:
type: string
description: Tool call ID
output:
oneOf:
- type: string
description: Text output
- type: array
description: Output content list
items:
type: object
description: Output content
caller:
type: object
description: Caller information
- description: type=shell_call, shell command call, includes action, environment
type: object
properties:
type:
type: string
enum:
- shell_call
description: Type, fixed as shell_call
id:
type: string
description: Unique ID
call_id:
type: string
description: Tool call ID
action:
type: object
description: Execution action
environment:
type: object
description: Execution environment
status:
type: string
description: 'Status: in_progress, completed, incomplete'
- description: >-
type=shell_call_output, shell command output, includes call_id,
output
type: object
properties:
type:
type: string
enum:
- shell_call_output
description: Type, fixed as shell_call_output
id:
type: string
description: Unique ID
call_id:
type: string
description: Tool call ID
output:
type: array
description: Output content list
items:
type: object
max_output_length:
type: integer
format: int64
description: Maximum output length
caller:
type: object
description: Caller information
status:
type: string
description: Status
- description: >-
type=local_shell_call, local shell call, includes action,
environment
type: object
properties:
type:
type: string
enum:
- local_shell_call
description: Type, fixed as local_shell_call
id:
type: string
description: Local shell call unique ID
call_id:
type: string
description: Tool call ID
action:
type: object
description: Execution action
status:
type: string
description: Status
- description: >-
type=local_shell_call_output, local shell output, includes output,
status
type: object
properties:
type:
type: string
enum:
- local_shell_call_output
description: Type, fixed as local_shell_call_output
id:
type: string
description: Unique ID
output:
type: string
description: Output content, JSON string
status:
type: string
description: 'Status: in_progress, completed, incomplete'
- description: type=apply_patch_call, patch application call, includes operation
type: object
properties:
type:
type: string
enum:
- apply_patch_call
description: Type, fixed as apply_patch_call
id:
type: string
description: Unique ID
call_id:
type: string
description: Tool call ID
operation:
type: object
description: Patch operation
status:
type: string
description: 'Status: in_progress, completed'
caller:
type: object
description: Caller information
- description: >-
type=apply_patch_call_output, patch application output, includes
output, status
type: object
properties:
type:
type: string
enum:
- apply_patch_call_output
description: Type, fixed as apply_patch_call_output
id:
type: string
description: Unique ID
call_id:
type: string
description: Tool call ID
output:
type: string
description: Output log
status:
type: string
description: 'Status: completed, failed'
caller:
type: object
description: Caller information
- description: type=mcp_call, MCP tool call, includes name, arguments
type: object
properties:
type:
type: string
enum:
- mcp_call
description: Type, fixed as mcp_call
id:
type: string
description: Tool call unique ID
name:
type: string
description: Tool name
arguments:
type: string
description: Tool arguments, JSON string
server_label:
type: string
description: MCP server label
approval_request_id:
type: string
description: Approval request ID
error:
type: string
description: Error message
output:
type: string
description: Output content
status:
type: string
description: 'Status: in_progress, completed, incomplete, calling, failed'
- description: type=mcp_approval_request, MCP approval request
type: object
properties:
type:
type: string
enum:
- mcp_approval_request
description: Type, fixed as mcp_approval_request
id:
type: string
description: Approval request unique ID
name:
type: string
description: Tool name
arguments:
type: string
description: Tool arguments, JSON string
server_label:
type: string
description: MCP server label
- description: type=mcp_approval_response, MCP approval response
type: object
properties:
type:
type: string
enum:
- mcp_approval_response
description: Type, fixed as mcp_approval_response
id:
type: string
description: Unique ID
approval_request_id:
type: string
description: Approval request ID
approve:
type: boolean
description: Whether approved
reason:
type: string
description: Approval/rejection reason
- description: type=mcp_list_tools, MCP tool list query
type: object
properties:
type:
type: string
enum:
- mcp_list_tools
description: Type, fixed as mcp_list_tools
id:
type: string
description: Unique ID
server_label:
type: string
description: MCP server label
tools:
type: array
description: Tool definition list
items:
type: object
error:
type: string
description: Error message
- description: type=program, program call, includes code, language
type: object
properties:
type:
type: string
enum:
- program
description: Type, fixed as program
id:
type: string
description: Unique ID
call_id:
type: string
description: Tool call ID
code:
type: string
description: Code content
fingerprint:
type: string
description: Fingerprint identifier
- description: >-
type=program_output, program execution output, includes stdout,
stderr, exit_code
type: object
properties:
type:
type: string
enum:
- program_output
description: Type, fixed as program_output
id:
type: string
description: Unique ID
call_id:
type: string
description: Tool call ID
result:
type: string
description: Execution result
status:
type: string
description: Status
- description: type=additional_tools, additional tool definition list
type: object
properties:
type:
type: string
enum:
- additional_tools
description: Type, fixed as additional_tools
id:
type: string
description: Unique ID
role:
type: string
description: 'Message role: user, assistant, system, developer'
tools:
type: array
description: Tool definition list
items:
$ref: '#/components/schemas/ResponseTool'
- description: type=* (any), unknown type, reserved for extension
type: object
properties:
type:
type: string
description: Unknown input item type
properties:
type:
type: string
description: >-
Input item type, used to distinguish different subtypes. Note:
multiple message subtypes share type=message, combine with other
fields for further distinction.
description: >-
OpenAI Responses API input item base class. Supports multiple input
types including message, function_call, computer_call, etc.
ResponseTool:
type: object
discriminator:
propertyName: type
oneOf:
- $ref: '#/components/schemas/ToolFunction'
- $ref: '#/components/schemas/ToolFileSearch'
- $ref: '#/components/schemas/ToolComputerUsePreview'
- $ref: '#/components/schemas/ToolWebSearchPreview'
- $ref: '#/components/schemas/ToolWebSearch'
- $ref: '#/components/schemas/ToolComputer'
- $ref: '#/components/schemas/ToolCodeInterpreter'
- $ref: '#/components/schemas/ToolImageGeneration'
- $ref: '#/components/schemas/ToolShell'
- $ref: '#/components/schemas/ToolCustom'
- $ref: '#/components/schemas/ToolNamespace'
- $ref: '#/components/schemas/ToolSearch'
- $ref: '#/components/schemas/ToolMcp'
- $ref: '#/components/schemas/ToolApplyPatch'
- $ref: '#/components/schemas/ToolLocalShell'
- $ref: '#/components/schemas/UnknownResponseTool'
properties:
type:
type: string
description: >-
Tool type, used to distinguish specific subtypes. Each type value
corresponds to a unique subtype.
description: >-
OpenAI Responses API base tool definition. Supports multiple tool types
including function, file_search, web_search_preview, etc.
ToolFunction:
type: object
properties:
type:
type: string
enum:
- function
description: Tool type, fixed as function
name:
type: string
description: Function name
description:
type: string
description: Function description
parameters:
type: object
description: Function parameter JSON Schema
strict:
type: boolean
description: Whether to enable strict schema adherence, defaults to true
defer_loading:
type: boolean
description: Whether to lazy load via tool search
description: Function tool definition
ToolFileSearch:
type: object
properties:
type:
type: string
enum:
- file_search
description: Tool type, fixed as file_search
vector_store_ids:
type: array
items:
type: string
description: Vector store ID list
filters:
type: object
description: File search filter criteria
max_num_results:
type: integer
format: int64
description: Maximum number of results to return
ranking_options:
type: object
description: Sorting options
description: File search tool definition
ToolComputerUsePreview:
type: object
properties:
type:
type: string
enum:
- computer_use_preview
description: Tool type, fixed as computer_use_preview
display_height:
type: integer
format: int64
description: Computer display height
display_width:
type: integer
format: int64
description: Computer display width
environment:
type: object
description: 'Runtime environment: browser, mac, windows, ubuntu, etc.'
description: Virtual computer control tool definition (preview)
ToolWebSearchPreview:
type: object
properties:
type:
type: string
enum:
- web_search_preview
description: Tool type, fixed as web_search_preview
search_content_types:
type: array
items:
type: string
description: Search content type list
search_context_size:
type: string
description: 'Search context size: low, medium, high'
user_location:
$ref: '#/components/schemas/UserLocation'
description: Web search preview tool definition
ToolWebSearch:
type: object
properties:
type:
type: string
enum:
- web_search
description: Tool type, fixed as web_search
filters:
type: object
description: Search filter criteria
search_context_size:
type: string
description: 'Search context size: low, medium, high'
user_location:
$ref: '#/components/schemas/UserLocation'
description: Web search tool definition
ToolComputer:
type: object
properties:
type:
type: string
enum:
- computer
description: Tool type, fixed as computer
description: Virtual computer control tool definition
ToolCodeInterpreter:
type: object
properties:
type:
type: string
enum:
- code_interpreter
description: Tool type, fixed as code_interpreter
container:
type: object
description: >-
Code interpreter container, can be a container ID or an object
containing file ID and memory limit
description: Code interpreter tool definition
ToolImageGeneration:
type: object
properties:
type:
type: string
enum:
- image_generation
description: Tool type, fixed as image_generation
action:
type: string
description: 'Image generation action: auto, generate, edit'
background:
type: string
description: 'Background transparency: transparent, opaque, auto'
input_fidelity:
type: string
description: 'Input image fidelity: high, low'
input_image_mask:
type: object
description: Optional inpainting mask
model:
type: string
description: Image generation model
moderation:
type: string
description: 'Content moderation level: auto, low, high'
output_compression:
type: integer
format: int64
description: Output image compression level
output_format:
type: string
description: 'Output format: png, webp, jpeg'
partial_images:
type: integer
format: int64
description: Number of partial images generated in streaming mode
quality:
type: string
description: 'Image quality: low, medium, high, auto'
size:
type: string
description: Image size
description: Image generation tool definition
ToolShell:
type: object
properties:
type:
type: string
enum:
- shell
description: Tool type, fixed as shell
environment:
type: object
description: Environment configuration
description: Shell tool definition
ToolCustom:
type: object
properties:
type:
type: string
enum:
- custom
description: Tool type, fixed as custom
name:
type: string
description: Custom tool name, used to identify in tool calls
description:
type: string
description: Custom tool description
defer_loading:
type: boolean
description: Whether to lazy load via tool search
format:
$ref: '#/components/schemas/ToolFormat'
description: Custom tool definition
ToolNamespace:
type: object
properties:
type:
type: string
enum:
- namespace
description: Tool type, fixed as namespace
name:
type: string
description: Namespace name, used for tool calls
description:
type: string
description: Namespace description, shown to the model
tools:
type: array
items:
$ref: '#/components/schemas/ResponseTool'
description: List of function/custom tools under the namespace
description: Namespace tool definition
ToolSearch:
type: object
properties:
type:
type: string
enum:
- tool_search
description: Tool type, fixed as tool_search
description:
type: string
description: Tool search description, shown to the model
execution:
type: string
description: 'Execution mode: server or client'
parameters:
type: object
description: Parameter schema for client-side tool search execution
description: Tool search configuration definition
ToolMcp:
type: object
properties:
type:
type: string
enum:
- mcp
description: Tool type, fixed as mcp
server_label:
type: string
description: MCP server label, used to identify in tool calls
allowed_tools:
type: object
description: Allowed tool list or filter object
authorization:
type: string
description: OAuth access token
connector_id:
type: string
description: Service connector identifier
defer_loading:
type: boolean
description: Whether to lazy load
headers:
type: object
description: Server-side HTTP request headers
require_approval:
type: object
description: Tool approval configuration
server_description:
type: string
description: Server description
server_url:
type: string
description: Server-side URL
tunnel_id:
type: string
description: Secure MCP Tunnel ID
description: MCP (Model Context Protocol) remote tool definition
ToolApplyPatch:
type: object
properties:
type:
type: string
enum:
- apply_patch
description: Tool type, fixed as apply_patch
description: >-
Apply Patch tool definition, allows the assistant to create, delete, or
update files using unified diff
ToolLocalShell:
type: object
properties:
type:
type: string
enum:
- local_shell
description: Tool type, fixed as local_shell
additionalProperties: true
description: >-
Local Shell tool definition, allows the model to execute shell commands
in the local environment
UnknownResponseTool:
type: object
properties:
type:
type: string
description: Unknown tool type, used as fallback
additionalProperties: true
description: Unknown tool type fallback implementation
UserLocation:
type: object
properties:
type:
type: string
description: Location approximation type, always approximate
default: approximate
city:
type: string
description: City
country:
type: string
description: Country (two-letter ISO code)
region:
type: string
description: Region
timezone:
type: string
description: Time zone
description: User geolocation
ToolFormat:
type: object
properties:
type:
type: string
description: Format type
description: Custom tool input format
````