Responses

Create responses with the OpenAI Responses API format. Supports multimodal input, tool calling, streaming, and context compaction.

POST /v1/responses

The Responses API targets multimodal workflows, tool calling, and context continuation. Compared with Chat Completions, its input/output and tool-call structures are better suited to complex task orchestration.

The default model is .

Available models

Model	Description
	Flagship latest in the 5.6 series
	High-spec 5.5 series
	General-purpose 5.4 series
	Lightweight 5.4
	Code-focused 5.3
	Smaller 5-series variant
	General multimodal model
	General text / tool-calling model

Headers

Name	Type	Required	Description
	string	Yes	Request authentication. Use a Bearer token, for example:
	string	Yes	Request content type; must be

Request body

Name	Type	Required	Description
	string	Yes	Model name; default example . See Available models above
	string | array	No	Model input: a plain text string, or an array of text / image / file input items
	string	No	System (developer) message; not automatically inherited when used with
	object	No	Reasoning configuration for o-series and gpt-5 series
	object	No	Text output configuration (, )
	array	No	List of callable tools (built-in / MCP / function)
	string | object	No	Tool selection: / / , or a specific tool object
	boolean	No	Whether to allow parallel tool calls, default
	integer	No	Upper bound on tokens generated in one response (visible output and reasoning tokens), minimum
	integer	No	Maximum total built-in tool calls in one response
	number	No	Sampling temperature, range –, default
	number	No	Nucleus sampling, range –, default
	integer	No	–; number of candidate token log probabilities to return
	boolean	No	Whether to use SSE streaming, default
	object	No	Streaming options; only effective when
	boolean	No	Whether to run asynchronously in the background, default
	boolean	No	Whether to store the response for later retrieval, default
	object	No	Up to 16 key-value pairs of metadata
	array	No	Additional output data to include (e.g. retrieval results, logprobs)
	string	No	Deprecated. Truncation strategy: / (default)
	string	No	Previous response ID for multi-turn continuation; cannot be used with
	string | object	No	Conversation ID or ; cannot be used with
	object	No	Reusable prompt template ( / / )
	string	No	Prompt cache bucket key
	object	No	Cache options (, ); supported on gpt-5.6 and later
	string	No	Stable end-user identifier, max 64 characters
	string	No	Processing tier: / / / / /
	string	No	Deprecated; use /
	object	No	Content moderation configuration
	array	No	Long-context management configuration

reasoning

Name	Type	Required	Description
	string	No	/ / / / / / , default
	string	No	/ /

text

Name	Type	Required	Description
	object	No	Default ; may use /
	string	No	/ / , default

stream_options

Name	Type	Required	Description
	boolean	No	Stream obfuscation fields; trusted links may disable this to save bandwidth. Usage is returned by default on

prompt

Name	Type	Required	Description
	string	Yes	Prompt template ID
	string	No	Template version
	object	No	Template variables

Request example

Text input

curl -X POST https://octopusx.ai/v1/responses \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra",
    "instructions": "You are a concise technical assistant.",
    "input": "In three sentences, explain when the Responses API is a good fit."
  }'

Multimodal input

curl -X POST https://octopusx.ai/v1/responses \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra",
    "input": [
      {
        "type": "input_text",
        "text": "Describe the main content of this image."
      },
      {
        "type": "input_image",
        "image_url": "https://example.com/image.png"
      }
    ]
  }'

Tool calling

curl -X POST https://octopusx.ai/v1/responses \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra",
    "input": "Look up today'\''s weather in Hangzhou.",
    "tools": [
      {
        "type": "function",
        "name": "get_weather",
        "description": "Get weather by city",
        "parameters": {
          "type": "object",
          "properties": {
            "city": { "type": "string" }
          },
          "required": ["city"]
        }
      }
    ],
    "tool_choice": "auto"
  }'

Streaming

curl -X POST https://octopusx.ai/v1/responses \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra",
    "input": "Explain the advantages of the Responses API step by step.",
    "stream": true
  }'

Response example

{
  "id": "resp_abc123",
  "object": "response",
  "created_at": 1735689600,
  "status": "completed",
  "model": "gpt-5.6-terra",
  "output": [
    {
      "type": "message",
      "id": "msg_abc123",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "The Responses API is a good fit for multimodal input, tool calling, and tasks that need context continuation. It splits output into structured items that are easy for programs to read. Through a unified gateway you can reuse the same auth, billing, and channel routing.",
          "annotations": []
        }
      ]
    }
  ],
  "usage": {
    "prompt_tokens": 26,
    "completion_tokens": 62,
    "total_tokens": 88
  }
}

Response fields

Name	Type	Description
	string	Response ID
	string	Always
	integer	Creation timestamp (Unix seconds)
	string	Status, e.g.
	string	Model actually used
	array	List of structured output items
	string	Output item type, e.g.
	array	Content parts (e.g. )
	object	Token usage
	integer	Input tokens
	integer	Output tokens
	integer	Total tokens

Context compaction

POST /v1/responses/compact compresses a long context into a summary that can continue in later turns. The request shape is close to /v1/responses; common fields are model, input, instructions, and previous_response_id.

curl -X POST https://octopusx.ai/v1/responses/compact \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra",
    "instructions": "Compress into context that later turns can continue from. Keep decisions, constraints, and open todos.",
    "input": [
      { "role": "user", "content": "First-round requirements..." },
      { "role": "assistant", "content": "First-round proposal..." }
    ]
  }'

Notes

TIP

Whether optional parameters take effect depends on the upstream model’s capabilities. In the debugger, non-required fields are off by default and are written into the request body only after you enable them.

WARNING

previous_response_id and conversation cannot be used together. Streaming usage is usually returned via the response.completed event.

Related endpoints

• Chat Completions
• Text APIs overview
• Error codes