Multimodale OpenAI Responses | API-Dokumentation

# 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-kompatible Responses-API. Dieser Endpunkt verwendet input im OpenAI-Stil und unterstützt Text, öffentliche Bild-URLs, PDF-Dateieingaben, Werkzeugaufrufe, Denkoptionen und Streaming-Parameter.

text

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

Authentifizierung

Alle Anfragen erfordern Bearer-Token-Authentifizierung.

http

Authorization: Bearer YOUR_API_KEY

Anfragekörper

modelstringerforderlichStandard: gpt-5.4

Aktuell aktive Modelle mit Responses-Unterstützung:

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

Die für den aktuellen API-Schlüssel sichtbaren Modelle finden Sie im Modellkatalog.

inputstring | object[]

Eingabeinhalt. Erforderlich, sofern keine nicht leere previous_response_id angegeben wird. Das Weglassen beider Felder oder ein ungültiger Eingabetyp liefert vor der Abrechnung 400.

Unterstützte Formen:

Eine Zeichenfolge, entsprechend einer Texteingabe von user.
Ein Array von Eingabeelementen für Unterhaltungsverlauf, multimodale Eingaben und Werkzeugergebnisse.

Jedes Objekt im Eingabearray kann folgende Felder enthalten:

typestring

Typ des Eingabeelements.

Häufige Werte:

message: eine Nachrichteneingabe.
function_call_output: das Ergebnis eines Funktionswerkzeugaufrufs.

rolestring

Rolle bei type=message.

Häufige Werte:

developer
system
user
assistant

contentstring | object[]

Nachrichteninhalt.

Verwenden Sie für multimodale Anfragen ein Array von Inhaltsblöcken. Inhaltsblöcke unterstützen:

typestring

Typ des Inhaltsblocks.

Derzeit unterstützt:

input_text
input_image
input_file

textstring

Textinhalt bei type=input_text.

image_urlstring

Öffentliche Bild-URL bei type=input_image.

Nur öffentlich zugängliche Bild-URLs mit http:// oder https:// werden unterstützt. Base64-Daten-URLs wie data:image/...;base64,... werden nicht unterstützt.

detailstringStandard: auto

Bilddetailgrad bei type=input_image.

Häufige Werte:

auto
low
high

file_datastring

Daten-URL des Dateiinhalts bei type=input_file. PDFs können data:application/pdf;base64,... verwenden.

filenamestring

Dateiname bei type=input_file.

instructionsstring

System- oder Entwickleranweisungen, die in den Modellkontext eingefügt werden.

max_output_tokensinteger

Optionale maximale Ausgabetokens als positive Ganzzahl. Lassen Sie das Feld weg, um den Anbieterstandard des gewählten Modells zu verwenden. Je nach Modell umfasst das Budget Denktokens und endgültigen Text. Ein kleines Budget kann die Antwort abschneiden oder vor dem endgültigen Text verbraucht sein; eine Erhöhung kann die Kosten steigern.

streambooleanStandard: false

Ob die Antwort gestreamt wird.

false: eine vollständige Antwort zurückgeben
true: SSE-Ereignisse im OpenAI-Responses-Stil zurückgeben

temperaturenumberStandard: 1.0

Sampling-Temperatur, gewöhnlich von 0 bis 2.

top_pnumberStandard: 1.0

Nucleus-Sampling-Parameter, gewöhnlich von 0 bis 1.

textobject

Konfiguration der Textausgabe.

text.formatobject

Textformatkonfiguration, etwa { "type": "text" } oder ein JSON-Schema.

text.verbositystring

Ausführlichkeit der Ausgabe, etwa low, medium oder high. Die Unterstützung hängt vom gewählten Modell ab.

toolsobject[]

Werkzeugdefinitionen. Die Verfügbarkeit hängt vom gewählten Modell und den verfügbaren Funktionen ab.

tool_choicestring | object

Werkzeugauswahlregel.

parallel_tool_callsboolean

Ob parallele Werkzeugaufrufe erlaubt sind.

reasoningobject

Optionen zum Denkprozess.

includestring[]

Zusätzliche Felder, die in der Antwort enthalten sein sollen.

prompt_cache_keystring

Prompt-Cache-Schlüssel zur Wiederverwendung des Prompt-Caches.

prompt_cache_retentionstring

Aufbewahrungsregel für den Prompt-Cache. Unterstützte Werte hängen vom gewählten Modell und den verfügbaren Funktionen ab.

safety_identifierstring

Stabile Endnutzerkennung für Sicherheitskontrollen.

storeboolean

Ob der Antwortzustand gespeichert werden darf.

Unterschiede bei Modellparametern

Native OpenAI-kompatible Responses-Weiterleitung behält top_p in der Anbieteranfrage bei; Validierung und Sampling-Verhalten hängen von Modell und Anbieter ab. Die Prüfungen am 2026-09-26 akzeptierten top_p: 0.9 für gpt-5.5, gpt-5.6-sol und gpt-5.6-terra. Annahme und Weiterleitung beweisen keine Sampling-Wirkung und garantieren keine Unterstützung für andere Werte, Modelle oder spätere Anfragen. Beginnen Sie mit einer minimalen Anfrage.
Die Unterstützung auf dieser Seite gilt nur für den regulären Endpunkt /openai/responses. Sie bedeutet nicht, dass dasselbe Modell /openai/responses/compact, WebSocket oder zustandsbehaftetes previous_response_id unterstützt.
Die fünf oben aufgeführten GPT-Modelle haben derzeit keinen verifizierten Compact-Kanal. Ohne ausdrücklich aktivierten Kanal werden Compact-Anfragen vor der Abrechnung abgelehnt. Normale Responses und Responses WebSocket bleiben verfügbar.

Anfragebeispiele

Die folgenden Beispiele enthalten input. Eine Fortsetzung darf input weglassen, wenn sie eine gültige previous_response_id angibt und der gewählte Kanal zustandsbehaftete Fortsetzung unterstützt. Eine Antwort-ID aktiviert diese Fähigkeit nicht auf einem nicht unterstützten Kanal. Werkzeugergebnisse bleiben gültige Eingabeelemente, einschließlich function_call_output.

Textinhalt

json

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

Parameter im Codex-CLI-Stil

json

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

Bildverständnis

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

Dateieingabe

Verwenden Sie file_data zusammen mit filename, um PDF-Inhalt zu übermitteln. file_data muss eine vollständige Daten-URL sein.

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

Bild- und Dateieingabe

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

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

Antwort

Antworten ohne Streaming folgen dem OpenAI-Responses-Stil. Tatsächliche Felder können je nach Fähigkeiten des gewählten Modells variieren.

idstring

Eindeutige Antwortkennung.

objectstring

Antwortobjekttyp, gewöhnlich response.

created_atinteger

Erstellungszeitstempel.

modelstring

Tatsächlich verwendetes Modell.

outputobject[]

Liste der Ausgabeelemente. Häufige Elemente sind message, function_call und werkzeugbezogene Ausgabe.

usageobject

Tokennutzungsstatistik, etwa input_tokens, output_tokens und total_tokens.

Erfolgsbeispiel

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

Bei stream=true liefert der Endpunkt 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"}}

Lesen Sie Ereignisse bis response.completed oder bis die Verbindung geschlossen wird.

Fehlerantwort

Die vollständige Codereferenz, Protokollunterschiede und Diagnoseschritte finden Sie unter Fehlercodes und Fehlerbehebung.

Von der Plattform erzeugte HTTP-Fehler verwenden die folgenden flachen Felder statt einer error-Hülle. Manche Anbieterfehler können ihre Originalstruktur behalten; Fehler in einem bereits gestarteten SSE-Stream folgen nicht diesem HTTP-Antwortbeispiel.

json

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

Hinweise

Der Endpunkt Responses verwendet input, nicht messages. Sendet Ihr Client nur messages, verwenden Sie /openai/v1/chat/completions.
Bildeingaben verwenden input_image; image_url muss eine öffentliche http://- oder https://-URL sein. Base64-Daten-URLs werden für Bilder nicht unterstützt.
Dateieingaben verwenden input_file. Verwenden Sie für PDFs file_data zusammen mit filename; file_data sollte eine vollständige data:application/pdf;base64,...-URL sein.
Audioeingabe/-ausgabe, Bilderzeugungswerkzeuge, Dateisuche und weitere erweiterte Fähigkeiten hängen vom gewählten Modell und den verfügbaren Funktionen ab.
Die auf dieser Seite aufgeführten Felder bilden den aktuellen öffentlichen Responses-Anfragevertrag; gehen Sie nicht davon aus, dass nicht aufgeführte Felder verfügbar sind.
/openai/responses ist der empfohlene öffentliche Pfad.
/v1/responses folgt demselben öffentlichen Anfrage- und Antwortvertrag.
/compat/v1/responses folgt demselben öffentlichen Anfrage- und Antwortvertrag.
/openai/v1/responses folgt demselben öffentlichen Anfrage- und Antwortvertrag.