> ## Documentation Index
> Fetch the complete documentation index at: https://doc.octopusx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI Multimodal Responses API

> Create responses using the OpenAI Responses API format, with support for multimodal input, tool calling, streaming output, and context compression.

# 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

<ParamField body="model" type="string" required>
  Model name.
</ParamField>

<ParamField body="input" type="string | array<object>">
  User input. Can be a string or a structured message array.
</ParamField>

<ParamField body="instructions" type="string">
  Developer or system-level instructions.
</ParamField>

<ParamField body="previous_response_id" type="string">
  The ID of the previous response. Can be used for context continuation when supported by the upstream.
</ParamField>

<ParamField body="tools" type="array<object>">
  Tool list. Supports function tools, and can also forward upstream-compatible built-in tools.
</ParamField>

<ParamField body="tool_choice" type="string | object">
  Tool selection strategy.
</ParamField>

<ParamField body="max_output_tokens" type="integer">
  Maximum number of output tokens. Explicitly passing `0` will be preserved and forwarded to supported upstreams.
</ParamField>

<ParamField body="reasoning" type="object">
  Reasoning configuration, for example `{ "effort": "medium", "summary": "auto" }`.
</ParamField>

<ParamField body="text" type="object">
  Text output configuration, commonly used for JSON Schema structured output.
</ParamField>

<ParamField body="stream" type="boolean">
  Whether to enable SSE streaming output.
</ParamField>

<ParamField body="stream_options.include_usage" type="boolean">
  Whether to include token usage in streaming responses.
</ParamField>

<ParamField body="store" type="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.
</ParamField>

<ParamField body="metadata" type="object">
  Additional business-side metadata.
</ParamField>

<ParamField body="include" type="array<string>">
  Additional fields to include in the request response; the specific values depend on the upstream implementation.
</ParamField>

## Request Example

<RequestExample>
  ```bash theme={null}
  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."
    }'
  ```
</RequestExample>

### Multimodal Input

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

<ResponseExample>
  ```json 200 - non-streaming theme={null}
  {
    "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
    }
  }
  ```

  ```text 200 - streaming theme={null}
  data: {"type":"response.created","response":{"id":"resp_abc123","object":"response","status":"in_progress","model":"gpt-4o"}}

  data: {"type":"response.output_text.delta","delta":"Responses"}

  data: {"type":"response.output_text.delta","delta":" API"}

  data: {"type":"response.completed","response":{"id":"resp_abc123","status":"completed","usage":{"prompt_tokens":26,"completion_tokens":62,"total_tokens":88}}}

  data: [DONE]
  ```

  ```json 400 theme={null}
  {
    "error": {
      "message": "model is required",
      "type": "invalid_request_error",
      "param": "",
      "code": "invalid_request"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "message": "Invalid API key provided",
      "type": "invalid_request_error",
      "param": "",
      "code": "invalid_api_key"
    }
  }
  ```

  ```json 402 theme={null}
  {
    "error": {
      "message": "User quota is insufficient",
      "type": "new_api_error",
      "param": "",
      "code": "insufficient_user_quota"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "message": "The current request rate is too high, please try again later",
      "type": "new_api_error",
      "param": "",
      "code": "too_many_requests"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "message": "bad response body",
      "type": "new_api_error",
      "param": "",
      "code": "bad_response_body"
    }
  }
  ```
</ResponseExample>

## Context Compression

```http theme={null}
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`.

```bash theme={null}
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..." }
    ]
  }'
```

## Related Interfaces

* [Chat Completions API (default non-streaming)](./chat-completions-non-stream)
* [Chat Completions API (default streaming)](./chat-completions-stream)