# إكمالات المحادثة

> استدعِ نماذج المحادثة عبر نقطة نهاية إكمالات المحادثة المتوافقة مع OpenAI في بوابة تاروت للذكاء الاصطناعي

# إكمالات المحادثة

نقطة النهاية `POST /chat/completions` هي واجهة إكمالات المحادثة من OpenAI.
تعمل معها أي حزمة OpenAI أو LangChain أو Vercel AI SDK بعد ضبط العنوان الأساسي
على `https://tarout.sa/api/ai/v1` واستخدام مفتاح تاروت (`sk_tarout_...`).
يستدعي المفتاح الواحد كل نماذج المحادثة، ويختار كل طلب نموذجه عبر `model`.

## المناطق

| المنطقة | مكان المعالجة | `model` |
| --- | --- | --- |
| **عالمي** | تُعالَج خارج السعودية. | `glm`، `deepseek-v4-pro`، `kimi-k3`، `minimax-m3`، `qwen3` |
| **عالمي، المسار السريع** | تُعالَج خارج السعودية، على مسار مهيأ للاستدلال السريع. | `gpt-oss-fast`، `gpt-oss-20b-fast`، `qwen3.8-fast`، `qwen3.6-fast` |

المعرّفات الكاملة لهذه النماذج موجودة في [جداول النماذج](https://tarout.sa/docs/api#النماذج).
ويعرض `GET /models` كل نماذج المحادثة التي يمكنك استدعاؤها الآن، مع منطقة كل
نموذج في `region`.

## نقطة النهاية

```
POST https://tarout.sa/api/ai/v1/chat/completions
```

يجب أن يملك مفتاحك صلاحية **بوابة الذكاء الاصطناعي**.

## الطلب

| الحقل | النوع | الوصف |
| --- | --- | --- |
| `model` | نص | مطلوب. الاسم المختصر للنموذج أو معرّفه الكامل. |
| `messages` | مصفوفة | مطلوب. رسالة واحدة على الأقل. قيمة `content` في كل رسالة نص (أو `null`)، ولا تُقبل الصور ولا أجزاء المحتوى الأخرى. |
| `stream` | قيمة منطقية | اختياري. القيمة `true` تبث الإجابة بأحداث Server-Sent Events. |
| `stream_options` | كائن | اختياري. خيارات البث، مثل `{ "include_usage": true }`. |
| `max_tokens` | عدد صحيح | اختياري. أقصى عدد من الرموز تُولَّد. إذا لم ترسله فالحد الأقصى للإجابة 4096 رمزًا. |
| `max_completion_tokens` | عدد صحيح | اختياري. الحد نفسه باسمه الأحدث. إذا أرسلت الحقلين فيجب أن تتساوى قيمتاهما. |
| `temperature`، `top_p` | عدد | اختياري. ضوابط التوليد. |
| `frequency_penalty`، `presence_penalty` | عدد | اختياري. |
| `stop` | نص أو مصفوفة | اختياري. تسلسلات الإيقاف. |
| `seed` | عدد صحيح | اختياري. يُمرَّر إلى النموذج لإجابات أكثر قابلية للتكرار. |
| `n` | عدد صحيح | اختياري. القيمة `1` فقط: اختيار واحد لكل طلب. أرسل طلبات متوازية إن احتجت أكثر. |
| `response_format` | كائن | اختياري. `{ "type": "text" }` أو `{ "type": "json_object" }` أو `{ "type": "json_schema", "json_schema": {...} }`. يتطلب نوعا JSON نموذجًا يدعم المخرجات المنظَّمة. |
| `tools`، `tool_choice`، `parallel_tool_calls` | | اختياري. استدعاء الدوال، للنماذج التي تدعم الأدوات. |
| `functions`، `function_call` | | اختياري. الصيغة الأقدم لاستدعاء الدوال. |
| `reasoning_effort` | نص | اختياري. للنماذج التي تحدد مستويات تفكير فقط؛ وترد نماذج هذه الصفحة بالحالة `400` والرمز `UNSUPPORTED_PARAMETER` إذا أرسلته. |
| `user` | نص | اختياري. معرّف المستخدم النهائي لديك، لسجلاتك أنت. |

أي حقل غير موجود في هذا الجدول يُرد بالحالة `400` والرمز `VALIDATION_ERROR` مع
اسم الحقل. وتعرض صفحة النموذج في لوحة التحكم (**نماذج الذكاء الاصطناعي**) هل
يدعم الأدوات والمخرجات المنظَّمة، والطلب الذي يحتاج ميزة لا يملكها النموذج يُرد
بالحالة `400`.

## الاستجابة

```json
{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1761300000,
  "model": "z-ai/glm-5.3",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "مرحبًا! كيف أساعدك؟" },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 12, "completion_tokens": 9, "total_tokens": 21 }
}
```

مع `"stream": true` تصل الإجابة على شكل أحداث `data:`، كل حدث منها
`chat.completion.chunk`، وتنتهي بـ`data: [DONE]`. وإذا فشل البث بعد بدئه ينتهي
بحدث `data:` واحد يحمل كائن `error`، ثم `data: [DONE]`.

## الحدود

- الرسائل النصية فقط.
- اختيار واحد لكل طلب (`n` تساوي `1`).
- دون `max_tokens` تُحدّ الإجابة بـ4096 رمزًا.
- افتراضيًا يمكن لكل مفتاح إرسال 60 طلبًا و100,000 رمز في الدقيقة، و1,000,000
  رمز في اليوم. وبعد تجاوز أي حد تصلك الحالة `429` مع `Retry-After`.

## التسعير

تُحتسب المحادثة لكل رمز، ولرموز الإدخال والإخراج سعران منفصلان، بالريال
السعودي من الرصيد المدفوع مسبقًا لمنظمتك. والطلبات الفاشلة لا تُحتسب. راجع
الأسعار الحالية لكل نموذج في لوحة التحكم (**نماذج الذكاء الاصطناعي**) أو عبر
`tarout ai models`، ويعرض `GET /models` النماذج التي يمكنك استدعاؤها الآن.
ويمكن أيضًا تعيين حد إنفاق شهري بالريال لكل مفتاح.

## أمثلة

```sh
curl https://tarout.sa/api/ai/v1/chat/completions \
  -H "Authorization: Bearer $TAROUT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm",
    "messages": [{ "role": "user", "content": "اكتب جملة واحدة عن الرياض." }]
  }'
```

باستخدام حزمة تاروت (`npm install @tarout/ai`):

```ts
import Tarout from "@tarout/ai";

const client = new Tarout(); // تقرأ TAROUT_API_KEY

const res = await client.chat.completions.create({
  model: "gpt-oss-fast",
  messages: [{ role: "user", content: "اكتب جملة واحدة عن الرياض." }],
});

console.log(res.choices[0]?.message.content);
```

باستخدام حزمة `openai` الرسمية للغة Python (`pip install openai`):

```python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://tarout.sa/api/ai/v1",
    api_key=os.environ["TAROUT_API_KEY"],
)

stream = client.chat.completions.create(
    model="glm",
    messages=[{"role": "user", "content": "اكتب جملة واحدة عن الرياض."}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")
```

## الأخطاء

تستخدم الأخطاء صيغة OpenAI: `{"error": {"message", "type", "code"}}`، ويحمل
`type` و`code` القيمة نفسها. القائمة الكاملة في
[نظرة عامة على API](https://tarout.sa/docs/api#الأخطاء).

| الحالة | `code` | المعنى |
| --- | --- | --- |
| 400 | `VALIDATION_ERROR` | جسم الطلب غير صالح، أو فيه حقل لا تقبله نقطة النهاية. |
| 400 | `UNSUPPORTED_PARAMETER` | النموذج لا يقبل هذا الحقل (`response_format` أو `reasoning_effort` أو `n` أكبر من 1). |
| 401 | `AUTHENTICATION_ERROR` | المفتاح مفقود أو غير صالح. |
| 402 | `PAYMENT_REQUIRED`، `BUDGET_EXCEEDED` | الرصيد أو حد الإنفاق الشهري للمفتاح لا يغطي الطلب. |
| 403 | `KEY_SCOPE_FORBIDDEN` | لا يملك المفتاح صلاحية بوابة الذكاء الاصطناعي. |
| 404 | `MODEL_NOT_FOUND`، `MODEL_UNAVAILABLE` | نموذج غير معروف أو مُزال، أو نموذج لا يمكن استدعاؤه الآن. |
| 429 | `RATE_LIMIT_EXCEEDED` | طلبات أو رموز كثيرة جدًا. انتظر عدد الثواني في `Retry-After`. |
| 502، 503 | `PROVIDER_ERROR` | النموذج غير متاح مؤقتًا. أعد المحاولة؛ الطلبات الفاشلة لا تُحتسب. |

## سطر الأوامر وMCP

```sh
tarout ai models                                          # كتالوج المحادثة وأسعاره
tarout ai keys create --name production --monthly-cap 50  # مفتاح بحد إنفاق شهري 50 ريالًا
```

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

---

## Every Tarout agent guide

- [Start Here (Agents)](https://tarout.sa/docs/for-ai/start.md)
- [Overview](https://tarout.sa/docs/for-ai.md)
- [Deploying an app](https://tarout.sa/docs/for-ai/deploy.md)
- [Databases](https://tarout.sa/docs/for-ai/database.md)
- [Object storage](https://tarout.sa/docs/for-ai/storage.md)
- [Custom domains](https://tarout.sa/docs/for-ai/domains.md)
- [Plans and upgrades](https://tarout.sa/docs/for-ai/billing.md)
- [Troubleshooting](https://tarout.sa/docs/for-ai/troubleshoot.md)
- [Agent Onboarding](https://tarout.sa/docs/for-ai/onboarding.md)
- [CLI Reference](https://tarout.sa/docs/for-ai/cli-reference.md)
- [CLI JSON Schema](https://tarout.sa/docs/for-ai/cli-json-schema.md)

Whole corpus in one file: https://tarout.sa/llms-full.txt · index: https://tarout.sa/llms.txt
Any docs page is raw markdown at the same URL + `.md`. Short link to the entry point: https://tarout.sa/deploy.md