استجابات 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.

واجهة Responses API متوافقة مع OpenAI. تستخدم نقطة النهاية هذه input بتنسيق OpenAI، وتدعم النصوص وروابط الصور العامة وإدخال ملفات 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.

تُدعم فقط روابط الصور http:// أو https:// المتاحة للعامة. لا تُدعم روابط بيانات Base64 مثل data:image/...;base64,....

detailstringالقيمة الافتراضية: auto

مستوى تفاصيل الصورة عندما تكون type=input_image.

القيم الشائعة:

auto
low
high

file_datastring

رابط بيانات محتوى الملف عندما تكون 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

معامل أخذ العينات النووية، وعادةً يكون من 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 القيمة 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 صالحًا وكانت القناة المختارة تدعم المتابعة مع حفظ الحالة. لا يفعّل معرّف الاستجابة هذه الإمكانية في قناة لا تدعمها. وتظل نتائج الأدوات عناصر إدخال صالحة، بما فيها 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 رابط بيانات كاملًا.

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، تعيد نقطة النهاية أحداثًا يرسلها الخادم عبر SSE.

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 رابطًا عامًا يبدأ بـ http:// أو https://. لا تُدعم روابط بيانات Base64 للصور.
يستخدم إدخال الملفات input_file. لملفات PDF، استخدم file_data مع filename؛ وينبغي أن يكون file_data رابطًا كاملًا بصيغة data:application/pdf;base64,....
يعتمد إدخال الصوت وإخراجه وأدوات توليد الصور والبحث في الملفات وغيرها من القدرات المتقدمة على النموذج المختار والميزات المتاحة.
تشكل الحقول المدرجة في هذه الصفحة عقد طلبات Responses العام الحالي؛ فلا تفترض توفر حقول غير مدرجة.
/openai/responses هو المسار العام الموصى به.
يتبع /v1/responses عقد الطلب والاستجابة العام نفسه.
يتبع /compat/v1/responses عقد الطلب والاستجابة العام نفسه.
يتبع /openai/v1/responses عقد الطلب والاستجابة العام نفسه.