Create a response

Creates an OpenAI Responses API task. Returns 202 when background=true, otherwise returns 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.2-FP8",
  "input": "Explain the key ideas behind transformer architectures."
}
'

200

{
  "id": "<string>",
  "object": "response",
  "created_at": 123,
  "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": {},
  "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

Makes the request retry-safe. Sail stores a reservation keyed by (organization, API key, Idempotency-Key); retrying with the same value returns the previously stored response instead of re-running inference. Keys are capped at 255 characters. See Idempotent Requests for full semantics.

Maximum string length: 255

Body

application/json

model · string · required

input · string object[] object · required

Text input, plus image input (input_image) on multimodal models. Audio, files, 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

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. completion_window controls scheduling; completion_webhook/webhook_token configure completion webhooks.

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: pending, running, failed, completed, cancelled

model · string · required

usage · object · required

Show child attributes

metadata · object · required

input · string object[] object

Text input, plus image input (input_image) on multimodal models. Audio, files, 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