OpenAI Responses API

Create a model response using the Responses API. Supports text, image, and file inputs to generate text or JSON outputs. Can call custom functions or built-in tools (web search, file search, etc.). Suitable for multimodal conversations, function calling, reasoning models, and more.

Endpoint

POST /v1/responses

Authentication

Method	Description
Bearer Token	Include Authorization: Bearer <API_key> in the request header for authentication.

Request Headers

Parameter	Type	Required	Description
Content-Type	string	Yes	Media type of the request body, set to application/json
Authorization	string	Yes	Bearer API_key for authentication

Request Body

Basic Parameters

Parameter	Type	Required	Default	Description
model	string	Yes	-	Model ID, e.g. gpt-4o, o3
input	string or array	No	-	Input content, can be a plain text string or a message array. Supports text, image, file input types
instructions	string	No	-	System/developer message inserted into model context. Previous instructions are not carried over when used with previous_response_id
store	boolean	No	true	Whether to store the response for later retrieval via API
stream	boolean	No	false	Whether to enable SSE streaming output
temperature	number	No	1	Sampling temperature, range 0~2. Higher values produce more random output
top_p	number	No	1	Nucleus sampling threshold, range 0~1.0. E.g. 0.1 means only top 10% probability tokens
top_logprobs	number	No	-	Number of most likely tokens to return per position, range 0~20
truncation	string	No	disabled	Truncation strategy. auto: auto-truncate long input; disabled: return 400 error on overflow
metadata	object	No	-	Key-value metadata, up to 16 pairs, keys max 64 chars, values max 512 chars
user	string	No	-	User identifier. Deprecated, use safety_identifier and prompt_cache_key instead
safety_identifier	string	No	-	Safety identifier for abuse detection. Max 64 chars, recommend hashing
service_tier	string	No	auto	Service tier. Options: auto/default/flex/scale/priority/fast/ultrafast
background	boolean	No	false	Whether to run the model response in the background
max_output_tokens	number	No	-	Maximum tokens for the response (including reasoning tokens)
parallel_tool_calls	boolean	No	true	Whether to allow parallel tool calls
previous_response_id	string	No	-	Previous response ID for multi-turn conversations. Cannot be used with conversation
conversation	string or object	No	-	Conversation association. Pass a conversation ID or { id } object
max_tool_calls	number	No	-	Maximum total built-in tool calls across all tools
include	array	No	-	Additional output data to include, e.g. file_search_call.results, web_search_call.action.sources, message.output_text.logprobs

Reasoning Parameters

Parameter	Type	Required	Default	Description
reasoning	object	No	-	Reasoning configuration (gpt-5 and o-series models only)

reasoning Details

Parameter	Type	Required	Default	Description
effort	string	No	-	Reasoning effort. Options: none/minimal/low/medium/high/xhigh/max
summary	string	No	-	Reasoning summary. Options: auto/concise/detailed
context	string	No	auto	Reasoning context mode. auto: model decides; current_turn: current turn only; all_turns: all turns
mode	string	No	-	Reasoning execution mode. Options: standard/pro
generate_summary	string	No	-	Deprecated, use summary instead

Text Format Parameters

Parameter	Type	Required	Default	Description
text	object	No	-	Text response format configuration

text Details

Parameter	Type	Required	Default	Description
format	object	No	{"type":"text"}	Output format. text: plain text; json_schema: structured JSON (recommended); json_object: legacy JSON mode
verbosity	string	No	medium	Response verbosity. Options: low/medium/high

text.format (json_schema mode)

Parameter	Type	Required	Default	Description
type	string	Yes	-	Always json_schema
name	string	Yes	-	Format name, a-z/A-Z/0-9/underscore/hyphen, max 64 chars
schema	object	Yes	-	JSON Schema object describing the response structure
description	string	No	-	Format description
strict	boolean	No	-	Whether to enforce strict schema adherence

Tool Parameters

Parameter	Type	Required	Default	Description
tools	array	No	-	Tool list. Supports Function, FileSearch, WebSearch, Computer, CodeInterpreter, ImageGeneration, MCP, Custom, etc.
tool_choice	string or object	No	auto	Tool selection strategy. none: no tools; auto: model decides; required: must call; or specify a specific tool

Supported tools Types

Type	type value	Description
Custom function	function	Define name, parameters (JSON Schema), description, strict
File search	file_search	Requires vector_store_ids, optional max_num_results, filters, ranking_options
Web search	web_search / web_search_preview	Optional search_context_size (low/medium/high), user_location, filters.allowed_domains
Computer control	computer / computer_use_preview	Control a virtual computer, requires display_width, display_height, environment
Code interpreter	code_interpreter	Run Python code, optional container (container ID or auto config)
Image generation	image_generation	Generate/edit images with GPT image models, optional quality, size, output_format, etc.
MCP tool	mcp	Connect to remote MCP servers, requires server_label, server_url/connector_id/tunnel_id
Custom tool	custom	Custom format tool, define name, description, format
Namespace	namespace	Group function/custom tools under a shared namespace
Tool search	tool_search	Deferred tool discovery configuration
Local shell	local_shell / shell	Allow model to execute shell commands
Apply patch	apply_patch	Create/delete/update files using unified diffs

Cache Parameters

Parameter	Type	Required	Default	Description
prompt_cache_key	string	No	-	Cache key, replaces user field for cache optimization
prompt_cache_options	object	No	-	Cache options (gpt-5.6+ supported)
prompt_cache_retention	string	No	-	Deprecated, use prompt_cache_options.ttl. Options: in_memory/24h

prompt_cache_options Details

Parameter	Type	Required	Default	Description
mode	string	No	implicit	Cache mode. implicit: auto implicit breakpoints; explicit: explicit breakpoints only
ttl	string	No	30m	Minimum cache lifetime, currently only 30m supported

Moderation Parameters

Parameter	Type	Required	Default	Description
moderation	object	No	-	Content moderation configuration

moderation Details

Parameter	Type	Required	Default	Description
model	string	No	-	Moderation model, e.g. omni-moderation-latest
policy	object	No	-	Moderation policy
policy.input.mode	string	No	-	Input moderation mode: score/block
policy.output.mode	string	No	-	Output moderation mode: score/block

Context Management Parameters

Parameter	Type	Required	Default	Description
context_management	array	No	-	Context management configuration

context_management Details

Parameter	Type	Required	Default	Description
type	string	Yes	-	Context management type, currently only compaction supported
compact_threshold	number	No	-	Token threshold to trigger compaction

Prompt Template Parameters

Parameter	Type	Required	Default	Description
prompt	object	No	-	Prompt template reference

prompt Details

Parameter	Type	Required	Default	Description
id	string	Yes	-	Prompt template unique identifier
variables	object	No	-	Template variable map, values are strings or input content types
version	string	No	-	Template version

Streaming Parameters

Parameter	Type	Required	Default	Description
stream_options	object	No	-	Streaming response options, only effective when stream: true

stream_options Details

Parameter	Type	Required	Default	Description
include_obfuscation	boolean	No	true	Whether to enable stream obfuscation (adds random characters to normalize payload sizes)

input Content Types

input can be a plain text string or a message array. Message objects support the following content types:

Content type	type value	Description
Text	input_text	Text input, field: text
Image	input_image	Image input, fields: image_url (URL or base64), file_id, detail (low/high/auto/original)
File	input_file	File input, fields: file_url, file_id, file_data, filename, detail (auto/low/high)

Message role options: user, assistant, system, developer.

Response Body

Parameter	Type	Description
id	string	Unique response identifier
object	string	Resource type, always response
created_at	number	Creation time (Unix timestamp in seconds)
completed_at	number or null	Completion time (Unix timestamp in seconds), only present when status is completed
status	string	Response status: completed/failed/in_progress/cancelled/queued/incomplete
error	object or null	Error info, contains code and message
incomplete_details	object or null	Incomplete reason, reason: max_output_tokens/content_filter
instructions	string or null	Inserted system/developer message
model	string	Model ID used
output	array	Array of model-generated content items, including messages, tool calls, etc.
output_text	string or null	SDK convenience property, aggregates text from all output_text items (Python/JS SDK only)
parallel_tool_calls	boolean	Whether parallel tool calls are allowed
previous_response_id	string or null	Previous response ID
reasoning	object or null	Reasoning configuration (effort/summary/context/mode)
service_tier	string or null	Actual service tier used
temperature	number or null	Sampling temperature
text	object or null	Text format configuration (format/verbosity)
tool_choice	string or object	Tool selection strategy
tools	array	Tool list
top_p	number or null	Nucleus sampling threshold
top_logprobs	number or null	Logprobs return count
truncation	string or null	Truncation strategy
usage	object or null	Token usage statistics
background	boolean or null	Whether running in background
conversation	object or null	Conversation info, contains id
max_output_tokens	number or null	Max output tokens
max_tool_calls	number or null	Max tool calls
moderation	object or null	Moderation results (input/output)
prompt	object or null	Prompt template reference
prompt_cache_key	string or null	Cache key
prompt_cache_options	object or null	Cache options (mode/ttl)
prompt_cache_retention	string or null	Cache retention policy
safety_identifier	string or null	Safety identifier
store	boolean or null	Whether response is stored
metadata	object or null	Metadata
user	string or null	User identifier

output Array Item Types

Type	type value	Description
Message	message	Model output message, contains content (output_text/refusal), role (assistant), status, phase
Function call	function_call	Function tool call, contains arguments, call_id, name, status
Function call output	function_call_output	Function execution result, contains output, call_id
File search call	file_search_call	File search results, contains queries, results, status
Web search call	web_search_call	Web search results, contains status, action
Reasoning	reasoning	Reasoning process, contains summary, encrypted_content
Code interpreter call	code_interpreter_call	Code execution result
Computer call	computer_call	Computer operation call

usage Object

Parameter	Type	Description
input_tokens	number	Input token count
output_tokens	number	Output token count
total_tokens	number	Total token count
input_tokens_details.cached_tokens	number	Cache hit token count
input_tokens_details.cache_write_tokens	number	Cache write token count
output_tokens_details.reasoning_tokens	number	Reasoning token count

Basic Text Conversation

cURL

curl --location --request POST 'https://neolink.com/api/v1/responses' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <API Key>' \
     --data-raw '{
         "model": "<Model ID>",
         "input": "Tell me a three sentence bedtime story about a unicorn."
     }'

Python

import requests

url = "https://neolink.com/api/v1/responses"

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <API Key>",
}

payload = {
    "model": "<Model ID>",
    "input": "Tell me a three sentence bedtime story about a unicorn."
}

response = requests.post(url, headers=headers, json=payload, timeout=30)
response.raise_for_status()
result = response.json()
print(result)

Multimodal Request (Image Input)

cURL

curl --location --request POST 'https://neolink.com/api/v1/responses' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <API Key>' \
     --data-raw '{
         "model": "<Model ID>",
         "input": [
             {
                 "role": "user",
                 "content": [
                     {"type": "input_text", "text": "What is in this image?"},
                     {"type": "input_image", "image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"}
                 ]
             }
         ]
     }'

Python

import requests

url = "https://neolink.com/api/v1/responses"

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <API Key>",
}

payload = {
    "model": "<Model ID>",
    "input": [
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "What is in this image?"},
                {"type": "input_image", "image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"}
            ]
        }
    ]
}

response = requests.post(url, headers=headers, json=payload, timeout=30)
response.raise_for_status()
result = response.json()
print(result)

File Input

cURL

curl --location --request POST 'https://neolink.com/api/v1/responses' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <API Key>' \
     --data-raw '{
         "model": "<Model ID>",
         "input": [
             {
                 "role": "user",
                 "content": [
                     {"type": "input_text", "text": "What is in this file?"},
                     {"type": "input_file", "file_url": "https://example.com/document.pdf", "detail": "auto"}
                 ]
             }
         ]
     }'

Python

import requests

url = "https://neolink.com/api/v1/responses"

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <API Key>",
}

payload = {
    "model": "<Model ID>",
    "input": [
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "What is in this file?"},
                {"type": "input_file", "file_url": "https://example.com/document.pdf", "detail": "auto"}
            ]
        }
    ]
}

response = requests.post(url, headers=headers, json=payload, timeout=30)
response.raise_for_status()
result = response.json()
print(result)

Function Calling

cURL

curl --location --request POST 'https://neolink.com/api/v1/responses' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <API Key>' \
     --data-raw '{
         "model": "<Model ID>",
         "input": "What is the weather like in Boston today?",
         "tools": [
             {
                 "type": "function",
                 "name": "get_current_weather",
                 "description": "Get the current weather in a given location",
                 "parameters": {
                     "type": "object",
                     "properties": {
                         "location": {"type": "string", "description": "The city and state, e.g. San Francisco, CA"},
                         "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
                     },
                     "required": ["location", "unit"]
                 }
             }
         ],
         "tool_choice": "auto"
     }'

Python

import requests

url = "https://neolink.com/api/v1/responses"

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <API Key>",
}

payload = {
    "model": "<Model ID>",
    "input": "What is the weather like in Boston today?",
    "tools": [
        {
            "type": "function",
            "name": "get_current_weather",
            "description": "Get the current weather in a given location",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {"type": "string", "description": "The city and state, e.g. San Francisco, CA"},
                    "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
                },
                "required": ["location", "unit"]
            }
        }
    ],
    "tool_choice": "auto"
}

response = requests.post(url, headers=headers, json=payload, timeout=30)
response.raise_for_status()
result = response.json()
print(result)

Web Search

cURL

curl --location --request POST 'https://neolink.com/api/v1/responses' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <API Key>' \
     --data-raw '{
         "model": "<Model ID>",
         "input": "What was a positive news story from today?",
         "tools": [{"type": "web_search_preview"}]
     }'

Python

import requests

url = "https://neolink.com/api/v1/responses"

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <API Key>",
}

payload = {
    "model": "<Model ID>",
    "input": "What was a positive news story from today?",
    "tools": [{"type": "web_search_preview"}]
}

response = requests.post(url, headers=headers, json=payload, timeout=30)
response.raise_for_status()
result = response.json()
print(result)

File Search

cURL

curl --location --request POST 'https://neolink.com/api/v1/responses' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <API Key>' \
     --data-raw '{
         "model": "<Model ID>",
         "input": "What are the attributes of an ancient brown dragon?",
         "tools": [
             {
                 "type": "file_search",
                 "vector_store_ids": ["vs_1234567890"],
                 "max_num_results": 20
             }
         ]
     }'

Python

import requests

url = "https://neolink.com/api/v1/responses"

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <API Key>",
}

payload = {
    "model": "<Model ID>",
    "input": "What are the attributes of an ancient brown dragon?",
    "tools": [
        {
            "type": "file_search",
            "vector_store_ids": ["vs_1234567890"],
            "max_num_results": 20
        }
    ]
}

response = requests.post(url, headers=headers, json=payload, timeout=30)
response.raise_for_status()
result = response.json()
print(result)

Reasoning Model

cURL

curl --location --request POST 'https://neolink.com/api/v1/responses' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <API Key>' \
     --data-raw '{
         "model": "<Model ID>",
         "input": "How much wood would a woodchuck chuck?",
         "reasoning": {
             "effort": "high"
         }
     }'

Python

import requests

url = "https://neolink.com/api/v1/responses"

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <API Key>",
}

payload = {
    "model": "<Model ID>",
    "input": "How much wood would a woodchuck chuck?",
    "reasoning": {
        "effort": "high"
    }
}

response = requests.post(url, headers=headers, json=payload, timeout=30)
response.raise_for_status()
result = response.json()
print(result)

Streaming

cURL

curl --location --request POST 'https://neolink.com/api/v1/responses' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <API Key>' \
     --data-raw '{
         "model": "<Model ID>",
         "instructions": "You are a helpful assistant.",
         "input": "Hello!",
         "stream": true
     }'

Python

import requests

url = "https://neolink.com/api/v1/responses"

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <API Key>",
}

payload = {
    "model": "<Model ID>",
    "instructions": "You are a helpful assistant.",
    "input": "Hello!",
    "stream": True
}

response = requests.post(url, headers=headers, json=payload, timeout=30, stream=True)
for line in response.iter_lines():
    if line:
        print(line.decode("utf-8"))

Streaming responses use SSE format. Main event types:

Event	Description
response.created	Response created
response.in_progress	Response in progress
response.output_item.added	Output item added
response.content_part.added	Content part added
response.output_text.delta	Text delta
response.output_text.done	Text output done
response.content_part.done	Content part done
response.output_item.done	Output item done
response.completed	Response completed

Structured Output (JSON Schema)

cURL

curl --location --request POST 'https://neolink.com/api/v1/responses' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <API Key>' \
     --data-raw '{
         "model": "<Model ID>",
         "input": "List three fruits and their colors",
         "text": {
             "format": {
                 "type": "json_schema",
                 "name": "fruit_list",
                 "schema": {
                     "type": "object",
                     "properties": {
                         "fruits": {
                             "type": "array",
                             "items": {
                                 "type": "object",
                                 "properties": {
                                     "name": {"type": "string"},
                                     "color": {"type": "string"}
                                 },
                                 "required": ["name", "color"]
                             }
                         }
                     },
                     "required": ["fruits"]
                 },
                 "strict": true
             }
         }
     }'

Python

import requests

url = "https://neolink.com/api/v1/responses"

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <API Key>",
}

payload = {
    "model": "<Model ID>",
    "input": "List three fruits and their colors",
    "text": {
        "format": {
            "type": "json_schema",
            "name": "fruit_list",
            "schema": {
                "type": "object",
                "properties": {
                    "fruits": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "name": {"type": "string"},
                                "color": {"type": "string"}
                            },
                            "required": ["name", "color"]
                        }
                    }
                },
                "required": ["fruits"]
            },
            "strict": True
        }
    }
}

response = requests.post(url, headers=headers, json=payload, timeout=30)
response.raise_for_status()
result = response.json()
print(result)

Multi-turn Conversation

Use previous_response_id for multi-turn conversations:

cURL

curl --location --request POST 'https://neolink.com/api/v1/responses' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <API Key>' \
     --data-raw '{
         "model": "<Model ID>",
         "previous_response_id": "resp_abc123",
         "input": "Please re-answer the previous question in Chinese."
     }'

Python

import requests

url = "https://neolink.com/api/v1/responses"

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <API Key>",
}

payload = {
    "model": "<Model ID>",
    "previous_response_id": "resp_abc123",
    "input": "Please re-answer the previous question in Chinese."
}

response = requests.post(url, headers=headers, json=payload, timeout=30)
response.raise_for_status()
result = response.json()
print(result)

Response Example

{
  "id": "resp_67ccd2bed1ec8190b14f964abc0542670bb6a6b452d3795b",
  "object": "response",
  "created_at": 1741476542,
  "status": "completed",
  "completed_at": 1741476543,
  "error": null,
  "incomplete_details": null,
  "instructions": null,
  "max_output_tokens": null,
  "model": "gpt-5.4",
  "output": [
    {
      "type": "message",
      "id": "msg_67ccd2bf17f0819081ff3bb2cf6508e60bb6a6b452d3795b",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "In a peaceful grove beneath a silver moon, a unicorn named Lumina discovered a hidden pool...",
          "annotations": []
        }
      ]
    }
  ],
  "parallel_tool_calls": true,
  "previous_response_id": null,
  "reasoning": {
    "effort": null,
    "summary": null
  },
  "store": true,
  "temperature": 1.0,
  "text": {
    "format": {"type": "text"}
  },
  "tool_choice": "auto",
  "tools": [],
  "top_p": 1.0,
  "truncation": "disabled",
  "usage": {
    "input_tokens": 36,
    "input_tokens_details": {
      "cached_tokens": 0,
      "cache_write_tokens": 0
    },
    "output_tokens": 87,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 123
  },
  "metadata": {}
}

Streaming Response Example

event: response.created
data: {"type":"response.created","response":{"id":"resp_abc","object":"response","created_at":1741290958,"status":"in_progress","model":"gpt-5.4","output":[]}}

event: response.output_item.added
data: {"type":"response.output_item.added","output_index":0,"item":{"id":"msg_abc","type":"message","status":"in_progress","role":"assistant","content":[]}}

event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_abc","output_index":0,"content_index":0,"delta":"Hi"}

event: response.output_text.done
data: {"type":"response.output_text.done","item_id":"msg_abc","output_index":0,"content_index":0,"text":"Hi there! How can I assist you today?"}

event: response.completed
data: {"type":"response.completed","response":{"id":"resp_abc","object":"response","status":"completed","output":[{"id":"msg_abc","type":"message","status":"completed","role":"assistant","content":[{"type":"output_text","text":"Hi there! How can I assist you today?","annotations":[]}]}],"usage":{"input_tokens":37,"output_tokens":11,"total_tokens":48}}}

Supported Model IDs:

• <Model ID> (Refer to the model list for available models)