واجهة Chat Completions المشتركة | وثائق API

# Common Chat Completions

Unified chat API for switching text models through the `model` parameter. The request format is compatible with OpenAI Chat Completions.

POST https://api.apihop.ai/v1/chat-completions

Unified chat API for switching text models through the `model` parameter. The request format is compatible with OpenAI Chat Completions.

Claude Sonnet 4.6 (`claude-sonnet-4-6`) is supported by the upstream supplier but is not currently published on API Hop. It is not an active integration default. Before calling any model, confirm access with your own `GET https://api.apihop.ai/v1/models` response.

This endpoint returns one complete JSON response by default. Set `stream: true` explicitly when you need SSE streaming.

```text
POST https://api.apihop.ai/v1/chat-completions
```

## Authentication

All requests require Bearer Token authentication.

```http
Authorization: Bearer YOUR_API_KEY
```

If authentication fails, check:

- Whether the API Key is correct
- Whether the key is valid for this API Base URL
- Whether the request header is spelled correctly
- Whether a proxy rewrites the authorization header

## Body

### `model` (string, required, Default: gpt-5.4)

Documented text model IDs (confirm access with `GET https://api.apihop.ai/v1/models`):

- OpenAI: `gpt-5.4`, `gpt-5.5`, `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-6-astra`
- Anthropic: `claude-fable-5`, `claude-fable-5-1`, `claude-opus-4-6`, `claude-opus-4-7`, `claude-opus-4-8`, `claude-opus-5`, `claude-opus-5-5`, `claude-sonnet-5`, `claude-sonnet-5-5`
- DeepSeek: `deepseek-v4-flash`, `deepseek-v4-pro`, `deepseek-v4.1-flash`

(V4.1 Flash is a distinct model ID, available only after deployment and enablement; check `GET https://api.apihop.ai/v1/models`).

- Gemini: `gemini-3.6-flash`, `gemini-3.7-flash`, `gemini-3.8-flash`, `gemini-3.5-flash-lite`, `gemini-4-argon` (after deployment and enablement)
- Kimi: `kimi-k3`
- MiniMax: `minimax-m3`

See the [Model Catalog](https://apihop.ai/en/docs/api-reference/models) for the complete list and the models visible to the current API Key. Use your own `GET https://api.apihop.ai/v1/models` response as the current source of availability. See the [DeepSeek](https://apihop.ai/en/docs/api-reference/DeepSeek/models), [Gemini](https://apihop.ai/en/docs/api-reference/Gemini/models), [Kimi](https://apihop.ai/en/docs/api-reference/Kimi/models), and [MiniMax](https://apihop.ai/en/docs/api-reference/MiniMax/models) guides for family-specific selection notes and examples.

### `messages` (object[], required)

Chat messages. Each message should include:

- `role`: `system`, `user`, or `assistant`
- `content`: message content

Example:

```json
  [
    {"role": "system", "content": "You are a helpful Python tutor."},
    {"role": "user", "content": "How should I learn programming?"}
  ]
```

**Model-specific sampling limits:** `gpt-6-astra` does not accept legacy `temperature`, `top_p`, or `top_logprobs`; omit those fields even when an older client includes them. API Hop's GPT-6 Astra Playground also hides the legacy sampling and penalty controls. `claude-sonnet-5` rejected `top_p` in a documented integration recheck, so omit it for that model as well. Passing an optional field through a proxy does not establish that the selected upstream model supports it.

### `temperature` (number, Default: 1.0)

Sampling temperature. OpenAI-compatible clients commonly use `0` through `2`, but the selected model makes the final validation decision.

### `max_tokens` (integer)

Optional maximum output tokens, as a positive integer. Omit this field to use the upstream default for the selected model; defaults and maximum limits vary by model and upstream configuration.

Depending on the model, the budget may include reasoning tokens as well as final text. A small budget can cause `finish_reason: "length"`, truncate the answer, or be exhausted before final text. Increasing it may increase cost.

### `max_completion_tokens` (integer)

Optional compatibility alternative to `max_tokens`, with the same budget considerations. A model may accept only one of these fields, so start with a minimal body when switching models. Omit both to use the upstream default.

### `stream` (boolean, Default: false)

Whether to stream the response.

- `true`: return Server-Sent Events
- `false`: return one complete response

### `top_p` (number, Default: 1.0)

Nucleus sampling parameter. OpenAI-compatible clients commonly use `0` through `1`; the selected model performs final validation.

### `frequency_penalty` (number, Default: 0)

Frequency penalty. OpenAI-compatible clients commonly use `-2.0` through `2.0`; the selected model performs final validation.

### `presence_penalty` (number, Default: 0)

Presence penalty. OpenAI-compatible clients commonly use `-2.0` through `2.0`; the selected model performs final validation.

### `stop` (string | array)

A stop sequence or array of stop sequences. The selected model determines the accepted count and behavior.

### `n` (integer, Default: 1)

Number of responses to generate. Use a number such as `1`, not a quoted string.

## Model Parameter Differences

Current text models support minimal streaming and non-streaming Chat requests, but optional parameter acceptance and effects vary by the selected model and its compatibility implementation.

The latest recheck on 2026-09-26 accepted `claude-fable-5` with `temperature: 0` and returned text. The same recheck rejected `claude-sonnet-5` with `top_p: 0.9` with HTTP `400` and `top_p is deprecated`. Omit `top_p` for that model. Acceptance establishes neither an effect on sampling nor a guarantee for other models or later requests; do not assume that all sampling parameters are supported.

The OpenAI checks on 2026-09-26 accepted `stop` for `gpt-5.6-sol` and `gpt-5.6-terra`. Parameter acceptance can change with the upstream and does not prove that a stop sequence is effective.

Native OpenAI-compatible Chat forwarding preserves `top_p` and `stop` in the upstream request. A route that converts Chat to Responses preserves `top_p` but does not forward `stop`. Forwarding a field does not establish upstream support or its effect; neither field has a platform-wide guarantee across routes.

Start with a minimal request when switching models, then verify sampling, stop sequences, and advanced tool parameters separately. For stop sequences, inspect the actual text and stop reason, not only the HTTP status. HTTP 200 does not establish a sampling effect. Output budgets must cover both the model's thinking and its final text.

## Request Example

```json
{
  "model": "gpt-5.4",
  "messages": [
    {
      "role": "user",
      "content": "Hello, introduce yourself briefly."
    }
  ],
  "stream": false
}
```

## Response

### `id` (string)

Unique response identifier.

### `object` (string)

Object type, usually `chat.completion` or `chat.completion.chunk` for streaming.

### `created` (integer)

Unix creation timestamp.

### `model` (string)

Model identifier returned in the response.

### `choices` (array)

Generated choices, including message content, index, and finish reason.

### `usage` (object)

Token usage statistics.

### Success Example

```json
{
  "id": "chatcmpl-9876543210",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "gpt-5.4",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "I am an AI assistant that can help with writing, coding, and analysis."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 42,
    "total_tokens": 70
  }
}
```

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

Chat Completions HTTP errors use a flat JSON body, including upstream HTTP errors returned before an SSE stream starts. For example, HTTP `402` returns:

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

- `code`: numeric platform error code, separate from the HTTP status and not a string
- `message`: human-readable error description
- `type`: `api_error`
- `requestId`: optional request identifier for troubleshooting

| HTTP status | `code` | Meaning |
| --- | --- | --- |
| 400 | 10000 | Invalid request |
| 401 | 20000 | Missing or invalid authentication |
| 402 | 40000 | Insufficient credit |
| 403 | 20001 | Access denied or model unavailable to this key |
| 404 | 30000 | Model or resource not found |
| 409 | 30001 | Request conflict |
| 422 | 10001 | Validation error |
| 429 | 40001 | Rate limit exceeded |
| 500 | 50003 | Internal error |
| 502 | 50000 | Upstream provider error |
| 503 | 50001 | Service unavailable |
| 504 | 50002 | Gateway timeout |

Check the HTTP status first to determine whether the request succeeded, then compare the numeric `code` for application-specific handling. Do not compare `code` with strings such as `"400"`, assume it equals the HTTP status, or parse `message` as a stable error identifier. Missing or incorrectly typed `messages` are rejected with HTTP `400` and `code: 10000` before provider invocation.

This error format applies to Chat Completions HTTP responses, not errors within an already-started SSE stream or other API protocols. Model Catalog and native protocol endpoints have their own documented error formats.

واجهة محادثة موحدة لتبديل النماذج النصية عبر المعامل model. يتوافق تنسيق الطلب مع OpenAI Chat Completions.

يدعم المزود Claude Sonnet 4.6 (claude-sonnet-4-6)، لكنه غير منشور حاليا على API Hop. وليس خيار تكامل افتراضيا نشطا. قبل استدعاء أي نموذج، أكد الوصول من خلال استجابة GET https://api.apihop.ai/v1/models الخاصة بك.

تعيد نقطة النهاية هذه استجابة JSON كاملة واحدة افتراضيا. اضبط stream: true صراحة عندما تحتاج إلى بث SSE.

text

POST https://api.apihop.ai/v1/chat-completions

المصادقة

تتطلب جميع الطلبات المصادقة برمز Bearer.

http

Authorization: Bearer YOUR_API_KEY

إذا فشلت المصادقة، فتحقق مما يلي:

صحة مفتاح API
صلاحية المفتاح لعنوان API Base URL هذا
صحة كتابة ترويسة الطلب
ما إذا كان وكيل يعيد كتابة ترويسة المصادقة

جسم الطلب

modelstringمطلوبالقيمة الافتراضية: gpt-5.4

معرفات النماذج النصية الموثقة (أكد الوصول عبر GET https://api.apihop.ai/v1/models):

OpenAI: gpt-5.4 وgpt-5.5 وgpt-5.6-sol وgpt-5.6-terra وgpt-6-astra
Anthropic: claude-fable-5 وclaude-fable-5-1 وclaude-opus-4-6 وclaude-opus-4-7 وclaude-opus-4-8 وclaude-opus-5 وclaude-opus-5-5 وclaude-sonnet-5 وclaude-sonnet-5-5
DeepSeek: deepseek-v4-flash وdeepseek-v4-pro وdeepseek-v4.1-flash (معرف V4.1 Flash مستقل، ولا يتاح إلا بعد النشر والتفعيل؛ تحقق عبر GET https://api.apihop.ai/v1/models).
Gemini: gemini-3.6-flash وgemini-3.7-flash وgemini-3.8-flash وgemini-3.5-flash-lite وgemini-4-argon (بعد النشر والتفعيل)
نموذج Kimi: kimi-k3
نموذج MiniMax: minimax-m3

راجع كتالوج النماذج للقائمة الكاملة والنماذج الظاهرة لمفتاح API الحالي. استخدم استجابة GET https://api.apihop.ai/v1/models الخاصة بك مرجعا حاليا للإتاحة. راجع أدلة DeepSeek وGemini وKimi وMiniMax لملاحظات الاختيار والأمثلة الخاصة بكل عائلة.

messagesobject[]مطلوب

رسائل المحادثة. ينبغي أن تتضمن كل رسالة:

role: ‏system أو user أو assistant
content: محتوى الرسالة

مثال:

json

  [
    {"role": "system", "content": "You are a helpful Python tutor."},
    {"role": "user", "content": "How should I learn programming?"}
  ]

حدود أخذ العينات الخاصة بالنماذج: لا يقبل gpt-6-astra المعاملات القديمة temperature أو top_p أو top_logprobs؛ احذف هذه الحقول حتى عندما يدرجها عميل أقدم. تخفي ساحة تجربة GPT-6 Astra في API Hop أيضا ضوابط أخذ العينات والعقوبات القديمة. رفض claude-sonnet-5 المعامل top_p في إعادة تحقق موثقة للتكامل، لذا احذفه لهذا النموذج أيضا. تمرير حقل اختياري عبر وكيل لا يثبت دعم نموذج المزود المختار له.

temperaturenumberالقيمة الافتراضية: 1.0

درجة حرارة أخذ العينات. يستخدم العملاء المتوافقون مع OpenAI عادة القيم من 0 إلى 2، لكن النموذج المختار يتخذ قرار التحقق النهائي.

max_tokensinteger

الحد الأقصى الاختياري لرموز الإخراج كعدد صحيح موجب. احذف هذا الحقل لاستخدام القيمة الافتراضية لدى المزود للنموذج المختار؛ وتختلف القيم الافتراضية والحدود القصوى بحسب النموذج وإعداد المزود.

بحسب النموذج، قد تشمل الميزانية رموز الاستدلال والنص النهائي معا. قد تتسبب الميزانية الصغيرة في finish_reason: "length" أو اقتطاع الإجابة أو نفادها قبل النص النهائي. وقد تزيد زيادتها التكلفة.

max_completion_tokensinteger

بديل توافق اختياري لـmax_tokens، مع اعتبارات الميزانية نفسها. قد يقبل النموذج أحد هذين الحقلين فقط، لذا ابدأ بجسم بسيط عند تبديل النماذج. احذف كليهما لاستخدام القيمة الافتراضية لدى المزود.

streambooleanالقيمة الافتراضية: false

ما إذا كانت الاستجابة ستبث.

true: إرجاع أحداث يرسلها الخادم
false: إرجاع استجابة كاملة واحدة

top_pnumberالقيمة الافتراضية: 1.0

معامل أخذ العينات النووية. يستخدم العملاء المتوافقون مع OpenAI عادة القيم من 0 إلى 1؛ وينفذ النموذج المختار التحقق النهائي.

frequency_penaltynumberالقيمة الافتراضية: 0

عقوبة التكرار. يستخدم العملاء المتوافقون مع OpenAI عادة القيم من -2.0 إلى 2.0؛ وينفذ النموذج المختار التحقق النهائي.

presence_penaltynumberالقيمة الافتراضية: 0

عقوبة الوجود. يستخدم العملاء المتوافقون مع OpenAI عادة القيم من -2.0 إلى 2.0؛ وينفذ النموذج المختار التحقق النهائي.

stopstring | array

تسلسل إيقاف أو مصفوفة تسلسلات إيقاف. يحدد النموذج المختار العدد المقبول والسلوك.

nintegerالقيمة الافتراضية: 1

عدد الاستجابات المراد توليدها. استخدم رقما مثل 1، وليس سلسلة بين علامتي اقتباس.

اختلافات معاملات النماذج

تدعم النماذج النصية الحالية طلبات Chat الأساسية بالبث ودونه، لكن قبول المعاملات الاختيارية وتأثيرها يختلف بحسب النموذج المختار وتنفيذ التوافق لديه.

قبلت أحدث إعادة تحقق في 2026-09-26 النموذج claude-fable-5 مع temperature: 0 وأعادت نصا. ورفضت إعادة التحقق نفسها claude-sonnet-5 مع top_p: 0.9 بالحالة HTTP 400 والرسالة top_p is deprecated. احذف top_p لهذا النموذج. لا يثبت القبول تأثيرا في أخذ العينات ولا ضمانا للنماذج الأخرى أو الطلبات اللاحقة؛ فلا تفترض دعم جميع معاملات أخذ العينات.

قبلت فحوص OpenAI في 2026-09-26 المعامل stop لكل من gpt-5.6-sol وgpt-5.6-terra. قد يتغير قبول المعاملات مع المزود ولا يثبت فاعلية تسلسل الإيقاف.

يحافظ التمرير الأصلي لـChat المتوافق مع OpenAI على top_p وstop في طلب المزود. ويحافظ المسار الذي يحول Chat إلى Responses على top_p لكنه لا يمرر stop. تمرير الحقل لا يثبت دعم المزود أو تأثيره؛ ولا يتمتع أي من الحقلين بضمان على مستوى المنصة عبر المسارات.

ابدأ بطلب بسيط عند تبديل النماذج، ثم تحقق من أخذ العينات وتسلسلات الإيقاف ومعاملات الأدوات المتقدمة بصورة مستقلة. لتسلسلات الإيقاف، افحص النص الفعلي وسبب التوقف، وليس حالة HTTP فقط. لا تثبت HTTP 200 تأثيرا في أخذ العينات. يجب أن تغطي ميزانيات الإخراج تفكير النموذج ونصه النهائي معا.

مثال طلب

json

{
  "model": "gpt-5.4",
  "messages": [
    {
      "role": "user",
      "content": "Hello, introduce yourself briefly."
    }
  ],
  "stream": false
}

الاستجابة

idstring

معرف فريد للاستجابة.

objectstring

نوع الكائن، وعادة chat.completion أو chat.completion.chunk للبث.

createdinteger

طابع وقت الإنشاء بصيغة Unix.

modelstring

معرف النموذج المعاد في الاستجابة.

choicesarray

الخيارات المولدة، بما فيها محتوى الرسالة والفهرس وسبب الانتهاء.

usageobject

إحصاءات استخدام الرموز.

مثال نجاح

json

{
  "id": "chatcmpl-9876543210",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "gpt-5.4",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "I am an AI assistant that can help with writing, coding, and analysis."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 42,
    "total_tokens": 70
  }
}

استجابة الخطأ

راجع رموز الأخطاء وتشخيصها للمرجع الكامل للرموز واختلافات البروتوكولات وخطوات التشخيص.

تستخدم أخطاء HTTP في Chat Completions جسم JSON مسطحا، بما فيه أخطاء HTTP من المزود المعادة قبل بدء بث SSE. مثلا، تعيد HTTP 402:

json

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

code: رمز خطأ رقمي للمنصة، مستقل عن حالة HTTP وليس سلسلة نصية
message: وصف خطأ مقروء للبشر
type: القيمة api_error
requestId: معرف طلب اختياري للتشخيص

حالة HTTP	`code`	المعنى
400	10000	طلب غير صحيح
401	20000	مصادقة مفقودة أو غير صحيحة
402	40000	رصيد غير كاف
403	20001	الوصول مرفوض أو النموذج غير متاح لهذا المفتاح
404	30000	النموذج أو المورد غير موجود
409	30001	تعارض الطلب
422	10001	خطأ تحقق
429	40001	تجاوز حد المعدل
500	50003	خطأ داخلي
502	50000	خطأ المزود
503	50001	الخدمة غير متاحة
504	50002	انتهاء مهلة البوابة

افحص حالة HTTP أولا لتحديد نجاح الطلب، ثم قارن code الرقمي للمعالجة الخاصة بالتطبيق. لا تقارن code بسلاسل مثل "400"، ولا تفترض مساواته لحالة HTTP، ولا تحلل message كمعرف خطأ ثابت. ترفض messages المفقودة أو ذات النوع الخاطئ بالحالة HTTP 400 وcode: 10000 قبل استدعاء المزود.

ينطبق تنسيق الخطأ هذا على استجابات HTTP في Chat Completions، وليس الأخطاء داخل بث SSE بدأ بالفعل أو بروتوكولات API الأخرى. لكتالوج النماذج ونقاط نهاية البروتوكولات الأصلية تنسيقات أخطاء موثقة خاصة بها.