POST
https://octopusx.ai
/
v1
/
responses
curl -X POST https://octopusx.ai/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "instructions": "You are a concise technical assistant.",
    "input": "Explain in three sentences what scenarios the Responses API is suitable for."
  }'

{
  "id": "resp_abc123",
  "object": "response",
  "created_at": 1735689600,
  "status": "completed",
  "model": "gpt-4o",
  "output": [
    {
      "type": "message",
      "id": "msg_abc123",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "The Responses API is suitable for multimodal input, tool calling, and tasks that require context continuation. It breaks output into structured items, making it easier for programs to read. Through a unified gateway, you can reuse the same authentication, billing, and channel distribution capabilities.",
          "annotations": []
        }
      ]
    }
  ],
  "usage": {
    "prompt_tokens": 26,
    "completion_tokens": 62,
    "total_tokens": 88
  }
}

​
OpenAI Multimodal Responses API

The Responses API is a unified response interface for multimodal workflows, tool calling, and context continuation. Compared with Chat Completions, its input, output, and tool-calling structure is better suited for complex task orchestration.

​
Request Body

​
model
string
required
Model name.
​
input
string | array<object>
User input. Can be a string or a structured message array.
​
instructions
string
Developer or system-level instructions.
​
previous_response_id
string
The ID of the previous response. Can be used for context continuation when supported by the upstream.
​
tools
array<object>
Tool list. Supports function tools, and can also forward upstream-compatible built-in tools.
​
tool_choice
string | object
Tool selection strategy.
​
max_output_tokens
integer
Maximum number of output tokens. Explicitly passing 0 will be preserved and forwarded to supported upstreams.
​
reasoning
object
Reasoning configuration, for example { "effort": "medium", "summary": "auto" }.
​
text
object
Text output configuration, commonly used for JSON Schema structured output.
​
stream
boolean
Whether to enable SSE streaming output.
​
stream_options.include_usage
boolean
Whether to include token usage in streaming responses.
​
store
boolean
Controls whether the upstream stores the request and response. This field is allowed to be forwarded by default, and can be disabled by channel settings.
​
metadata
object
Additional business-side metadata.
​
include
array<string>
Additional fields to include in the request response; the specific values depend on the upstream implementation.

​
Request Example

curl -X POST https://octopusx.ai/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "instructions": "You are a concise technical assistant.",
    "input": "Explain in three sentences what scenarios the Responses API is suitable for."
  }'

​
Multimodal Input

curl -X POST https://octopusx.ai/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "input": [
      {
        "role": "user",
        "content": [
          { "type": "input_text", "text": "Extract the abnormal metrics from this screenshot." },
          { "type": "input_image", "image_url": "https://.../dashboard.png", "detail": "high" }
        ]
      }
    ]
  }'

​
Tool Calling

curl -X POST https://octopusx.ai/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "input": "Is Beijing suitable for outdoor running today?",
    "tools": [
      {
        "type": "function",
        "name": "get_weather",
        "description": "Get city weather",
        "parameters": {
          "type": "object",
          "properties": {
            "city": { "type": "string" }
          },
          "required": ["city"]
        }
      }
    ],
    "tool_choice": "auto"
  }'

​
Streaming Output

curl -N -X POST https://octopusx.ai/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "input": "Write a product launch announcement within 5 lines.",
    "stream": true,
    "stream_options": {
      "include_usage": true
    }
  }'

​
Response Example

{
  "id": "resp_abc123",
  "object": "response",
  "created_at": 1735689600,
  "status": "completed",
  "model": "gpt-4o",
  "output": [
    {
      "type": "message",
      "id": "msg_abc123",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "The Responses API is suitable for multimodal input, tool calling, and tasks that require context continuation. It breaks output into structured items, making it easier for programs to read. Through a unified gateway, you can reuse the same authentication, billing, and channel distribution capabilities.",
          "annotations": []
        }
      ]
    }
  ],
  "usage": {
    "prompt_tokens": 26,
    "completion_tokens": 62,
    "total_tokens": 88
  }
}

​
Context Compression

POST /v1/responses/compact
Used to compress a long context into a summary suitable for continuing the conversation later. The request structure is similar to /v1/responses, and the commonly used fields are model, input, instructions, and previous_response_id. 
curl -X POST https://octopusx.ai/v1/responses/compact \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "instructions": "Compress this into context that can continue to be used in subsequent conversations, preserving decisions, constraints, and action items.",
    "input": [
      { "role": "user", "content": "First-round requirements..." },
      { "role": "assistant", "content": "First-round proposal..." }
    ]
  }'