OpenAI 多模態回應 | API 文件

# OpenAI Multimodal Responses

OpenAI-compatible Responses API. This endpoint uses OpenAI-style `input`, supports text, public image URLs, PDF file input, tool calls, reasoning options, and streaming parameters.

POST https://api.apihop.ai/openai/responses

OpenAI-compatible Responses API. This endpoint uses OpenAI-style `input`, supports text, public image URLs, PDF file input, tool calls, reasoning options, and streaming parameters.

```text
POST https://api.apihop.ai/openai/responses
```

## Authentication

All requests require Bearer Token authentication.

```http
Authorization: Bearer YOUR_API_KEY
```

## Body

### `model` (string, required, Default: gpt-5.4)

Current active models with Responses support:

- `gpt-5.4`
- `gpt-5.5`
- `gpt-5.6-sol`
- `gpt-5.6-terra`
- `gpt-6-astra`

See the [Model Catalog](https://apihop.ai/en/docs/api-reference/models) for the models visible to the current API Key.

### `input` (string | object[])

Input content. Required unless a non-empty `previous_response_id` is provided. Omitting both fields or using an invalid input type returns `400` before billing.

Supported forms:

- A string, equivalent to one `user` text input.
- An array of input items for conversation history, multimodal input, and tool call results.

Each object in the input array may contain the following fields:

### `type` (string)

Input item type.

Common values:

- `message`: a message input.
- `function_call_output`: the result of a function tool call.

### `role` (string)

Role when `type=message`.

Common values:

- `developer`
- `system`
- `user`
- `assistant`

### `content` (string | object[])

Message content.

Use a content-block array for multimodal requests. Content blocks support:

### `type` (string)

Content block type.

Currently supported:

- `input_text`
- `input_image`
- `input_file`

### `text` (string)

Text content when `type=input_text`.

### `image_url` (string)

Public image URL when `type=input_image`.

Only publicly accessible `http://` or `https://` image URLs are supported. Base64 Data URLs such as `data:image/...;base64,...` are not supported.

### `detail` (string, Default: auto)

Image detail level when `type=input_image`.

Common values:

- `auto`
- `low`
- `high`

### `file_data` (string)

File content Data URL when `type=input_file`. PDFs may use `data:application/pdf;base64,...`.

### `filename` (string)

File name when `type=input_file`.

### `instructions` (string)

System or developer instructions inserted into the model context.

### `max_output_tokens` (integer)

Optional maximum output tokens, as a positive integer. Omit this field to use the upstream default for the selected model. Depending on the model, the budget may include reasoning tokens as well as final text. A small budget can truncate the answer or be exhausted before final text; increasing it may increase cost.

### `stream` (boolean, Default: false)

Whether to stream the response.

- `false`: return one complete response
- `true`: return OpenAI Responses-style SSE events

### `temperature` (number, Default: 1.0)

Sampling temperature, usually from `0` to `2`.

### `top_p` (number, Default: 1.0)

Nucleus sampling parameter, usually from `0` to `1`.

### `text` (object)

Text output configuration.

### `text.format` (object)

Text format configuration, such as `{ "type": "text" }` or a JSON schema.

### `text.verbosity` (string)

Output verbosity, such as `low`, `medium`, or `high`. Support depends on the selected model.

### `tools` (object[])

Tool definitions. Availability depends on the selected model and available features.

### `tool_choice` (string | object)

Tool selection policy.

### `parallel_tool_calls` (boolean)

Whether parallel tool calls are allowed.

### `reasoning` (object)

Reasoning-related options.

### `include` (string[])

Extra fields to include in the response.

### `prompt_cache_key` (string)

Prompt cache key for prompt cache reuse.

### `prompt_cache_retention` (string)

Prompt cache retention policy. Supported values depend on the selected model and available features.

### `safety_identifier` (string)

Stable end-user identifier for safety controls.

### `store` (boolean)

Whether response state may be stored.

## Model Parameter Differences

- Native OpenAI-compatible Responses forwarding preserves `top_p` in the upstream request; validation and sampling behavior depend on the selected model and upstream. The checks on 2026-09-26 accepted `top_p: 0.9` for `gpt-5.5`, `gpt-5.6-sol`, and `gpt-5.6-terra`. Acceptance and forwarding do not prove a sampling effect or guarantee support for other values, models, or later requests. Start with a minimal request.
- Support on this page applies only to the regular `/openai/responses` endpoint. It does not imply that the same model supports `/openai/responses/compact`, WebSocket, or stateful `previous_response_id`.
- The five GPT models listed above currently have no verified Compact channel. Compact requests are rejected before billing when no explicitly enabled channel is available. Ordinary Responses and Responses WebSocket remain available.

## Request Examples

The examples below provide `input`. A continuation may omit `input` when it provides a valid `previous_response_id` and the selected channel supports stateful continuation. A response ID does not enable that capability on an unsupported channel. Tool results remain valid input items, including `function_call_output`.

### Text

```json
{
  "model": "gpt-5.4",
  "input": "Hello, introduce yourself in one sentence."
}
```

### Codex CLI-Style Parameters

```json
{
  "model": "gpt-5.5",
  "input": "Reply with READY only.",
  "reasoning": {
    "effort": "xhigh"
  },
  "store": false,
  "text": {
    "verbosity": "low"
  },
  "stream": true
}
```

### Image Understanding

```json
{
  "model": "gpt-5.4",
  "input": [
    {
      "type": "message",
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "What is in this image?"
        },
        {
          "type": "input_image",
          "image_url": "https://example.com/cat.png",
          "detail": "high"
        }
      ]
    }
  ]
}
```

### File Input

Use `file_data` plus `filename` to submit PDF content. `file_data` must be a complete Data URL.

```json
{
  "model": "gpt-5.4",
  "input": [
    {
      "type": "message",
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Summarize the key points in this PDF."
        },
        {
          "type": "input_file",
          "file_data": "data:application/pdf;base64,JVBERi0xLjQKJc...",
          "filename": "report.pdf"
        }
      ]
    }
  ]
}
```

### Image and File Input

```json
{
  "model": "gpt-5.4",
  "input": [
    {
      "type": "message",
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Give three conclusions based on the image and attachment."
        },
        {
          "type": "input_image",
          "image_url": "https://example.com/chart.png",
          "detail": "high"
        },
        {
          "type": "input_file",
          "file_data": "data:application/pdf;base64,JVBERi0xLjQKJc...",
          "filename": "notes.pdf"
        }
      ]
    }
  ]
}
```

### Streaming Output

```json
{
  "model": "gpt-5.4",
  "stream": true,
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Explain this diagram step by step."
        },
        {
          "type": "input_image",
          "image_url": "https://example.com/diagram.png"
        }
      ]
    }
  ]
}
```

## Response

Non-streaming responses follow OpenAI Responses style. Actual fields may vary with selected model capabilities.

### `id` (string)

Unique response identifier.

### `object` (string)

Response object type, usually `response`.

### `created_at` (integer)

Creation timestamp.

### `model` (string)

Actual model used.

### `output` (object[])

Output item list. Common items include `message`, `function_call`, and tool-related output.

### `usage` (object)

Token usage statistics, such as `input_tokens`, `output_tokens`, and `total_tokens`.

### Success Example

```json
{
  "id": "resp_123",
  "object": "response",
  "created_at": 1766534400,
  "model": "gpt-5.4",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "text": "The image shows a cat, and the attachment is a document about pet care."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 128,
    "output_tokens": 42,
    "total_tokens": 170
  }
}
```

## Streaming Response

When `stream=true`, the endpoint returns Server-Sent Events.

```text
event: response.output_text.delta
data: {"type":"response.output_text.delta","delta":"The image"}

event: response.completed
data: {"type":"response.completed","response":{"id":"resp_123"}}
```

Read events until `response.completed` or the connection closes.

## Error Response

See [Error Codes and Troubleshooting](https://apihop.ai/en/docs/api-reference/errors) for the full code reference, protocol differences, and diagnostic steps.

Platform-generated HTTP errors use the flat fields below instead of an `error` wrapper. Some upstream errors may retain their original structure; errors inside an already-started SSE stream do not follow this HTTP response example.

```json
{
  "code": 40000,
  "message": "Insufficient credit. Required: 30000, Available: 20000",
  "type": "api_error"
}
```

## Notes

- The `Responses` endpoint uses `input`, not `messages`. If your client only sends `messages`, use `/openai/v1/chat/completions`.
- Image input uses `input_image`; `image_url` must be a public `http://` or `https://` URL. Base64 Data URLs are not supported for images.
- File input uses `input_file`. For PDFs, use `file_data` plus `filename`; `file_data` should be a complete `data:application/pdf;base64,...` URL.
- Audio input/output, image generation tools, file search, and other advanced capabilities depend on the selected model and available features.
- The fields listed on this page form the current public Responses request contract; do not assume unlisted fields are available.
- `/openai/responses` is the recommended public path.
- `/v1/responses` follows the same public request and response contract.
- `/compat/v1/responses` follows the same public request and response contract.
- `/openai/v1/responses` follows the same public request and response contract.

OpenAI 相容的 Responses API。此端點使用 OpenAI 風格的 input，支援文字、公開圖像網址、PDF 檔案輸入、工具呼叫、推理選項與串流參數。

text

POST https://api.apihop.ai/openai/responses

驗證

所有請求均需要 Bearer Token 驗證。

http

Authorization: Bearer YOUR_API_KEY

請求主體

modelstring必填預設: gpt-5.4

目前已啟用且支援 Responses 的模型：

gpt-5.4
gpt-5.5
gpt-5.6-sol
gpt-5.6-terra
gpt-6-astra

目前 API 金鑰可見的模型，請見模型目錄。

inputstring | object[]

輸入內容。除非提供非空的 previous_response_id，否則必填。兩個欄位均省略或輸入類型無效時，會在計費前回傳 400。

支援形式：

字串，相當於一則 user 文字輸入。
輸入項目陣列，用於對話歷程、多模態輸入與工具呼叫結果。

輸入陣列中的每個物件可包含以下欄位：

typestring

輸入項目類型。

常見值：

message：訊息輸入。
function_call_output：函式工具呼叫的結果。

rolestring

type=message 時的角色。

常見值：

developer
system
user
assistant

contentstring | object[]

訊息內容。

多模態請求請使用內容區塊陣列。內容區塊支援：

typestring

內容區塊類型。

目前支援：

input_text
input_image
input_file

textstring

type=input_text 時的文字內容。

image_urlstring

type=input_image 時的公開圖像網址。

僅支援可公開存取的 http:// 或 https:// 圖像網址。不支援像 data:image/...;base64,... 這樣的 Base64 資料網址。

detailstring預設: auto

type=input_image 時的圖像細節層級。

常見值：

auto
low
high

file_datastring

type=input_file 時的檔案內容資料網址。PDF 可使用 data:application/pdf;base64,...。

filenamestring

type=input_file 時的檔案名稱。

instructionsstring

插入模型上下文的系統或開發者指示。

max_output_tokensinteger

選填的最大輸出 token，必須為正整數。省略此欄位會使用所選模型的上游預設值。依模型而定，預算可能包含推理 token 與最終文字。預算過小可能截斷答案，或在產生最終文字前耗盡；提高預算可能增加費用。

streamboolean預設: false

是否串流回應。

false：傳回完整回應
true：傳回 OpenAI Responses 風格的 SSE 事件

temperaturenumber預設: 1.0

取樣溫度，通常介於 0 至 2。

top_pnumber預設: 1.0

核心取樣參數，通常介於 0 至 1。

textobject

文字輸出設定。

text.formatobject

文字格式設定，例如 { "type": "text" } 或 JSON schema。

text.verbositystring

輸出詳盡程度，例如 low、medium 或 high。是否支援取決於所選模型。

toolsobject[]

工具定義。可用性取決於所選模型與可用功能。

tool_choicestring | object

工具選擇策略。

parallel_tool_callsboolean

是否允許平行工具呼叫。

reasoningobject

推理相關選項。

includestring[]

要包含在回應中的額外欄位。

prompt_cache_keystring

用於重用提示詞快取的快取鍵。

prompt_cache_retentionstring

提示詞快取保留策略。支援的值取決於所選模型與可用功能。

safety_identifierstring

用於安全控制的穩定終端使用者識別碼。

storeboolean

是否允許儲存回應狀態。

模型參數差異

原生 OpenAI 相容 Responses 轉送會在上游請求中保留 top_p；驗證與取樣行為取決於所選模型及上游。2026-09-26 的檢查接受 gpt-5.5、gpt-5.6-sol 與 gpt-5.6-terra 的 top_p: 0.9。接受與轉送不代表有取樣效果，也不保證其他值、模型或之後請求受支援。請從最小請求開始。
本頁的支援範圍僅適用於一般 /openai/responses 端點，不代表同一模型支援 /openai/responses/compact、WebSocket 或具狀態的 previous_response_id。
上述五個 GPT 模型目前沒有經驗證的 Compact 通道。若無明確啟用的通道，Compact 請求會在計費前遭拒。一般 Responses 與 Responses WebSocket 仍可使用。

請求範例

以下範例均提供 input。接續請求若提供有效的 previous_response_id，且所選通道支援具狀態接續，則可省略 input。回應 ID 不會在不支援的通道上啟用此能力。工具結果仍是有效輸入項目，包含 function_call_output。

文字

json

{
  "model": "gpt-5.4",
  "input": "Hello, introduce yourself in one sentence."
}

Codex CLI 風格參數

json

{
  "model": "gpt-5.5",
  "input": "Reply with READY only.",
  "reasoning": {
    "effort": "xhigh"
  },
  "store": false,
  "text": {
    "verbosity": "low"
  },
  "stream": true
}

圖像理解

json

{
  "model": "gpt-5.4",
  "input": [
    {
      "type": "message",
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "What is in this image?"
        },
        {
          "type": "input_image",
          "image_url": "https://example.com/cat.png",
          "detail": "high"
        }
      ]
    }
  ]
}

檔案輸入

使用 file_data 加上 filename 提交 PDF 內容。file_data 必須是完整資料網址。

json

{
  "model": "gpt-5.4",
  "input": [
    {
      "type": "message",
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Summarize the key points in this PDF."
        },
        {
          "type": "input_file",
          "file_data": "data:application/pdf;base64,JVBERi0xLjQKJc...",
          "filename": "report.pdf"
        }
      ]
    }
  ]
}

圖像與檔案輸入

json

{
  "model": "gpt-5.4",
  "input": [
    {
      "type": "message",
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Give three conclusions based on the image and attachment."
        },
        {
          "type": "input_image",
          "image_url": "https://example.com/chart.png",
          "detail": "high"
        },
        {
          "type": "input_file",
          "file_data": "data:application/pdf;base64,JVBERi0xLjQKJc...",
          "filename": "notes.pdf"
        }
      ]
    }
  ]
}

串流輸出

json

{
  "model": "gpt-5.4",
  "stream": true,
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Explain this diagram step by step."
        },
        {
          "type": "input_image",
          "image_url": "https://example.com/diagram.png"
        }
      ]
    }
  ]
}

回應

非串流回應遵循 OpenAI Responses 風格。實際欄位可能隨所選模型能力而異。

idstring

回應的唯一識別碼。

objectstring

回應物件類型，通常為 response。

created_atinteger

建立時間戳記。

modelstring

實際使用的模型。

outputobject[]

輸出項目列表。常見項目包含 message、function_call 及工具相關輸出。

usageobject

Token 用量統計，例如 input_tokens、output_tokens 與 total_tokens。

成功範例

json

{
  "id": "resp_123",
  "object": "response",
  "created_at": 1766534400,
  "model": "gpt-5.4",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "text": "The image shows a cat, and the attachment is a document about pet care."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 128,
    "output_tokens": 42,
    "total_tokens": 170
  }
}

串流回應

設定 stream=true 時，端點會傳回 Server-Sent Events。

text

event: response.output_text.delta
data: {"type":"response.output_text.delta","delta":"The image"}

event: response.completed
data: {"type":"response.completed","response":{"id":"resp_123"}}

持續讀取事件，直到 response.completed 或連線關閉。

錯誤回應

完整代碼參考、協定差異及診斷步驟，請見錯誤代碼與疑難排解。

平台產生的 HTTP 錯誤使用下列扁平欄位，而非 error 包裝。部分上游錯誤可能保留原始結構；已開始的 SSE 串流內錯誤不遵循此 HTTP 回應範例。

json

{
  "code": 40000,
  "message": "Insufficient credit. Required: 30000, Available: 20000",
  "type": "api_error"
}

注意事項

Responses 端點使用 input，而非 messages。若客戶端只傳送 messages，請使用 /openai/v1/chat/completions。
圖像輸入使用 input_image；image_url 必須是公開的 http:// 或 https:// 網址。圖像不支援 Base64 資料網址。
檔案輸入使用 input_file。PDF 請使用 file_data 加上 filename，file_data 應為完整的 data:application/pdf;base64,... 網址。
音訊輸入／輸出、圖像生成工具、檔案搜尋及其他進階能力，取決於所選模型與可用功能。
本頁所列欄位構成目前公開的 Responses 請求契約，請勿假設未列出的欄位可用。
/openai/responses 是建議的公開路徑。
/v1/responses 遵循相同的公開請求與回應契約。
/compat/v1/responses 遵循相同的公開請求與回應契約。
/openai/v1/responses 遵循相同的公開請求與回應契約。