# 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 Hop

OpenAI Responses แบบหลายสื่อ

API Responses ที่เข้ากันได้กับ OpenAI เอนด์พอยต์นี้ใช้ input รูปแบบ OpenAI รองรับข้อความ URL ภาพสาธารณะ อินพุตไฟล์ PDF การเรียกเครื่องมือ ตัวเลือกการให้เหตุผล และพารามิเตอร์สตรีม

POSThttps://api.apihop.ai/openai/responses

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

URL ภาพสาธารณะเมื่อ type=input_image

รองรับเฉพาะ URL ภาพ http:// หรือ https:// ที่เข้าถึงสาธารณะ ไม่รองรับ Base64 Data URL เช่น data:image/...;base64,...

detailstringค่าเริ่มต้น: auto

ระดับรายละเอียดภาพเมื่อ type=input_image

ค่าที่พบบ่อย:

auto
low
high

file_datastring

Data URL เนื้อหาไฟล์เมื่อ type=input_file โดย PDF อาจใช้ data:application/pdf;base64,...

filenamestring

ชื่อไฟล์เมื่อ type=input_file

instructionsstring

คำสั่งระบบหรือนักพัฒนาที่แทรกในบริบทโมเดล

max_output_tokensinteger

โทเคนเอาต์พุตสูงสุดแบบไม่บังคับ เป็นจำนวนเต็มบวก ไม่ระบุเพื่อใช้ค่าเริ่มต้นต้นทางของโมเดลที่เลือก งบอาจรวมโทเคนการให้เหตุผลและข้อความสุดท้ายตามโมเดล งบน้อยอาจตัดคำตอบหรือหมดก่อนข้อความสุดท้าย การเพิ่มอาจเพิ่มค่าใช้จ่าย

streambooleanค่าเริ่มต้น: false

จะสตรีมการตอบกลับหรือไม่

false: ส่งการตอบกลับสมบูรณ์หนึ่งชุด
true: ส่งเหตุการณ์ SSE รูปแบบ OpenAI Responses

temperaturenumberค่าเริ่มต้น: 1.0

อุณหภูมิการสุ่ม โดยทั่วไปตั้งแต่ 0 ถึง 2

top_pnumberค่าเริ่มต้น: 1.0

พารามิเตอร์สุ่มแบบ nucleus โดยทั่วไปตั้งแต่ 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

อาจเก็บสถานะการตอบกลับหรือไม่

ความต่างพารามิเตอร์โมเดล

การส่งต่อ Responses ดั้งเดิมที่เข้ากันได้กับ OpenAI คง top_p ในคำขอต้นทาง การตรวจและพฤติกรรมสุ่มขึ้นอยู่กับโมเดลและต้นทาง การตรวจเมื่อ 2026-09-26 ยอมรับ top_p: 0.9 สำหรับ gpt-5.5, gpt-5.6-sol และ gpt-5.6-terra การยอมรับและส่งต่อไม่พิสูจน์ผลการสุ่มหรือรับประกันค่าอื่น โมเดลอื่น หรือคำขอภายหลัง เริ่มด้วยคำขอขั้นต่ำ
การรองรับในหน้านี้ใช้เฉพาะเอนด์พอยต์ /openai/responses ปกติ ไม่ได้หมายความว่าโมเดลเดียวกันรองรับ /openai/responses/compact, WebSocket หรือ previous_response_id แบบเก็บสถานะ
โมเดล GPT ห้ารายการข้างต้นยังไม่มีช่อง Compact ที่ตรวจยืนยันปัจจุบัน คำขอ Compact ถูกปฏิเสธก่อนคิดค่าบริการเมื่อไม่มีช่องที่เปิดใช้ชัดเจน Responses ปกติและ Responses WebSocket ยังใช้ได้

ตัวอย่างคำขอ

ตัวอย่างด้านล่างระบุ input การต่อเนื่องอาจละ input เมื่อระบุ previous_response_id ถูกต้องและช่องที่เลือกรองรับการต่อเนื่องแบบเก็บสถานะ 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 ต้องเป็น 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 ใช้ input ไม่ใช่ messages หากไคลเอนต์ส่งเฉพาะ messages ใช้ /openai/v1/chat/completions
อินพุตภาพใช้ input_image โดย image_url ต้องเป็น URL สาธารณะ http:// หรือ https:// ไม่รองรับ Base64 Data URL สำหรับภาพ
อินพุตไฟล์ใช้ input_file สำหรับ PDF ใช้ file_data พร้อม filename โดย file_data ควรเป็น URL data:application/pdf;base64,... สมบูรณ์
อินพุต/เอาต์พุตเสียง เครื่องมือสร้างภาพ ค้นหาไฟล์ และความสามารถขั้นสูงอื่นขึ้นอยู่กับโมเดลที่เลือกและฟีเจอร์ที่มี
ฟิลด์ในหน้านี้เป็นข้อกำหนดคำขอ Responses สาธารณะปัจจุบัน อย่าคิดว่าฟิลด์ที่ไม่ระบุใช้ได้
/openai/responses เป็นเส้นทางสาธารณะที่แนะนำ
/v1/responses ใช้ข้อกำหนดคำขอและตอบกลับสาธารณะเดียวกัน
/compat/v1/responses ใช้ข้อกำหนดคำขอและตอบกลับสาธารณะเดียวกัน
/openai/v1/responses ใช้ข้อกำหนดคำขอและตอบกลับสาธารณะเดียวกัน