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을 사용하며 텍스트, 공개 이미지 URL, PDF 파일 입력, 도구 호출, 추론 옵션 및 스트리밍 매개변수를 지원합니다.

text

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

인증

모든 요청에는 Bearer 토큰 인증이 필요합니다.

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일 때의 공개 이미지 URL입니다.

공개적으로 접근 가능한 http:// 또는 https:// 이미지 URL만 지원합니다. data:image/...;base64,... 같은 Base64 데이터 URL은 지원하지 않습니다.

detailstring기본값: auto

type=input_image일 때의 이미지 세부 수준입니다.

일반적인 값:

auto
low
high

file_datastring

type=input_file일 때의 파일 콘텐츠 데이터 URL입니다. PDF는 data:application/pdf;base64,...를 사용할 수 있습니다.

filenamestring

type=input_file일 때의 파일 이름입니다.

instructionsstring

모델 컨텍스트에 삽입하는 시스템 또는 개발자 지시입니다.

max_output_tokensinteger

선택적 최대 출력 토큰으로 양의 정수입니다. 생략하면 선택한 모델의 공급자 기본값을 사용합니다. 모델에 따라 예산에 추론 토큰과 최종 텍스트가 모두 포함될 수 있습니다. 작은 예산은 답변을 잘라내거나 최종 텍스트 전에 소진될 수 있으며 늘리면 비용이 증가할 수 있습니다.

streamboolean기본값: false

응답 스트리밍 여부입니다.

false: 완전한 응답 하나 반환
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를 지원한다는 뜻은 아닙니다.
위의 다섯 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는 완전한 데이터 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 데이터 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는 같은 공개 요청 및 응답 계약을 따릅니다.