Skip to content
Lightcone Lightcone
NorthstarPlatformPricingLogin
API Reference
Responses

Create Responses

client.responses.create(ResponseCreateParams { input, background, cache_salt, 31 more } body, RequestOptionsoptions?): ResponseCreateResponse { id, created_at, model, 6 more }
POST/v1/responses

Create Responses

ParametersExpand Collapse
body: ResponseCreateParams { input, background, cache_salt, 31 more }
input: string | Array<EasyInputMessageParam { content, role, type } | Message { content, role, status, type } | ResponseOutputMessageParam { id, content, role, 2 more } | 41 more>
One of the following:
string
Array<EasyInputMessageParam { content, role, type } | Message { content, role, status, type } | ResponseOutputMessageParam { id, content, role, 2 more } | 41 more>
EasyInputMessageParam { content, role, type }

A message input to the model with a role indicating instruction following hierarchy. Instructions given with the developer or system role take precedence over instructions given with the user role. Messages with the assistant role are presumed to have been generated by the model in previous interactions.

content: string | Array<ResponseInputTextParam { text, type } | ResponseInputImageParam { detail, type, file_id, image_url } | ResponseInputFileParam { type, file_data, file_id, 2 more } >
One of the following:
string
Array<ResponseInputTextParam { text, type } | ResponseInputImageParam { detail, type, file_id, image_url } | ResponseInputFileParam { type, file_data, file_id, 2 more } >
ResponseInputTextParam { text, type }

A text input to the model.

text: string
type: "input_text"
ResponseInputImageParam { detail, type, file_id, image_url }

An image input to the model.

Learn about image inputs.

detail: "low" | "high" | "auto"
One of the following:
"low"
"high"
"auto"
type: "input_image"
file_id?: string | null
image_url?: string | null
ResponseInputFileParam { type, file_data, file_id, 2 more }

A file input to the model.

type: "input_file"
file_data?: string
file_id?: string | null
file_url?: string
filename?: string
role: "user" | "assistant" | "system" | "developer"
One of the following:
"user"
"assistant"
"system"
"developer"
type?: "message"
Message { content, role, status, type }

A message input to the model with a role indicating instruction following hierarchy. Instructions given with the developer or system role take precedence over instructions given with the user role.

content: Array<ResponseInputTextParam { text, type } | ResponseInputImageParam { detail, type, file_id, image_url } | ResponseInputFileParam { type, file_data, file_id, 2 more } >
One of the following:
ResponseInputTextParam { text, type }

A text input to the model.

text: string
type: "input_text"
ResponseInputImageParam { detail, type, file_id, image_url }

An image input to the model.

Learn about image inputs.

detail: "low" | "high" | "auto"
One of the following:
"low"
"high"
"auto"
type: "input_image"
file_id?: string | null
image_url?: string | null
ResponseInputFileParam { type, file_data, file_id, 2 more }

A file input to the model.

type: "input_file"
file_data?: string
file_id?: string | null
file_url?: string
filename?: string
role: "user" | "system" | "developer"
One of the following:
"user"
"system"
"developer"
status?: "in_progress" | "completed" | "incomplete"
One of the following:
"in_progress"
"completed"
"incomplete"
type?: "message"
ResponseOutputMessageParam { id, content, role, 2 more }

An output message from the model.

id: string
content: Array<ResponseOutputTextParam { annotations, text, type, logprobs } | ResponseOutputRefusalParam { refusal, type } >
One of the following:
ResponseOutputTextParam { annotations, text, type, logprobs }

A text output from the model.

annotations: Array<AnnotationFileCitation { file_id, filename, index, type } | AnnotationURLCitation { end_index, start_index, title, 2 more } | AnnotationContainerFileCitation { container_id, end_index, file_id, 3 more } | AnnotationFilePath { file_id, index, type } >
One of the following:
AnnotationFileCitation { file_id, filename, index, type }

A citation to a file.

file_id: string
filename: string
index: number
type: "file_citation"
AnnotationURLCitation { end_index, start_index, title, 2 more }

A citation for a web resource used to generate a model response.

end_index: number
start_index: number
title: string
type: "url_citation"
url: string
AnnotationContainerFileCitation { container_id, end_index, file_id, 3 more }

A citation for a container file used to generate a model response.

container_id: string
end_index: number
file_id: string
filename: string
start_index: number
type: "container_file_citation"
AnnotationFilePath { file_id, index, type }

A path to a file.

file_id: string
index: number
type: "file_path"
text: string
type: "output_text"
logprobs?: Array<Logprob { token, bytes, logprob, top_logprobs } >
token: string
bytes: Array<number>
logprob: number
top_logprobs: Array<TopLogprob>
token: string
bytes: Array<number>
logprob: number
ResponseOutputRefusalParam { refusal, type }

A refusal from the model.

refusal: string
type: "refusal"
role: "assistant"
status: "in_progress" | "completed" | "incomplete"
One of the following:
"in_progress"
"completed"
"incomplete"
type: "message"
ResponseFileSearchToolCallParam { id, queries, status, 2 more }

The results of a file search tool call.

See the file search guide for more information.

id: string
queries: Array<string>
status: "in_progress" | "searching" | "completed" | 2 more
One of the following:
"in_progress"
"searching"
"completed"
"incomplete"
"failed"
type: "file_search_call"
results?: Array<Result> | null
attributes?: Record<string, string | number | boolean> | null
One of the following:
string
number
boolean
file_id?: string
filename?: string
score?: number
text?: string
ResponseComputerToolCallParam { id, action, call_id, 3 more }

A tool call to a computer use tool.

See the computer use guide for more information.

id: string
action: ActionClick { button, type, x, y } | ActionDoubleClick { type, x, y } | ActionDrag { path, type } | 11 more

A click action.

One of the following:
ActionClick { button, type, x, y }

A click action.

button: "left" | "right" | "wheel" | 2 more
One of the following:
"left"
"right"
"wheel"
"back"
"forward"
type: "click"
x: number
y: number
ActionDoubleClick { type, x, y }

A double click action.

type: "double_click"
x: number
y: number
ActionDrag { path, type }

A drag action.

path: Array<Path>
x: number
y: number
type: "drag"
ActionKeypress { keys, type }

A collection of keypresses the model would like to perform.

keys: Array<string>
type: "keypress"
ActionMove { type, x, y }

A mouse move action.

type: "move"
x: number
y: number
ActionScreenshot { type }

A screenshot action.

type: "screenshot"
ActionScroll { scroll_x, scroll_y, type, 2 more }

A scroll action.

scroll_x: number
scroll_y: number
type: "scroll"
x: number
y: number
ActionType { text, type }

An action to type in text.

text: string
type: "type"
ActionWait { type }

A wait action.

type: "wait"
ActionPointAndType { text, type, x, y }

Click at a position then type text.

text: string
type: "point_and_type"
x: number
y: number
ActionMouseDown { type, x, y }

Press and hold the left mouse button at a position.

type: "mouse_down"
x: number
y: number
ActionMouseUp { type, x, y }

Release the left mouse button at a position.

type: "mouse_up"
x: number
y: number
ActionKeyDown { keys, type }

Press and hold a key.

keys: Array<string>
type: "key_down"
ActionKeyUp { keys, type }

Release a held key.

keys: Array<string>
type: "key_up"
call_id: string
pending_safety_checks: Array<PendingSafetyCheck>
id: string
code?: string | null
message?: string | null
status: "in_progress" | "completed" | "incomplete"
One of the following:
"in_progress"
"completed"
"incomplete"
type: "computer_call"
ComputerCallOutput { call_id, output, type, 3 more }

The output of a computer tool call.

call_id: string
output: Output { type, file_id, image_url }

A computer screenshot image used with the computer use tool.

type: "computer_screenshot"
file_id?: string
image_url?: string
type: "computer_call_output"
id?: string | null
acknowledged_safety_checks?: Array<AcknowledgedSafetyCheck> | null
id: string
code?: string | null
message?: string | null
status?: "in_progress" | "completed" | "incomplete" | null
One of the following:
"in_progress"
"completed"
"incomplete"
ResponseFunctionWebSearchParam { id, action, status, type }

The results of a web search tool call.

See the web search guide for more information.

id: string
action: ActionSearch { query, type, queries, sources } | ActionOpenPage { type, url } | ActionFind { pattern, type, url }

Action type "search" - Performs a web search query.

One of the following:
ActionSearch { query, type, queries, sources }

Action type "search" - Performs a web search query.

query: string
type: "search"
queries?: Array<string>
sources?: Array<ActionSearchSource { type, url } >
type: "url"
url: string
ActionOpenPage { type, url }

Action type "open_page" - Opens a specific URL from search results.

type: "open_page"
url: string
ActionFind { pattern, type, url }

Action type "find": Searches for a pattern within a loaded page.

pattern: string
type: "find"
url: string
status: "in_progress" | "searching" | "completed" | "failed"
One of the following:
"in_progress"
"searching"
"completed"
"failed"
type: "web_search_call"
ResponseFunctionToolCallParam { arguments, call_id, name, 3 more }

A tool call to run a function.

See the function calling guide for more information.

arguments: string
call_id: string
name: string
type: "function_call"
id?: string
status?: "in_progress" | "completed" | "incomplete"
One of the following:
"in_progress"
"completed"
"incomplete"
FunctionCallOutput { call_id, output, type, 2 more }

The output of a function tool call.

call_id: string
output: string | Array<ResponseInputTextContentParam { text, type } | ResponseInputImageContentParam { type, detail, file_id, image_url } | ResponseInputFileContentParam { type, file_data, file_id, 2 more } >
One of the following:
string
Array<ResponseInputTextContentParam { text, type } | ResponseInputImageContentParam { type, detail, file_id, image_url } | ResponseInputFileContentParam { type, file_data, file_id, 2 more } >
ResponseInputTextContentParam { text, type }

A text input to the model.

text: string
type: "input_text"
ResponseInputImageContentParam { type, detail, file_id, image_url }

An image input to the model.

Learn about image inputs

type: "input_image"
detail?: "low" | "high" | "auto" | null
One of the following:
"low"
"high"
"auto"
file_id?: string | null
image_url?: string | null
ResponseInputFileContentParam { type, file_data, file_id, 2 more }

A file input to the model.

type: "input_file"
file_data?: string | null
file_id?: string | null
file_url?: string | null
filename?: string | null
type: "function_call_output"
id?: string | null
status?: "in_progress" | "completed" | "incomplete" | null
One of the following:
"in_progress"
"completed"
"incomplete"
ResponseReasoningItemParam { id, summary, type, 3 more }

A description of the chain of thought used by a reasoning model while generating a response. Be sure to include these items in your input to the Responses API for subsequent turns of a conversation if you are manually managing context.

id: string
summary: Array<Summary { text, type } >
text: string
type: "summary_text"
type: "reasoning"
content?: Array<Content>
text: string
type: "reasoning_text"
encrypted_content?: string | null
status?: "in_progress" | "completed" | "incomplete"
One of the following:
"in_progress"
"completed"
"incomplete"
ResponseCompactionItemParamParam { encrypted_content, type, id }

A compaction item generated by the v1/responses/compact API.

encrypted_content: string
type: "compaction"
id?: string | null
ImageGenerationCall { id, result, status, type }

An image generation request made by the model.

id: string
result: string | null
status: "in_progress" | "completed" | "generating" | "failed"
One of the following:
"in_progress"
"completed"
"generating"
"failed"
type: "image_generation_call"
ResponseCodeInterpreterToolCallParam { id, code, container_id, 3 more }

A tool call to run code.

id: string
code: string | null
container_id: string
outputs: Array<OutputLogs { logs, type } | OutputImage { type, url } > | null
One of the following:
OutputLogs { logs, type }

The logs output from the code interpreter.

logs: string
type: "logs"
OutputImage { type, url }

The image output from the code interpreter.

type: "image"
url: string
status: "in_progress" | "completed" | "incomplete" | 2 more
One of the following:
"in_progress"
"completed"
"incomplete"
"interpreting"
"failed"
type: "code_interpreter_call"
LocalShellCall { id, action, call_id, 2 more }

A tool call to run a command on the local shell.

id: string
action: Action { command, env, type, 3 more }

Execute a shell command on the server.

command: Array<string>
env: Record<string, string>
type: "exec"
timeout_ms?: number | null
user?: string | null
working_directory?: string | null
call_id: string
status: "in_progress" | "completed" | "incomplete"
One of the following:
"in_progress"
"completed"
"incomplete"
type: "local_shell_call"
LocalShellCallOutput { id, output, type, status }

The output of a local shell tool call.

id: string
output: string
type: "local_shell_call_output"
status?: "in_progress" | "completed" | "incomplete" | null
One of the following:
"in_progress"
"completed"
"incomplete"
ShellCall { action, call_id, type, 2 more }

A tool representing a request to execute one or more shell commands.

action: Action { commands, max_output_length, timeout_ms }

The shell commands and limits that describe how to run the tool call.

commands: Array<string>
max_output_length?: number | null
timeout_ms?: number | null
call_id: string
type: "shell_call"
id?: string | null
status?: "in_progress" | "completed" | "incomplete" | null
One of the following:
"in_progress"
"completed"
"incomplete"
ShellCallOutput { call_id, output, type, 2 more }

The streamed output items emitted by a shell tool call.

call_id: string
output: Array<Output>
outcome: OutcomeTimeout { type } | OutcomeExit { exit_code, type }

Indicates that the shell call exceeded its configured time limit.

One of the following:
OutcomeTimeout { type }

Indicates that the shell call exceeded its configured time limit.

type: "timeout"
OutcomeExit { exit_code, type }

Indicates that the shell commands finished and returned an exit code.

exit_code: number
type: "exit"
stderr: string
stdout: string
type: "shell_call_output"
id?: string | null
max_output_length?: number | null
ApplyPatchCall { call_id, operation, status, 2 more }

A tool call representing a request to create, delete, or update files using diff patches.

call_id: string
operation: ApplyPatchCallOperationCreateFile { diff, path, type } | ApplyPatchCallOperationDeleteFile { path, type } | ApplyPatchCallOperationUpdateFile { diff, path, type }

Instruction for creating a new file via the apply_patch tool.

One of the following:
ApplyPatchCallOperationCreateFile { diff, path, type }

Instruction for creating a new file via the apply_patch tool.

diff: string
path: string
type: "create_file"
ApplyPatchCallOperationDeleteFile { path, type }

Instruction for deleting an existing file via the apply_patch tool.

path: string
type: "delete_file"
ApplyPatchCallOperationUpdateFile { diff, path, type }

Instruction for updating an existing file via the apply_patch tool.

diff: string
path: string
type: "update_file"
status: "in_progress" | "completed"
One of the following:
"in_progress"
"completed"
type: "apply_patch_call"
id?: string | null
ApplyPatchCallOutput { call_id, status, type, 2 more }

The streamed output emitted by an apply patch tool call.

call_id: string
status: "completed" | "failed"
One of the following:
"completed"
"failed"
type: "apply_patch_call_output"
id?: string | null
output?: string | null
McpListTools { id, server_label, tools, 2 more }

A list of tools available on an MCP server.

id: string
server_label: string
tools: Array<Tool>
input_schema: unknown
name: string
annotations?: unknown
description?: string | null
type: "mcp_list_tools"
error?: string | null
McpApprovalRequest { id, arguments, name, 2 more }

A request for human approval of a tool invocation.

id: string
arguments: string
name: string
server_label: string
type: "mcp_approval_request"
McpApprovalResponse { approval_request_id, approve, type, 2 more }

A response to an MCP approval request.

approval_request_id: string
approve: boolean
type: "mcp_approval_response"
id?: string | null
reason?: string | null
McpCall { id, arguments, name, 6 more }

An invocation of a tool on an MCP server.

id: string
arguments: string
name: string
server_label: string
type: "mcp_call"
approval_request_id?: string | null
error?: string | null
output?: string | null
status?: "in_progress" | "completed" | "incomplete" | 2 more
One of the following:
"in_progress"
"completed"
"incomplete"
"calling"
"failed"
ResponseCustomToolCallOutputParam { call_id, output, type, id }

The output of a custom tool call from your code, being sent back to the model.

call_id: string
output: string | Array<ResponseInputTextParam { text, type } | ResponseInputImageParam { detail, type, file_id, image_url } | ResponseInputFileParam { type, file_data, file_id, 2 more } >
One of the following:
string
Array<ResponseInputTextParam { text, type } | ResponseInputImageParam { detail, type, file_id, image_url } | ResponseInputFileParam { type, file_data, file_id, 2 more } >
ResponseInputTextParam { text, type }

A text input to the model.

text: string
type: "input_text"
ResponseInputImageParam { detail, type, file_id, image_url }

An image input to the model.

Learn about image inputs.

detail: "low" | "high" | "auto"
One of the following:
"low"
"high"
"auto"
type: "input_image"
file_id?: string | null
image_url?: string | null
ResponseInputFileParam { type, file_data, file_id, 2 more }

A file input to the model.

type: "input_file"
file_data?: string
file_id?: string | null
file_url?: string
filename?: string
type: "custom_tool_call_output"
id?: string
ResponseCustomToolCallParam { call_id, input, name, 2 more }

A call to a custom tool created by the model.

call_id: string
input: string
name: string
type: "custom_tool_call"
id?: string
ItemReference { id, type }

An internal identifier for an item to reference.

id: string
type?: "item_reference" | null
ResponseOutputMessage { id, content, role, 2 more }

An output message from the model.

id: string
content: Array<ResponseOutputText { annotations, text, type, logprobs } | ResponseOutputRefusal { refusal, type } >
One of the following:
ResponseOutputText { annotations, text, type, logprobs }

A text output from the model.

annotations: Array<AnnotationFileCitation { file_id, filename, index, type } | AnnotationURLCitation { end_index, start_index, title, 2 more } | AnnotationContainerFileCitation { container_id, end_index, file_id, 3 more } | AnnotationFilePath { file_id, index, type } >
One of the following:
AnnotationFileCitation { file_id, filename, index, type }

A citation to a file.

file_id: string
filename: string
index: number
type: "file_citation"
AnnotationURLCitation { end_index, start_index, title, 2 more }

A citation for a web resource used to generate a model response.

end_index: number
start_index: number
title: string
type: "url_citation"
url: string
AnnotationContainerFileCitation { container_id, end_index, file_id, 3 more }

A citation for a container file used to generate a model response.

container_id: string
end_index: number
file_id: string
filename: string
start_index: number
type: "container_file_citation"
AnnotationFilePath { file_id, index, type }

A path to a file.

file_id: string
index: number
type: "file_path"
text: string
type: "output_text"
logprobs?: Array<Logprob { token, bytes, logprob, top_logprobs } > | null
token: string
bytes: Array<number>
logprob: number
top_logprobs: Array<TopLogprob>
token: string
bytes: Array<number>
logprob: number
ResponseOutputRefusal { refusal, type }

A refusal from the model.

refusal: string
type: "refusal"
role: "assistant"
status: "in_progress" | "completed" | "incomplete"
One of the following:
"in_progress"
"completed"
"incomplete"
type: "message"
ResponseFileSearchToolCall { id, queries, status, 2 more }

The results of a file search tool call.

See the file search guide for more information.

id: string
queries: Array<string>
status: "in_progress" | "searching" | "completed" | 2 more
One of the following:
"in_progress"
"searching"
"completed"
"incomplete"
"failed"
type: "file_search_call"
results?: Array<Result> | null
attributes?: Record<string, string | number | boolean> | null
One of the following:
string
number
boolean
file_id?: string | null
filename?: string | null
score?: number | null
text?: string | null
ResponseFunctionToolCall { arguments, call_id, name, 3 more }

A tool call to run a function.

See the function calling guide for more information.

arguments: string
call_id: string
name: string
type: "function_call"
id?: string | null
status?: "in_progress" | "completed" | "incomplete" | null
One of the following:
"in_progress"
"completed"
"incomplete"
ResponseFunctionWebSearch { id, action, status, type }

The results of a web search tool call.

See the web search guide for more information.

id: string
action: ActionSearch { query, type, queries, sources } | ActionOpenPage { type, url } | ActionFind { pattern, type, url }

Action type "search" - Performs a web search query.

One of the following:
ActionSearch { query, type, queries, sources }

Action type "search" - Performs a web search query.

query: string
type: "search"
queries?: Array<string> | null
sources?: Array<ActionSearchSource { type, url } > | null
type: "url"
url: string
ActionOpenPage { type, url }

Action type "open_page" - Opens a specific URL from search results.

type: "open_page"
url: string
ActionFind { pattern, type, url }

Action type "find": Searches for a pattern within a loaded page.

pattern: string
type: "find"
url: string
status: "in_progress" | "searching" | "completed" | "failed"
One of the following:
"in_progress"
"searching"
"completed"
"failed"
type: "web_search_call"
ResponseComputerToolCall { id, action, call_id, 3 more }

A tool call to a computer use tool.

See the computer use guide for more information.

id: string
action: ActionClick { button, type, x, y } | ActionDoubleClick { type, x, y } | ActionDrag { path, type } | 11 more

A click action.

One of the following:
ActionClick { button, type, x, y }

A click action.

button: "left" | "right" | "wheel" | 2 more
One of the following:
"left"
"right"
"wheel"
"back"
"forward"
type: "click"
x: number
y: number
ActionDoubleClick { type, x, y }

A double click action.

type: "double_click"
x: number
y: number
ActionDrag { path, type }

A drag action.

path: Array<Path>
x: number
y: number
type: "drag"
ActionKeypress { keys, type }

A collection of keypresses the model would like to perform.

keys: Array<string>
type: "keypress"
ActionMove { type, x, y }

A mouse move action.

type: "move"
x: number
y: number
ActionScreenshot { type }

A screenshot action.

type: "screenshot"
ActionScroll { scroll_x, scroll_y, type, 2 more }

A scroll action.

scroll_x: number
scroll_y: number
type: "scroll"
x: number
y: number
ActionType { text, type }

An action to type in text.

text: string
type: "type"
ActionWait { type }

A wait action.

type: "wait"
ActionPointAndType { text, type, x, y }

Click at a position then type text.

text: string
type: "point_and_type"
x: number
y: number
ActionMouseDown { type, x, y }

Press and hold the left mouse button at a position.

type: "mouse_down"
x: number
y: number
ActionMouseUp { type, x, y }

Release the left mouse button at a position.

type: "mouse_up"
x: number
y: number
ActionKeyDown { keys, type }

Press and hold a key.

keys: Array<string>
type: "key_down"
ActionKeyUp { keys, type }

Release a held key.

keys: Array<string>
type: "key_up"
call_id: string
pending_safety_checks: Array<PendingSafetyCheck>
id: string
code?: string | null
message?: string | null
status: "in_progress" | "completed" | "incomplete"
One of the following:
"in_progress"
"completed"
"incomplete"
type: "computer_call"
ResponseReasoningItem { id, summary, type, 3 more }

A description of the chain of thought used by a reasoning model while generating a response. Be sure to include these items in your input to the Responses API for subsequent turns of a conversation if you are manually managing context.

id: string
summary: Array<Summary { text, type } >
text: string
type: "summary_text"
type: "reasoning"
content?: Array<Content> | null
text: string
type: "reasoning_text"
encrypted_content?: string | null
status?: "in_progress" | "completed" | "incomplete" | null
One of the following:
"in_progress"
"completed"
"incomplete"
ResponseCompactionItem { id, encrypted_content, type, created_by }

A compaction item generated by the v1/responses/compact API.

id: string
encrypted_content: string
type: "compaction"
created_by?: string | null
ImageGenerationCall { id, status, type, result }

An image generation request made by the model.

id: string
status: "in_progress" | "completed" | "generating" | "failed"
One of the following:
"in_progress"
"completed"
"generating"
"failed"
type: "image_generation_call"
result?: string | null
ResponseCodeInterpreterToolCall { id, container_id, status, 3 more }

A tool call to run code.

id: string
container_id: string
status: "in_progress" | "completed" | "incomplete" | 2 more
One of the following:
"in_progress"
"completed"
"incomplete"
"interpreting"
"failed"
type: "code_interpreter_call"
code?: string | null
outputs?: Array<OutputLogs { logs, type } | OutputImage { type, url } > | null
One of the following:
OutputLogs { logs, type }

The logs output from the code interpreter.

logs: string
type: "logs"
OutputImage { type, url }

The image output from the code interpreter.

type: "image"
url: string
LocalShellCall { id, action, call_id, 2 more }

A tool call to run a command on the local shell.

id: string
action: Action { command, env, type, 3 more }

Execute a shell command on the server.

command: Array<string>
env: Record<string, string>
type: "exec"
timeout_ms?: number | null
user?: string | null
working_directory?: string | null
call_id: string
status: "in_progress" | "completed" | "incomplete"
One of the following:
"in_progress"
"completed"
"incomplete"
type: "local_shell_call"
ResponseFunctionShellToolCall { id, action, call_id, 3 more }

A tool call that executes one or more shell commands in a managed environment.

id: string
action: Action { commands, max_output_length, timeout_ms }

The shell commands and limits that describe how to run the tool call.

commands: Array<string>
max_output_length?: number | null
timeout_ms?: number | null
call_id: string
status: "in_progress" | "completed" | "incomplete"
One of the following:
"in_progress"
"completed"
"incomplete"
type: "shell_call"
created_by?: string | null
ResponseFunctionShellToolCallOutput { id, call_id, output, 4 more }

The output of a shell tool call that was emitted.

id: string
call_id: string
output: Array<Output>
outcome: OutputOutcomeTimeout { type } | OutputOutcomeExit { exit_code, type }

Indicates that the shell call exceeded its configured time limit.

One of the following:
OutputOutcomeTimeout { type }

Indicates that the shell call exceeded its configured time limit.

type: "timeout"
OutputOutcomeExit { exit_code, type }

Indicates that the shell commands finished and returned an exit code.

exit_code: number
type: "exit"
stderr: string
stdout: string
created_by?: string | null
status: "in_progress" | "completed" | "incomplete"
One of the following:
"in_progress"
"completed"
"incomplete"
type: "shell_call_output"
created_by?: string | null
max_output_length?: number | null
ResponseApplyPatchToolCall { id, call_id, operation, 3 more }

A tool call that applies file diffs by creating, deleting, or updating files.

id: string
call_id: string
operation: OperationCreateFile { diff, path, type } | OperationDeleteFile { path, type } | OperationUpdateFile { diff, path, type }

Instruction describing how to create a file via the apply_patch tool.

One of the following:
OperationCreateFile { diff, path, type }

Instruction describing how to create a file via the apply_patch tool.

diff: string
path: string
type: "create_file"
OperationDeleteFile { path, type }

Instruction describing how to delete a file via the apply_patch tool.

path: string
type: "delete_file"
OperationUpdateFile { diff, path, type }

Instruction describing how to update a file via the apply_patch tool.

diff: string
path: string
type: "update_file"
status: "in_progress" | "completed"
One of the following:
"in_progress"
"completed"
type: "apply_patch_call"
created_by?: string | null
ResponseApplyPatchToolCallOutput { id, call_id, status, 3 more }

The output emitted by an apply patch tool call.

id: string
call_id: string
status: "completed" | "failed"
One of the following:
"completed"
"failed"
type: "apply_patch_call_output"
created_by?: string | null
output?: string | null
McpCall { id, arguments, name, 6 more }

An invocation of a tool on an MCP server.

id: string
arguments: string
name: string
server_label: string
type: "mcp_call"
approval_request_id?: string | null
error?: string | null
output?: string | null
status?: "in_progress" | "completed" | "incomplete" | 2 more | null
One of the following:
"in_progress"
"completed"
"incomplete"
"calling"
"failed"
McpListTools { id, server_label, tools, 2 more }

A list of tools available on an MCP server.

id: string
server_label: string
tools: Array<Tool>
input_schema: unknown
name: string
annotations?: unknown
description?: string | null
type: "mcp_list_tools"
error?: string | null
McpApprovalRequest { id, arguments, name, 2 more }

A request for human approval of a tool invocation.

id: string
arguments: string
name: string
server_label: string
type: "mcp_approval_request"
ResponseCustomToolCall { call_id, input, name, 2 more }

A call to a custom tool created by the model.

call_id: string
input: string
name: string
type: "custom_tool_call"
id?: string | null
background?: boolean | null
cache_salt?: string | null

If specified, the prefix cache will be salted with the provided string to prevent an attacker to guess prompts in multi-user environments. The salt should be random, protected from access by 3rd parties, and long enough to be unpredictable (e.g., 43 characters base64-encoded, corresponding to 256 bit).

enable_response_messages?: boolean

Dictates whether or not to return messages as part of the response object. Currently only supported fornon-background and gpt-oss only.

include?: Array<"code_interpreter_call.outputs" | "computer_call_output.output.image_url" | "file_search_call.results" | 3 more> | null
One of the following:
"code_interpreter_call.outputs"
"computer_call_output.output.image_url"
"file_search_call.results"
"message.input_image.image_url"
"message.output_text.logprobs"
"reasoning.encrypted_content"
include_stop_str_in_output?: boolean
instructions?: string | null
logit_bias?: Record<string, number> | null
max_output_tokens?: number | null
max_tool_calls?: number | null
metadata?: Record<string, string> | null
mm_processor_kwargs?: Record<string, unknown> | null

Additional kwargs to pass to the HF processor.

model?: string | null
parallel_tool_calls?: boolean | null
previous_input_messages?: Array<Message { author, channel, content, 2 more } | Record<string, unknown>> | null
One of the following:
Message { author, channel, content, 2 more }
author: Author { role, name }
role: "user" | "assistant" | "system" | 2 more

The role of a message author (mirrors chat::Role).

One of the following:
"user"
"assistant"
"system"
"developer"
"tool"
name?: string | null
channel?: string | null
content?: Array<unknown>
content_type?: string | null
recipient?: string | null
Record<string, unknown>
previous_response_id?: string | null
priority?: number

The priority of the request (lower means earlier handling; default: 0). Any priority other than 0 will raise an error if the served model does not use priority scheduling.

prompt?: Prompt | null

Reference to a prompt template and its variables. Learn more.

id: string
variables?: Record<string, string | ResponseInputText { text, type } | ResponseInputImage { detail, type, file_id, image_url } | ResponseInputFile { type, file_data, file_id, 2 more } > | null
One of the following:
string
ResponseInputText { text, type }

A text input to the model.

text: string
type: "input_text"
ResponseInputImage { detail, type, file_id, image_url }

An image input to the model.

Learn about image inputs.

detail: "low" | "high" | "auto"
One of the following:
"low"
"high"
"auto"
type: "input_image"
file_id?: string | null
image_url?: string | null
ResponseInputFile { type, file_data, file_id, 2 more }

A file input to the model.

type: "input_file"
file_data?: string | null
file_id?: string | null
file_url?: string | null
filename?: string | null
version?: string | null
prompt_cache_key?: string | null

A key that was used to read from or write to the prompt cache.Note: This field has not been implemented yet and vLLM will ignore it.

reasoning?: Reasoning | null

gpt-5 and o-series models only

Configuration options for reasoning models.

effort?: "none" | "minimal" | "low" | 3 more | null
One of the following:
"none"
"minimal"
"low"
"medium"
"high"
"xhigh"
generate_summary?: "auto" | "concise" | "detailed" | null
One of the following:
"auto"
"concise"
"detailed"
summary?: "auto" | "concise" | "detailed" | null
One of the following:
"auto"
"concise"
"detailed"
request_id?: string

The request_id related to this request. If the caller does not set it, a random_uuid will be generated. This id is used through out the inference process and return in response.

service_tier?: "auto" | "default" | "flex" | 2 more
One of the following:
"auto"
"default"
"flex"
"scale"
"priority"
skip_special_tokens?: boolean
store?: boolean | null
stream?: boolean | null
temperature?: number | null
text?: Text | null

Configuration options for a text response from the model.

Can be plain text or structured JSON data. Learn more:

format?: ResponseFormatText { type } | ResponseFormatTextJsonSchemaConfig { name, schema, type, 2 more } | ResponseFormatJsonObject { type } | null

Default response format. Used to generate text responses.

One of the following:
ResponseFormatText { type }

Default response format. Used to generate text responses.

type: "text"
ResponseFormatTextJsonSchemaConfig { name, schema, type, 2 more }

JSON Schema response format.

Used to generate structured JSON responses. Learn more about Structured Outputs.

name: string
schema: Record<string, unknown>
type: "json_schema"
description?: string | null
strict?: boolean | null
ResponseFormatJsonObject { type }

JSON object response format.

An older method of generating JSON responses. Using json_schema is recommended for models that support it. Note that the model will not generate JSON without a system or user message instructing it to do so.

type: "json_object"
verbosity?: "low" | "medium" | "high" | null
One of the following:
"low"
"medium"
"high"
tool_choice?: "none" | "auto" | "required" | ToolChoiceAllowed { mode, tools, type } | ToolChoiceTypes { type } | 2 more

Constrains the tools available to the model to a pre-defined set.

One of the following:
"none" | "auto" | "required"
"none"
"auto"
"required"
ToolChoiceAllowed { mode, tools, type }

Constrains the tools available to the model to a pre-defined set.

mode: "auto" | "required"
One of the following:
"auto"
"required"
tools: Array<Record<string, unknown>>
type: "allowed_tools"
ToolChoiceTypes { type }

Indicates that the model should use a built-in tool to generate a response. Learn more about built-in tools.

type: "computer_use_preview"
ToolChoiceFunction { name, type }

Use this option to force the model to call a specific function.

name: string
type: "function"
ToolChoiceCustom { name, type }

Use this option to force the model to call a specific custom tool.

name: string
type: "custom"
tools?: Array<FunctionTool { name, type, description, 2 more } | CustomTool { name, type, description, format } | ComputerTool { display_height, display_width, environment, type } >
One of the following:
FunctionTool { name, type, description, 2 more }

Defines a function in your own code the model can choose to call.

Learn more about function calling.

name: string
type: "function"
description?: string | null
parameters?: Record<string, unknown> | null
strict?: boolean | null
CustomTool { name, type, description, format }

A custom tool that processes input using a specified format.

Learn more about custom tools

name: string
type: "custom"
description?: string | null
format?: Text { type } | Grammar { definition, syntax, type } | null

Unconstrained free-form text.

One of the following:
Text { type }

Unconstrained free-form text.

type: "text"
Grammar { definition, syntax, type }

A grammar defined by the user.

definition: string
syntax: "lark" | "regex"
One of the following:
"lark"
"regex"
type: "grammar"
ComputerTool { display_height, display_width, environment, type }

A tool that controls a virtual computer.

Learn more about the computer tool.

display_height: number
display_width: number
environment: "windows" | "mac" | "linux" | 2 more
One of the following:
"windows"
"mac"
"linux"
"ubuntu"
"browser"
type: "computer_use_preview"
top_k?: number | null
top_logprobs?: number | null
top_p?: number | null
truncation?: "auto" | "disabled" | null
One of the following:
"auto"
"disabled"
user?: string | null
ReturnsExpand Collapse
ResponseCreateResponse { id, created_at, model, 6 more }

The response object returned by the Responses API.

id: string
created_at: number
model: string
object: "response"
output: Array<ResponseOutputMessage { id, content, role, 2 more } | ResponseFunctionToolCall { arguments, call_id, name, 3 more } | ResponseComputerToolCall { id, action, call_id, 3 more } | Record<string, unknown>>
One of the following:
ResponseOutputMessage { id, content, role, 2 more }

An output message from the model.

id: string
content: Array<ResponseOutputText { annotations, text, type, logprobs } | ResponseOutputRefusal { refusal, type } >
One of the following:
ResponseOutputText { annotations, text, type, logprobs }

A text output from the model.

annotations: Array<AnnotationFileCitation { file_id, filename, index, type } | AnnotationURLCitation { end_index, start_index, title, 2 more } | AnnotationContainerFileCitation { container_id, end_index, file_id, 3 more } | AnnotationFilePath { file_id, index, type } >
One of the following:
AnnotationFileCitation { file_id, filename, index, type }

A citation to a file.

file_id: string
filename: string
index: number
type: "file_citation"
AnnotationURLCitation { end_index, start_index, title, 2 more }

A citation for a web resource used to generate a model response.

end_index: number
start_index: number
title: string
type: "url_citation"
url: string
AnnotationContainerFileCitation { container_id, end_index, file_id, 3 more }

A citation for a container file used to generate a model response.

container_id: string
end_index: number
file_id: string
filename: string
start_index: number
type: "container_file_citation"
AnnotationFilePath { file_id, index, type }

A path to a file.

file_id: string
index: number
type: "file_path"
text: string
type: "output_text"
logprobs?: Array<Logprob { token, bytes, logprob, top_logprobs } > | null
token: string
bytes: Array<number>
logprob: number
top_logprobs: Array<TopLogprob>
token: string
bytes: Array<number>
logprob: number
ResponseOutputRefusal { refusal, type }

A refusal from the model.

refusal: string
type: "refusal"
role: "assistant"
status: "in_progress" | "completed" | "incomplete"
One of the following:
"in_progress"
"completed"
"incomplete"
type: "message"
ResponseFunctionToolCall { arguments, call_id, name, 3 more }

A tool call to run a function.

See the function calling guide for more information.

arguments: string
call_id: string
name: string
type: "function_call"
id?: string | null
status?: "in_progress" | "completed" | "incomplete" | null
One of the following:
"in_progress"
"completed"
"incomplete"
ResponseComputerToolCall { id, action, call_id, 3 more }

A tool call to a computer use tool.

See the computer use guide for more information.

id: string
action: ActionClick { button, type, x, y } | ActionDoubleClick { type, x, y } | ActionDrag { path, type } | 11 more

A click action.

One of the following:
ActionClick { button, type, x, y }

A click action.

button: "left" | "right" | "wheel" | 2 more
One of the following:
"left"
"right"
"wheel"
"back"
"forward"
type: "click"
x: number
y: number
ActionDoubleClick { type, x, y }

A double click action.

type: "double_click"
x: number
y: number
ActionDrag { path, type }

A drag action.

path: Array<Path>
x: number
y: number
type: "drag"
ActionKeypress { keys, type }

A collection of keypresses the model would like to perform.

keys: Array<string>
type: "keypress"
ActionMove { type, x, y }

A mouse move action.

type: "move"
x: number
y: number
ActionScreenshot { type }

A screenshot action.

type: "screenshot"
ActionScroll { scroll_x, scroll_y, type, 2 more }

A scroll action.

scroll_x: number
scroll_y: number
type: "scroll"
x: number
y: number
ActionType { text, type }

An action to type in text.

text: string
type: "type"
ActionWait { type }

A wait action.

type: "wait"
ActionPointAndType { text, type, x, y }

Click at a position then type text.

text: string
type: "point_and_type"
x: number
y: number
ActionMouseDown { type, x, y }

Press and hold the left mouse button at a position.

type: "mouse_down"
x: number
y: number
ActionMouseUp { type, x, y }

Release the left mouse button at a position.

type: "mouse_up"
x: number
y: number
ActionKeyDown { keys, type }

Press and hold a key.

keys: Array<string>
type: "key_down"
ActionKeyUp { keys, type }

Release a held key.

keys: Array<string>
type: "key_up"
call_id: string
pending_safety_checks: Array<PendingSafetyCheck>
id: string
code?: string | null
message?: string | null
status: "in_progress" | "completed" | "incomplete"
One of the following:
"in_progress"
"completed"
"incomplete"
type: "computer_call"
Record<string, unknown>
status: "completed" | "failed" | "in_progress" | 2 more
One of the following:
"completed"
"failed"
"in_progress"
"incomplete"
"cancelled"
error?: Record<string, unknown> | null
tools?: Array<Record<string, unknown>>
usage?: Usage | null
input_tokens?: number
output_tokens?: number
total_tokens?: number

Create Responses

import Lightcone from '@tzafon/lightcone';

const client = new Lightcone({
  apiKey: process.env['TZAFON_API_KEY'], // This is the default and can be omitted
});

const response = await client.responses.create({ input: 'string' });

console.log(response.id);
{
  "id": "id",
  "created_at": 0,
  "model": "model",
  "object": "response",
  "output": [
    {
      "id": "id",
      "content": [
        {
          "annotations": [
            {
              "file_id": "file_id",
              "filename": "filename",
              "index": 0,
              "type": "file_citation"
            }
          ],
          "text": "text",
          "type": "output_text",
          "logprobs": [
            {
              "token": "token",
              "bytes": [
                0
              ],
              "logprob": 0,
              "top_logprobs": [
                {
                  "token": "token",
                  "bytes": [
                    0
                  ],
                  "logprob": 0
                }
              ]
            }
          ]
        }
      ],
      "role": "assistant",
      "status": "in_progress",
      "type": "message"
    }
  ],
  "status": "completed",
  "error": {
    "foo": "bar"
  },
  "tools": [
    {
      "foo": "bar"
    }
  ],
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "total_tokens": 0
  }
}
Returns Examples
{
  "id": "id",
  "created_at": 0,
  "model": "model",
  "object": "response",
  "output": [
    {
      "id": "id",
      "content": [
        {
          "annotations": [
            {
              "file_id": "file_id",
              "filename": "filename",
              "index": 0,
              "type": "file_citation"
            }
          ],
          "text": "text",
          "type": "output_text",
          "logprobs": [
            {
              "token": "token",
              "bytes": [
                0
              ],
              "logprob": 0,
              "top_logprobs": [
                {
                  "token": "token",
                  "bytes": [
                    0
                  ],
                  "logprob": 0
                }
              ]
            }
          ]
        }
      ],
      "role": "assistant",
      "status": "in_progress",
      "type": "message"
    }
  ],
  "status": "completed",
  "error": {
    "foo": "bar"
  },
  "tools": [
    {
      "foo": "bar"
    }
  ],
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "total_tokens": 0
  }
}