API ResourcesResponses

Responses API

The Responses API is a dedicated interface designed for the latest generation of thinking models. Unlike the Chat Completions API, it does not maintain conversation history or use message role structures. The API accepts an input parameter and returns model-generated completion text, supporting deep reasoning, code completion, file analysis, and more.

With an OriginRouter One subscription, choose the corresponding Coding API endpoint and make sure the model ID comes from the Supported Models list; with the pay-as-you-go API plan, choose the corresponding Beta API endpoint and make sure the model ID comes from the Model List; a plan and endpoint mismatch may make models unavailable or result in unexpected billing.

POST/beta/v1/responses

Create a response

Creates a model response. Provide text or image inputs to generate text or JSON outputs. Have the model call your own custom code or use built-in tools like web search or file search to use your own data as input for the model's response.

Request Headers

Name
Content-Type
Type
string
Required
Required
Description
Must be application/json.
Name
Authorization
Type
string
Optional
Optional
Description
Bearer token for API authentication. Learn more about authentication.
Name
x-api-key
Type
string
Optional
Optional
Description
API key for authentication. Note: Do not use both Authorization and x-api-key together.

Request Body Parameters

Name
model
Type
string
Required
Required
Description
Model ID used to generate the response. Available models include gpt-5.4, gpt-5.4-mini, gpt-5, o3, o3-mini, etc.
Name
input
Type
string | array
Required
Required
Description
Text, image, or file inputs to the model, used to generate a response. Supports 29 different object types for advanced use cases.
Name
background
Type
boolean
Optional
Optional
Description
Whether to run the model response in the background. If set to true, the server will immediately return a 202 Accept response. To retrieve the final result, use Retrieve Response.When stream and background are both set to true, the request will be processed in streaming mode and background will be ignored.
Name
conversation
Type
string | object
Optional
Optional
Description
The conversation that this response belongs to. Items from this conversation are prepended to input_items for this response request. Input items and output items from this response are automatically added to this conversation after this response completes.
Note: Cannot be used in conjunction with previous_response_id.
Name
instructions
Type
string | array
Optional
Optional
Description
A system (or developer) message inserted into the model's context.
Note: When using along with previous_response_id, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses.
Name
previous_response_id
Type
string
Optional
Optional
Description
The unique ID of the previous response to the model. Use it to create multi-turn conversations without having to pass along the entire previous conversation.
Note: Cannot be used in conjunction with conversation.
Name
prompt
Type
object
Optional
Optional
Description
Reference to a prompt template and its variables.
Name
prompt_cache_key
Type
string
Optional
Optional
Description
Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the user field.
Name
prompt_cache_retention
Type
string
Optional
Optional
Description
The retention policy for the prompt cache. Set to 24h to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours.
- in_memory (default)
- 24h
Name
temperature
Type
number
Optional
Optional
Description
What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.We generally recommend altering this or top_p but not both.
- Minimum: 0
- Maximum: 2
Name
max_output_tokens
Type
integer
Optional
Optional
Description
An upper bound for the number of tokens that can be generated for a response, including visible output tokens and reasoning tokens.
- Minimum: 16
Name
max_tool_calls
Type
integer
Optional
Optional
Description
The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored.
Name
top_p
Type
number
Optional
Optional
Description
An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered.We generally recommend altering this or temperature but not both.
- Minimum: 0
- Maximum: 1
Name
top_logprobs
Type
integer
Optional
Optional
Description
An integer between 0 and 20 specifying the number of most likely tokens to return at each token position, each with an associated log probability.
- Minimum: 0
- Maximum: 20
Name
tools
Type
array
Optional
Optional
Description
An array of tools the model may call while generating a response. You can specify which tool to use by setting the tool_choice parameter.
Supported tool categories:
- Built-in tools: Tools provided by OpenAI like web search, file search, code interpreter, computer use, image generation, etc.
- MCP Tools: Integrations with third-party systems via Model Context Protocol servers
- Function calls: Functions defined by you, enabling the model to call your own code
Name
tool_choice
Type
string | object
Optional
Optional
Description
How the model should select which tool (or tools) to use when generating a response.
Name
parallel_tool_calls
Type
boolean
Optional
Optional
Description
Whether to allow the model to run tool calls in parallel. Default true.
Name
stream
Type
boolean
Optional
Optional
Description
If set to true, the model response data will be streamed to the client as it is generated using server-sent events.
Name
stream_options
Type
object
Optional
Optional
Description
Options for streaming responses. Only set this when you set stream: true.
Name
text
Type
object
Optional
Optional
Description
Configuration options for a text response from the model. Can be plain text or structured JSON data.
Name
reasoning
Type
object
Optional
Optional
Description
gpt-5 and o-series models only
Configuration options for reasoning models.
Name
store
Type
boolean
Optional
Optional
Description
Whether to store the generated model response for later retrieval via API. Default false.
Name
truncation
Type
string
Optional
Optional
Description
The truncation strategy to use for the model response.
- auto: If the input exceeds the model's context window size, the model will truncate the response to fit the context window by dropping items from the beginning of the conversation.
- disabled (default): If the input size exceeds the context window, the request will fail with a 400 error.
Name
context_management
Type
array
Optional
Optional
Description
Context management configuration for this request.
Name
include
Type
array
Optional
Optional
Description
Specify additional output data to include in the model response.
Supported values:
- file_search_call.results: Include search results of the file search tool call
- web_search_call.results: Include results of the web search tool call
- web_search_call.action.sources: Include the sources of the web search tool call
- code_interpreter_call.outputs: Include outputs of Python code execution
- computer_call_output.output.image_url: Include image URLs from computer call output
- message.input_image.image_url: Include image URLs from input messages
- message.output_text.logprobs: Include logprobs with assistant messages
- reasoning.encrypted_content: Include encrypted version of reasoning tokens for multi-turn conversations when using the API statelessly
Name
metadata
Type
map
Optional
Optional
Description
Set of 16 key-value pairs that can be attached to an object for storing additional information.Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.
Name
safety_identifier
Type
string
Optional
Optional
Description
A stable identifier used to help detect users of your application that may be violating usage policies. Should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address.
- MaxLength: 64
Name
service_tier
Type
string
Optional
Optional
Description
Specifies the processing type used for serving the request.
- auto: Uses the service tier configured in Project settings (default)
- default: Standard pricing and performance
- flex, priority, scale: Corresponding service tier
When set, the response body will include the actual service_tier value used.
Name
user
Type
string
Optional
Optional
Description
Deprecated: Use prompt_cache_key instead for caching optimizations, and safety_identifier for safety.
A stable identifier for your end-users, used to boost cache hit rates and help detect abuse.
Name
multimodal
Type
object
Optional
Optional
Description
Multimodal adaptation configuration. Used to enable and control automatic conversion of non-text content (such as images, PDFs, videos, audio, etc.). For details, see Multimodal Support.
Name
fallback
Type
string
Optional
Optional
Description
Defines the fallback strategy when a request fails. This parameter only applies to the /beta/v1/responses endpoint. For details, see Model Fallback.
Name
fallback_config
Type
object
Optional
Optional
Description
Detailed configuration for custom fallback behavior. This parameter only applies to the /beta/v1/responses endpoint. For details, see Model Fallback.

Response Body

Name
id
Type
string
Optional
Optional
Description
Unique identifier for this Response.
Name
object
Type
string
Optional
Optional
Description
The object type, always response.
Name
created_at
Type
integer
Optional
Optional
Description
Unix timestamp (in seconds) of when this Response was created.
Name
completed_at
Type
integer
Optional
Optional
Description
Unix timestamp (in seconds) of when this Response was completed. Only present when status is completed.
Name
status
Type
string
Optional
Optional
Description
The status of the response generation. One of completed, failed, in_progress, cancelled, queued, or incomplete.
Name
error
Type
object | null
Optional
Optional
Description
An error object returned when the model fails to generate a Response, or null.
Name
incomplete_details
Type
object | null
Optional
Optional
Description
Details about why the response is incomplete.
Name
model
Type
string
Optional
Optional
Description
Model ID used to generate the response, like gpt-5.4 or o3.
Name
output
Type
array
Optional
Optional
Description
An array of content items generated by the model. Rather than accessing the first item, consider using the output_text property in SDKs.
Name
output_text
Type
string
Optional
Optional
Description
SDK-only convenience property that contains the aggregated text output from all output_text items in the output array. Supported in the Python and JavaScript SDKs.
Name
instructions
Type
string | array | null
Optional
Optional
Description
The instructions (system message) used for this response.
Name
parallel_tool_calls
Type
boolean
Optional
Optional
Description
Whether to allow the model to run tool calls in parallel.
Name
previous_response_id
Type
string | null
Optional
Optional
Description
The unique ID of the previous response, if this is part of a multi-turn conversation.
Name
reasoning
Type
object
Optional
Optional
Description
Configuration options for reasoning models.
Name
temperature
Type
number
Optional
Optional
Description
The sampling temperature used.
Name
text
Type
object
Optional
Optional
Description
The text response configuration used.
Name
tool_choice
Type
string | object
Optional
Optional
Description
The tool choice strategy used.
Name
tools
Type
array
Optional
Optional
Description
The tools that were available to the model.
Name
top_p
Type
number
Optional
Optional
Description
The nucleus sampling value used.
Name
top_logprobs
Type
integer
Optional
Optional
Description
The top logprobs value used.
Name
truncation
Type
string
Optional
Optional
Description
The truncation strategy used.
Name
usage
Type
object
Optional
Optional
Description
Token usage details.
Name
conversation
Type
object | null
Optional
Optional
Description
The conversation that this response belonged to, if specified.
Name
prompt
Type
object | null
Optional
Optional
Description
The prompt template used, if specified.
Name
metadata
Type
map
Optional
Optional
Description
Set of 16 key-value pairs attached to this response.

Request

POST

/beta/v1/responses

curl https://api.easytransnote.com/beta/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -d '{
    "model": "gpt-5.4",
    "input": "Tell me a three sentence bedtime story about a unicorn."
  }'

Response

{
  "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 that reflected the stars...",
          "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
    },
    "output_tokens": 87,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 123
  },
  "user": null,
  "metadata": {}
}

GET/beta/v1/responses/{response_id}

Retrieve a response

Retrieves a model response with the given ID.

Path Parameters

Name
response_id
Type
string
Required
Required
Description
The ID of the response to retrieve.

Query Parameters

Name
include
Type
array
Optional
Optional
Description
Additional fields to include in the response. One of: file_search_call.results, web_search_call.results, web_search_call.action.sources, message.input_image.image_url, computer_call_output.output.image_url, code_interpreter_call.outputs, reasoning.encrypted_content, message.output_text.logprobs.
Name
include_obfuscation
Type
boolean
Optional
Optional
Description
When true, stream obfuscation will be enabled, adding random characters to an obfuscation field on streaming delta events to normalize payload sizes as a mitigation to certain side-channel attacks. Set to false to optimize for bandwidth if you trust the network links between your application and the API.
Name
starting_after
Type
number
Optional
Optional
Description
The sequence number of the event after which to start streaming.
Name
stream
Type
boolean
Optional
Optional
Description
Streaming is not currently supported. This parameter has no effect and the API always returns a complete, non-streaming response.

Response Body

Returns a Response object.

Request

GET

/beta/v1/responses/{response_id}

curl https://api.easytransnote.com/beta/v1/responses/YOUR_RESPONSE_ID \
  -H "Authorization: Bearer $YOUR_API_KEY"

Response

{
  "id": "resp_67cb71b351908190a308f3859487620d06981a8637e6bc44",
  "object": "response",
  "created_at": 1741386163,
  "status": "completed",
  "completed_at": 1741386164,
  "error": null,
  "incomplete_details": null,
  "instructions": null,
  "max_output_tokens": null,
  "model": "gpt-5.4",
  "output": [
    {
      "type": "message",
      "id": "msg_67cb71b3c2b0819084d481baaaf148f206981a8637e6bc44",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Silent circuits hum,  \nThoughts emerge in data streams—  \nDigital dawn breaks.",
          "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": 32,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 18,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 50
  },
  "user": null,
  "metadata": {}
}

POST/beta/v1/responses/{response_id}/cancel

Cancel a response

Cancels a model response with the given ID. Only responses created with the background parameter set to true can be cancelled.

Path Parameters

Name
response_id
Type
string
Required
Required
Description
The ID of the response to cancel.

Response Body

Returns a Response object with status cancelled. The usage field will be null upon successful cancellation.

Request

POST

/beta/v1/responses/{response_id}/cancel

curl -X POST https://api.easytransnote.com/beta/v1/responses/YOUR_RESPONSE_ID/cancel \
  -H "Authorization: Bearer $YOUR_API_KEY"

Response

{
  "id": "resp_67cb71b351908190a308f3859487620d06981a8637e6bc44",
  "object": "response",
  "created_at": 1741386163,
  "status": "cancelled",
  "background": true,
  "completed_at": null,
  "error": null,
  "incomplete_details": null,
  "instructions": null,
  "max_output_tokens": null,
  "model": "gpt-5.4",
  "output": [
    {
      "type": "message",
      "id": "msg_67cb71b3c2b0819084d481baaaf148f206981a8637e6bc44",
      "status": "in_progress",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Silent circuits hum,  \nThoughts emerge in data streams—  \nDigital dawn breaks.",
          "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": null,
  "user": null,
  "metadata": {}
}