استخدم Rivya Chat API للدورات غير المتدفقة أو SSE، والجلسات المنشأة عبر API، ومرفقات الصور file_id، وتسوية الرصيد بناء على token.

استخدم POST /api/v1/chat/completions للحصول على استجابة دردشة كاملة غير متدفقة، أو POST /api/v1/chat/completions/stream للحصول على Server-Sent Events.

يعتمد Chat API على الجلسات. احذف session_id لبدء جلسة دردشة API جديدة. مرر session_id العائد لمتابعة الجلسة نفسها التي أنشئت عبر API.

النطاق الحالي

يدعم Chat API v1:

استجابات مساعد غير متدفقة
بث SSE باستخدام text/event-stream
جلسات دردشة منشأة عبر API
حجز رصيد الحساب والتسوية النهائية بناء على token
البحث في الويب، وreasoning effort، وthought mode اختياريا عندما يدعمها النموذج المحدد
مرفقات صور عبر قيم file_id من Files API

لا يدعم Chat API v1:

سجل messages خام يقدمه المستخدم
متابعة جلسات دردشة Studio-only
عناوين URL عشوائية لمرفقات خارجية
أحداث Chat webhook

النطاقات المطلوبة

استخدم مفتاح API يتضمن:

chat:create
chat:read

تتضمن المفاتيح الجديدة التي تنشأ في Settings كلا النطاقين افتراضيا. قد تحتاج المفاتيح الأقدم إلى إعادة إنشائها قبل استدعاء Chat API.

إنشاء Chat Completion

curl https://rivya.ai/api/v1/chat/completions \
  -H "Authorization: Bearer rvya_sk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: chat-turn-001" \
  -d '{
    "model": "gpt-5-2-chat",
    "message": "Write a concise launch plan for a new product image campaign",
    "client_request_id": "chat-001"
  }'

الاستجابة:

{
  "id": "chatcmpl_...",
  "object": "chat.completion",
  "session_id": "session_id",
  "model": "gpt-5-2-chat",
  "created_at": "2026-05-11T00:00:00.000Z",
  "message": {
    "id": "assistant_message_id",
    "role": "assistant",
    "content": "..."
  },
  "usage": {
    "input_tokens": 1200,
    "output_tokens": 320,
    "total_tokens": 1520
  },
  "credits": {
    "reserved": 3,
    "final": 2
  }
}

بث Chat Completion

استخدم POST /api/v1/chat/completions/stream عندما يريد خادمك قراءة دلتا المساعد فور وصولها:

curl -N https://rivya.ai/api/v1/chat/completions/stream \
  -H "Authorization: Bearer rvya_sk_..." \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -H "Idempotency-Key: chat-stream-001" \
  -d '{
    "model": "gpt-5-2-chat",
    "message": "Write a concise launch plan for a new product image campaign",
    "client_request_id": "chat-stream-001"
  }'

تستخدم الاستجابات المتدفقة Content-Type: text/event-stream; charset=utf-8.

الأحداث:

Event	المعنى
`session.created`	اجتازت فحوصات مفتاح API، والنموذج، والجلسة، والمرفقات، وحد معدل الطلبات، وحجز الرصيد.
`message.delta`	دلتا عرض لرسالة المساعد. ليست رسالة ملتزمة بعد.
`message.completed`	تم تثبيت رسالة المساعد في الجلسة المنشأة عبر API.
`usage.completed`	تمت تسوية استخدام token والرصيد النهائي.
`heartbeat`	حدث keepalive أثناء فترات التوقف الطويلة.
`error`	غلاف خطأ Public API لفشل حدث بعد بدء البث.
`done`	اكتمل البث بنجاح.

مثال بث:

event: session.created
data: {"request_id":"req_...","session_id":"session_id","model":"gpt-5-2-chat"}

event: message.delta
data: {"request_id":"req_...","session_id":"session_id","delta":"Draft ","index":0}

event: message.completed
data: {"request_id":"req_...","session_id":"session_id","message":{"id":"assistant_message_id","role":"assistant","content":"Draft ...","created_at":"2026-05-11T00:00:00.000Z"}}

event: usage.completed
data: {"request_id":"req_...","session_id":"session_id","usage":{"input_tokens":1200,"output_tokens":320,"total_tokens":1520},"credits":{"reserved":3,"final":2}}

event: done
data: {"request_id":"req_...","ok":true}

إذا حدث خطأ بعد أول حدث SSE، يرسل البث event: error ثم يغلق:

event: error
data: {"error":{"code":"internal_error","message":"The request could not be completed.","requestId":"req_..."}}

إذا انقطع العميل قبل الاكتمال، توقف Rivya بث التوليد الجاري عندما يكون ذلك ممكنا. لا تحفظ الدلتا الجزئية كرسالة مساعد نهائية. إذا كان الخادم قد ثبت message.completed بالفعل، فيمكن قراءة النتيجة النهائية لاحقا باستخدام GET /api/v1/chat/sessions/{sessionId}.

متابعة جلسة

استخدم session_id العائد:

curl https://rivya.ai/api/v1/chat/completions \
  -H "Authorization: Bearer rvya_sk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: chat-turn-002" \
  -d '{
    "model": "gpt-5-2-chat",
    "session_id": "session_id",
    "message": "Now turn that into a 5-step execution checklist."
  }'

يجب أن تنتمي الجلسة إلى حساب Rivya نفسه، وأن تكون قد أنشئت بواسطة Public API. لا يعيد Chat API جلسات دردشة Studio-only ولا يتابعها.

مرفقات الصور

تستخدم مرفقات Chat سجلات Files API، لا عناوين URL خارجية.

ارفع صورة باستخدام POST /api/v1/files.
استخدم id العائد كقيمة attachments[].file_id.

{
  "model": "gpt-5-2-chat",
  "message": "Review this product photo and suggest a cleaner editorial direction.",
  "attachments": [
    {
      "file_id": "file_..."
    }
  ]
}

يجب أن ينتمي الملف إلى الحساب نفسه، وأن تكون لديه kind: "image"، وأن يكون متاحا. تعيد النماذج التي لا تدعم مرفقات الصور chat_attachment_not_supported.

عناصر التحكم الاختيارية

{
  "model": "gpt-5-2-chat",
  "message": "Compare three launch options.",
  "enable_web_search": false,
  "reasoning_effort": "default",
  "thought_mode": "default"
}

يختلف دعم عناصر التحكم بحسب النموذج. اقرأ /api/v1/models وتحقق من chat_capabilities قبل إظهار عناصر التحكم في واجهتك.

سرد الجلسات

استخدم GET /api/v1/chat/sessions مع مفتاح يتضمن chat:read.

curl https://rivya.ai/api/v1/chat/sessions \
  -H "Authorization: Bearer rvya_sk_..."

يعيد هذا جلسات منشأة عبر API فقط:

{
  "object": "list",
  "data": [
    {
      "id": "session_id",
      "object": "chat.session",
      "model": "gpt-5-2-chat",
      "tool_slug": null,
      "title": "Write a concise launch plan...",
      "controls": {
        "enable_web_search": false,
        "reasoning_effort": null,
        "thought_mode": null
      },
      "created_at": "2026-05-11T00:00:00.000Z",
      "updated_at": "2026-05-11T00:00:00.000Z",
      "last_message_at": "2026-05-11T00:00:00.000Z"
    }
  ]
}

جلب جلسة واحدة

استخدم GET /api/v1/chat/sessions/{sessionId} لقراءة جلسة واحدة منشأة عبر API ورسائلها المثبتة.

curl https://rivya.ai/api/v1/chat/sessions/session_id \
  -H "Authorization: Bearer rvya_sk_..."

تتضمن الاستجابة رسائل المستخدم والمساعد المثبتة. ولا تكشف حقول المزوّد الداخلية.

Idempotency

استخدم Idempotency-Key لكل طلب إنتاج من نوع POST /api/v1/chat/completions وPOST /api/v1/chat/completions/stream.

إذا استخدمت إعادة المحاولة المفتاح نفسه والجسم نفسه، يمكن لـ Rivya إعادة الاستجابة المخزنة من دون إنشاء رسالة أخرى أو استهلاك الرصيد مرة أخرى. إذا أعيد استخدام المفتاح نفسه مع إدخال مختلف، يعيد API الخطأ idempotency_conflict.

في إعادة محاولات البث، لا تعيد Rivya تشغيل دلتا token التاريخية. تعيد إعادة تشغيل طلب مكتمل تسلسلا أدنى من SSE يتضمن session.created، وmessage.completed، وusage.completed، وdone.

الأخطاء الشائعة

Code	المعنى
`chat_model_not_supported`	النموذج المحدد غير متاح لـ Chat API.
`chat_session_conflict`	لا يمكن استخدام الجلسة لهذا الطلب.
`chat_attachment_not_supported`	المرفق مفقود، أو لا يملكه الحساب، أو ليس صورة، أو لا يدعمه النموذج.
`insufficient_credits`	لا يملك الحساب رصيدا كافيا لهذه الدورة.
`idempotency_conflict`	أعيد استخدام مفتاح idempotency مع إدخال مختلف.

Chat API