Multimodalne OpenAI Responses | Dokumentacja 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 zgodne z OpenAI. Ten punkt końcowy używa input w stylu OpenAI i obsługuje tekst, publiczne adresy URL obrazów, pliki PDF na wejściu, wywołania narzędzi, opcje rozumowania i parametry strumieniowania.

text

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

Uwierzytelnianie

Wszystkie żądania wymagają uwierzytelniania tokenem Bearer.

http

Authorization: Bearer YOUR_API_KEY

Treść żądania

modelstringWymaganeWartość domyślna: gpt-5.4

Obecnie aktywne modele obsługujące Responses:

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

Modele widoczne dla bieżącego klucza API znajdziesz w katalogu modeli.

inputstring | object[]

Treść wejściowa. Wymagana, chyba że podano niepuste previous_response_id. Pominięcie obu pól lub użycie nieprawidłowego typu wejścia zwraca 400 przed rozliczeniem.

Obsługiwane formy:

Ciąg znaków, równoważny jednemu tekstowemu wejściu user.
Tablica elementów wejściowych dla historii rozmowy, wejścia multimodalnego i wyników wywołań narzędzi.

Każdy obiekt w tablicy wejściowej może zawierać następujące pola:

typestring

Typ elementu wejściowego.

Typowe wartości:

message: wiadomość wejściowa.
function_call_output: wynik wywołania narzędzia funkcyjnego.

rolestring

Rola przy type=message.

Typowe wartości:

developer
system
user
assistant

contentstring | object[]

Treść wiadomości.

W żądaniach multimodalnych używaj tablicy bloków treści. Bloki treści obsługują:

typestring

Typ bloku treści.

Obecnie obsługiwane:

input_text
input_image
input_file

textstring

Treść tekstowa przy type=input_text.

image_urlstring

Publiczny adres URL obrazu przy type=input_image.

Obsługiwane są tylko publicznie dostępne adresy URL obrazów http:// lub https://. Adresy Data URL Base64, takie jak data:image/...;base64,..., nie są obsługiwane.

detailstringWartość domyślna: auto

Poziom szczegółowości obrazu przy type=input_image.

Typowe wartości:

auto
low
high

file_datastring

Adres Data URL zawartości pliku przy type=input_file. Pliki PDF mogą używać data:application/pdf;base64,....

filenamestring

Nazwa pliku przy type=input_file.

instructionsstring

Instrukcje systemowe lub deweloperskie wstawiane do kontekstu modelu.

max_output_tokensinteger

Opcjonalna maksymalna liczba tokenów wyjściowych jako dodatnia liczba całkowita. Pomiń to pole, aby użyć wartości domyślnej dostawcy dla wybranego modelu. W zależności od modelu limit może obejmować zarówno tokeny rozumowania, jak i końcowy tekst. Mały limit może uciąć odpowiedź lub wyczerpać się przed końcowym tekstem; jego zwiększenie może podnieść koszt.

streambooleanWartość domyślna: false

Czy strumieniować odpowiedź.

false: zwraca jedną kompletną odpowiedź
true: zwraca zdarzenia SSE w stylu OpenAI Responses

temperaturenumberWartość domyślna: 1.0

Temperatura próbkowania, zwykle od 0 do 2.

top_pnumberWartość domyślna: 1.0

Parametr próbkowania jądrowego, zwykle od 0 do 1.

textobject

Konfiguracja tekstu wyjściowego.

text.formatobject

Konfiguracja formatu tekstu, na przykład { "type": "text" } lub schemat JSON.

text.verbositystring

Szczegółowość wyniku, na przykład low, medium lub high. Obsługa zależy od wybranego modelu.

toolsobject[]

Definicje narzędzi. Dostępność zależy od wybranego modelu i dostępnych funkcji.

tool_choicestring | object

Zasady wyboru narzędzi.

parallel_tool_callsboolean

Czy dozwolone są równoległe wywołania narzędzi.

reasoningobject

Opcje dotyczące rozumowania.

includestring[]

Dodatkowe pola do uwzględnienia w odpowiedzi.

prompt_cache_keystring

Klucz pamięci podręcznej promptu do jej ponownego użycia.

prompt_cache_retentionstring

Zasady przechowywania pamięci podręcznej promptu. Obsługiwane wartości zależą od wybranego modelu i dostępnych funkcji.

safety_identifierstring

Stały identyfikator użytkownika końcowego dla mechanizmów bezpieczeństwa.

storeboolean

Czy stan odpowiedzi może być przechowywany.

Różnice parametrów modeli

Natywne przekazywanie Responses zgodne z OpenAI zachowuje top_p w żądaniu do dostawcy; walidacja i zachowanie próbkowania zależą od wybranego modelu i dostawcy. Kontrole z 2026-09-26 zaakceptowały top_p: 0.9 dla gpt-5.5, gpt-5.6-sol i gpt-5.6-terra. Akceptacja i przekazanie nie dowodzą wpływu na próbkowanie ani nie gwarantują obsługi innych wartości, modeli lub późniejszych żądań. Zacznij od minimalnego żądania.
Obsługa opisana na tej stronie dotyczy tylko zwykłego punktu końcowego /openai/responses. Nie oznacza, że ten sam model obsługuje /openai/responses/compact, WebSocket lub stanowe previous_response_id.
Pięć wymienionych wyżej modeli GPT nie ma obecnie zweryfikowanego kanału Compact. Żądania Compact są odrzucane przed rozliczeniem, gdy nie ma jawnie włączonego kanału. Zwykłe Responses i Responses WebSocket pozostają dostępne.

Przykłady żądań

Poniższe przykłady podają input. Kontynuacja może pominąć input, gdy podaje prawidłowe previous_response_id, a wybrany kanał obsługuje kontynuację ze stanem. Identyfikator odpowiedzi nie włącza tej funkcji w kanale bez jej obsługi. Wyniki narzędzi pozostają prawidłowymi elementami wejściowymi, w tym function_call_output.

Tekst

json

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

Parametry w stylu Codex CLI

json

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

Rozumienie obrazów

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

Plik na wejściu

Użyj file_data wraz z filename, aby przesłać zawartość PDF. file_data musi być kompletnym adresem 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"
        }
      ]
    }
  ]
}

Obraz i plik na wejściu

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

Strumieniowanie wyniku

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

Odpowiedź

Odpowiedzi bez strumieniowania mają format OpenAI Responses. Rzeczywiste pola mogą zależeć od możliwości wybranego modelu.

idstring

Unikalny identyfikator odpowiedzi.

objectstring

Typ obiektu odpowiedzi, zwykle response.

created_atinteger

Znacznik czasu utworzenia.

modelstring

Faktycznie użyty model.

outputobject[]

Lista elementów wyjściowych. Typowe elementy obejmują message, function_call i wyniki związane z narzędziami.

usageobject

Statystyki zużycia tokenów, takie jak input_tokens, output_tokens i total_tokens.

Przykład powodzenia

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

Odpowiedź strumieniowa

Przy stream=true punkt końcowy zwraca zdarzenia 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"}}

Odczytuj zdarzenia do response.completed lub zamknięcia połączenia.

Odpowiedź błędu

Zobacz kody błędów i diagnozowanie, aby poznać pełny wykaz kodów, różnice protokołów i kroki diagnostyczne.

Błędy HTTP generowane przez platformę używają poniższych płaskich pól zamiast opakowania error. Niektóre błędy dostawcy mogą zachować oryginalną strukturę; błędy w już rozpoczętym strumieniu SSE nie mają formatu tego przykładu odpowiedzi HTTP.

json

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

Uwagi

Punkt końcowy Responses używa input, a nie messages. Jeśli Twój klient wysyła tylko messages, użyj /openai/v1/chat/completions.
Wejście obrazu używa input_image; image_url musi być publicznym adresem URL http:// lub https://. Adresy Data URL Base64 nie są obsługiwane dla obrazów.
Wejście pliku używa input_file. Dla plików PDF użyj file_data wraz z filename; file_data powinno być kompletnym adresem URL data:application/pdf;base64,....
Wejście/wyjście dźwięku, narzędzia generowania obrazów, wyszukiwanie plików i inne zaawansowane możliwości zależą od wybranego modelu i dostępnych funkcji.
Pola wymienione na tej stronie tworzą obecny publiczny kontrakt żądania Responses; nie zakładaj dostępności pól niewymienionych.
/openai/responses jest zalecaną publiczną ścieżką.
/v1/responses używa tego samego publicznego kontraktu żądań i odpowiedzi.
/compat/v1/responses używa tego samego publicznego kontraktu żądań i odpowiedzi.
/openai/v1/responses używa tego samego publicznego kontraktu żądań i odpowiedzi.