Create a response

Creates an OpenAI Responses API task. Accepted background requests return 202; foreground requests return 200 after completion. Foreground stream=true requests return OpenAI Responses Server-Sent Events.

POST /responses

cURL

basic

curl --request POST \
  --url https://api.sailresearch.com/v1/responses \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "zai-org/GLM-5.3",
  "input": "Explain the key ideas behind transformer architectures."
}
'

200

{
  "id": "<string>",
  "object": "response",
  "created_at": 123,
  "status": "queued",
  "model": "<string>",
  "usage": {
    "input_tokens": 123,
    "input_tokens_details": {
      "cached_tokens": 123,
      "reasoning_tokens": 123
    },
    "output_tokens": 123,
    "output_tokens_details": {
      "cached_tokens": 123,
      "reasoning_tokens": 123
    },
    "total_tokens": 123,
    "prompt_tokens": 123,
    "completion_tokens": 123
  },
  "metadata": {
    "supercached_input_tokens": "<string>",
    "supercache_write_input_tokens": "<string>"
  },
  "input": "<string>",
  "output": "<string>",
  "error": {},
  "incomplete_details": {},
  "max_output_tokens": 123,
  "reasoning": {},
  "text": {
    "format": {
      "type": "text"
    }
  },
  "store": true,
  "temperature": 123,
  "top_p": 123,
  "parallel_tool_calls": true,
  "tool_choice": "<string>",
  "tools": [
    {}
  ],
  "truncation": "<string>",
  "user": "<string>"
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key · string

Identifies one submission within your organization and API key. Reuse the same value and request body when retrying; use a new value for new work. See Idempotency.

Maximum string length: 255

X-Sail-Completion-Window · enum<string>

Completion window for this request, for clients that cannot set metadata.completion_window in the body. A window in the body takes precedence. See Completion windows.

Available options: asap, balanced, flex

Body

application/json

model · string · required

input · string object[] object · required

Text input, plus image input (input_image) on multimodal models and inline PDF input (input_file) on every model. Audio, files referenced by file_id or file_url, and item references are not currently supported.

Minimum string length: 1

raw_prompt_tokens · integer[]

Sail extension: pre-tokenized prompt as an array of token ids, forwarded to the model verbatim (no chat templating or tokenization). When set, input is still required but ignored; pass a placeholder string.

Required array length: 1 - 2000000 elements

Required range: 0 <= x <= 2147483647

max_output_tokens · integer | null

Required range: x >= 1

temperature · number | null

Required range: 0 <= x <= 2

top_p · number | null

Required range: 0 <= x <= 1

text · object

Show child attributes

reasoning · object

Show child attributes

instructions · string

Prepended to the input as a system message.

parallel_tool_calls · boolean

Accepted for OpenAI compatibility. Models decide their own tool-call cadence, so this field has no effect.

include · string[]

Additional data to include. reasoning.encrypted_content is accepted for OpenAI-client compatibility, but reasoning items are returned without encrypted content.

background · boolean

When true, submits a background request using a supported balanced or flex window; defaults to false. See Background mode for restrictions and Default behavior for window selection.

prompt_cache_key · string

Optional routing hint for prompt-prefix cache locality. Requests with the same key are preferentially routed to maximize cache hit rates.

store · boolean

Accepted for OpenAI compatibility. false does not change Sail's normal temporary request/response storage for processing, retries, polling, and idempotency; Customer Data remains governed by Sail's DPA retention and deletion terms.

truncation · enum<string>

Available options: disabled

stream · boolean

When true on a foreground request, returns OpenAI Responses Server-Sent Events. background=true requests cannot be streamed.

user · string

Maximum string length: 256

metadata · object

Optional string metadata. The keys supercached_input_tokens and supercache_write_input_tokens are reserved for response output. A request that supplies either key returns HTTP 400.

Show child attributes

Response

200

application/json

Response completed and returned synchronously. When stream=true, returns Server-Sent Events.

id · string · required

object · enum<string> · required

Available options: response

created_at · integer · required

status · enum<string> · required

Available options: queued, in_progress, failed, completed, incomplete, cancelled

model · string · required

usage · object | null · required

Show child attributes

metadata · object · required

Response metadata. A completed response includes supercached_input_tokens and supercache_write_input_tokens as decimal strings when Supercache accounting data is available. Both fields are included when their value is zero.

Show child attributes

input · string object[] object

Text input, plus image input (input_image) on multimodal models and inline PDF input (input_file) on every model. Audio, files referenced by file_id or file_url, and item references are not currently supported.

Minimum string length: 1

output · string object[] object

error · object | null

incomplete_details · object | null

max_output_tokens · integer | null

reasoning · object

text · object

Show child attributes

store · boolean

temperature · number

top_p · number

parallel_tool_calls · boolean

tool_choice · string object

tools · object[]

truncation · string object

user · string | null