Responses Multimodal OpenAI | Dokumentasi 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.

API Responses yang kompatibel OpenAI. Endpoint ini menggunakan input bergaya OpenAI, mendukung teks, URL gambar publik, masukan file PDF, panggilan alat, opsi penalaran, dan parameter streaming.

text

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

Autentikasi

Semua permintaan memerlukan autentikasi Bearer Token.

http

Authorization: Bearer YOUR_API_KEY

Isi

modelstringwajibBawaan: gpt-5.4

Model aktif saat ini dengan dukungan Responses:

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

Lihat Katalog Model untuk model yang terlihat oleh API Key saat ini.

inputstring | object[]

Konten masukan. Wajib kecuali previous_response_id yang tidak kosong disediakan. Menghilangkan kedua kolom atau menggunakan tipe masukan yang tidak valid mengembalikan 400 sebelum penagihan.

Bentuk yang didukung:

String, setara dengan satu masukan teks user.
Larik item masukan untuk riwayat percakapan, masukan multimodal, dan hasil panggilan alat.

Setiap objek dalam larik masukan dapat berisi kolom berikut:

typestring

Tipe item masukan.

Nilai umum:

message: masukan pesan.
function_call_output: hasil panggilan alat fungsi.

rolestring

Peran saat type=message.

Nilai umum:

developer
system
user
assistant

contentstring | object[]

Isi pesan.

Gunakan larik blok konten untuk permintaan multimodal. Blok konten mendukung:

typestring

Tipe blok konten.

Saat ini didukung:

input_text
input_image
input_file

textstring

Konten teks saat type=input_text.

image_urlstring

URL gambar publik saat type=input_image.

Hanya URL gambar http:// atau https:// yang dapat diakses publik yang didukung. Data URL Base64 seperti data:image/...;base64,... tidak didukung.

detailstringBawaan: auto

Tingkat detail gambar saat type=input_image.

Nilai umum:

auto
low
high

file_datastring

Data URL isi file saat type=input_file. PDF dapat menggunakan data:application/pdf;base64,....

filenamestring

Nama file saat type=input_file.

instructionsstring

Instruksi sistem atau pengembang yang dimasukkan ke konteks model.

max_output_tokensinteger

Batas maksimum token output opsional, berupa bilangan bulat positif. Hilangkan kolom ini untuk menggunakan nilai bawaan penyedia hulu bagi model yang dipilih. Bergantung pada model, anggaran ini dapat mencakup token penalaran dan teks akhir. Anggaran kecil dapat memotong jawaban atau habis sebelum teks akhir dihasilkan; menaikkannya dapat meningkatkan biaya.

streambooleanBawaan: false

Apakah respons dikirim secara streaming.

false: kembalikan satu respons lengkap
true: kembalikan peristiwa SSE bergaya OpenAI Responses

temperaturenumberBawaan: 1.0

Temperatur sampling, biasanya dari 0 hingga 2.

top_pnumberBawaan: 1.0

Parameter nucleus sampling, biasanya dari 0 hingga 1.

textobject

Konfigurasi keluaran teks.

text.formatobject

Konfigurasi format teks, seperti { "type": "text" } atau skema JSON.

text.verbositystring

Tingkat kerincian keluaran, seperti low, medium, atau high. Dukungan bergantung pada model yang dipilih.

toolsobject[]

Definisi alat. Ketersediaan bergantung pada model yang dipilih dan fitur yang tersedia.

tool_choicestring | object

Kebijakan pemilihan alat.

parallel_tool_callsboolean

Apakah panggilan alat paralel diizinkan.

reasoningobject

Opsi terkait penalaran.

includestring[]

Kolom tambahan untuk disertakan dalam respons.

prompt_cache_keystring

Kunci cache prompt untuk penggunaan ulang cache prompt.

prompt_cache_retentionstring

Kebijakan retensi cache prompt. Nilai yang didukung bergantung pada model yang dipilih dan fitur yang tersedia.

safety_identifierstring

Pengenal pengguna akhir yang stabil untuk kontrol keamanan.

storeboolean

Apakah status respons boleh disimpan.

Perbedaan Parameter Model

Penerusan Responses native yang kompatibel OpenAI mempertahankan top_p dalam permintaan upstream; validasi dan perilaku sampling bergantung pada model yang dipilih serta upstream. Pemeriksaan pada 2026-09-26 menerima top_p: 0.9 untuk gpt-5.5, gpt-5.6-sol, dan gpt-5.6-terra. Penerimaan dan penerusan tidak membuktikan efek sampling atau menjamin dukungan untuk nilai lain, model lain, atau permintaan berikutnya. Mulai dengan permintaan minimal.
Dukungan di halaman ini hanya berlaku untuk endpoint /openai/responses biasa. Ini tidak berarti model yang sama mendukung /openai/responses/compact, WebSocket, atau previous_response_id dengan status tersimpan.
Lima model GPT yang tercantum di atas saat ini tidak memiliki kanal Compact terverifikasi. Permintaan Compact ditolak sebelum penagihan jika tidak tersedia kanal yang diaktifkan secara eksplisit. Responses biasa dan Responses WebSocket tetap tersedia.

Contoh Permintaan

Contoh di bawah menyediakan input. Kelanjutan dapat menghilangkan input jika menyediakan previous_response_id yang valid dan kanal yang dipilih mendukung kelanjutan dengan status tersimpan. ID respons tidak mengaktifkan kemampuan tersebut pada kanal yang tidak mendukungnya. Hasil alat tetap merupakan item masukan yang valid, termasuk function_call_output.

Teks

json

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

Parameter Bergaya Codex CLI

json

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

Pemahaman Gambar

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"
        }
      ]
    }
  ]
}

Masukan File

Gunakan file_data beserta filename untuk mengirim isi PDF. file_data harus berupa Data URL lengkap.

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"
        }
      ]
    }
  ]
}

Masukan Gambar dan File

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"
        }
      ]
    }
  ]
}

Keluaran Streaming

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"
        }
      ]
    }
  ]
}

Respons

Respons tanpa streaming mengikuti gaya OpenAI Responses. Kolom sebenarnya dapat berbeda sesuai kemampuan model yang dipilih.

idstring

Pengenal respons unik.

objectstring

Tipe objek respons, biasanya response.

created_atinteger

Stempel waktu pembuatan.

modelstring

Model yang sebenarnya digunakan.

outputobject[]

Daftar item keluaran. Item umum mencakup message, function_call, dan keluaran terkait alat.

usageobject

Statistik penggunaan token, seperti input_tokens, output_tokens, dan total_tokens.

Contoh Berhasil

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
  }
}

Respons Streaming

Saat stream=true, endpoint mengembalikan 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"}}

Baca peristiwa hingga response.completed atau koneksi ditutup.

Respons Kesalahan

Lihat Kode Kesalahan dan Pemecahan Masalah untuk referensi kode lengkap, perbedaan protokol, dan langkah diagnosis.

Kesalahan HTTP yang dihasilkan platform menggunakan kolom datar di bawah, bukan pembungkus error. Sebagian kesalahan upstream dapat mempertahankan struktur aslinya; kesalahan di dalam stream SSE yang sudah dimulai tidak mengikuti contoh respons HTTP ini.

json

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

Catatan

Endpoint Responses menggunakan input, bukan messages. Jika klien Anda hanya mengirim messages, gunakan /openai/v1/chat/completions.
Masukan gambar menggunakan input_image; image_url harus berupa URL http:// atau https:// publik. Data URL Base64 tidak didukung untuk gambar.
Masukan file menggunakan input_file. Untuk PDF, gunakan file_data beserta filename; file_data harus berupa URL data:application/pdf;base64,... lengkap.
Masukan/keluaran audio, alat pembuatan gambar, pencarian file, dan kemampuan lanjutan lainnya bergantung pada model yang dipilih dan fitur yang tersedia.
Kolom yang tercantum di halaman ini membentuk kontrak permintaan Responses publik saat ini; jangan menganggap kolom yang tidak tercantum tersedia.
/openai/responses adalah jalur publik yang direkomendasikan.
/v1/responses mengikuti kontrak permintaan dan respons publik yang sama.
/compat/v1/responses mengikuti kontrak permintaan dan respons publik yang sama.
/openai/v1/responses mengikuti kontrak permintaan dan respons publik yang sama.