OpenAI マルチモーダル Responses | 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 を使用し、テキスト、公開画像 URL、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 を返します。

対応する形式：

文字列。1 件の 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 の場合の公開画像 URL です。

公開アクセス可能な http:// または https:// の画像 URL のみに対応しています。 data:image/...;base64,... などの Base64 Data URL には対応していません。

detailstring既定値: auto

type=input_image の場合の画像の詳細レベルです。

主な値：

auto
low
high

file_datastring

type=input_file の場合のファイル内容の Data URL です。PDF には data:application/pdf;base64,... を使用できます。

filenamestring

type=input_file の場合のファイル名です。

instructionsstring

モデルのコンテキストに挿入する、システムまたは開発者の指示です。

max_output_tokensinteger

任意の最大出力トークン数で、正の整数を指定します。省略すると、選択したモデルの上流側の既定値を使用します。モデルによっては、予算に最終テキストだけでなく推論トークンも含まれます。予算が小さいと、回答が途中で切れたり、最終テキストの生成前に予算を使い切ったりする可能性があります。予算を増やすと費用が増える場合があります。

streamboolean既定値: false

レスポンスをストリーミングするかどうかを指定します。

false：1 つの完全なレスポンスを返す
true：OpenAI Responses 形式の SSE イベントを返す

temperaturenumber既定値: 1.0

サンプリング温度です。通常は 0 から 2 です。

top_pnumber既定値: 1.0

ニュークリアスサンプリングのパラメータです。通常は 0 から 1 です。

textobject

テキスト出力の設定です。

text.formatobject

テキスト形式の設定です。{ "type": "text" } または JSON スキーマなどを指定します。

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 にも対応することを意味しません。
上記の 5 つの 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"
        }
      ]
    }
  ]
}

ファイル入力

PDF の内容を送信するには、file_data と filename を使用してください。file_data は完全な 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"
        }
      ]
    }
  ]
}

画像とファイルの入力

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

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 エンドポイントは messages ではなく input を使用します。クライアントが messages しか送信できない場合は、/openai/v1/chat/completions を使用してください。
画像入力には input_image を使用します。image_url は公開の http:// または https:// URL にする必要があります。画像の Base64 Data URL には対応していません。
ファイル入力には input_file を使用します。PDF には file_data と filename を使用してください。file_data は完全な data:application/pdf;base64,... URL にします。
音声の入出力、画像生成ツール、ファイル検索、その他の高度な機能は、選択したモデルと利用可能な機能によって異なります。
このページに記載されたフィールドが、現在公開されている Responses のリクエスト仕様です。記載されていないフィールドが利用できるとは想定しないでください。
推奨する公開パスは /openai/responses です。
/v1/responses も同じ公開のリクエスト・レスポンス仕様に従います。
/compat/v1/responses も同じ公開のリクエスト・レスポンス仕様に従います。
/openai/v1/responses も同じ公開のリクエスト・レスポンス仕様に従います。