واجهة API للمحادثة

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

تعتمد واجهة API للمحادثة على الجلسات. احذف session_id لبدء جلسة محادثة جديدة عبر API، ثم مرر session_id المعاد لمتابعة الجلسة نفسها.

توثق هذه الصفحة عقد API العام المنفذ بالإصدار v1. ويظل الوصول وقت التشغيل معتمدا على تفعيل API العام للنشر، وامتلاك الحساب مفتاح API نشطا، وإبلاغ النموذج المختار عن حالة API متاحة. تحقق من قائمة النماذج الحالية قبل إرسال طلب إنتاج.

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

تدعم واجهة API للمحادثة في الإصدار v1 ما يلي:

• استجابات مساعد غير متدفقة

• بث SSE باستخدام text/event-stream

• جلسات دردشة منشأة عبر API

• حجز رصيد الحساب والتسوية النهائية بناء على عدد الرموز

• البحث في الويب، ومستوى الاستدلال، ووضع التفكير اختياريا عندما يدعمها النموذج المحدد

• مرفقات صور عبر قيم file_id من واجهة API للملفات

لا تدعم واجهة API للمحادثة في الإصدار v1 ما يلي:

• سجل messages خام يقدمه المستخدم

• متابعة جلسات دردشة منشأة داخل Studio فقط

• عناوين URL عشوائية لمرفقات خارجية

• أحداث Webhook الخاصة بالمحادثة

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

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

chat:create
chat:read

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

إنشاء استجابة محادثة

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": "claude-sonnet-5-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": "claude-sonnet-5-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
  }
}

بث استجابة المحادثة

استخدم 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": "claude-sonnet-5-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
data: {"request_id":"req_...","session_id":"session_id","model":"claude-sonnet-5-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": "claude-sonnet-5-chat",
    "session_id": "session_id",
    "message": "Now turn that into a 5-step execution checklist."
  }'

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

مرفقات الصور

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

1. ارفع صورة باستخدام POST /api/v1/files.

2. استخدم id العائد كقيمة attachments[].file_id.

{
  "model": "<image-capable-chat-model-id>",
  "message": "Review this product photo and suggest a cleaner editorial direction.",
  "attachments": [
    {
      "file_id": "file_..."
    }
  ]
}

يجب أن ينتمي الملف إلى الحساب نفسه، وأن يحمل kind: "image"، وأن يكون متاحا. استبدل العنصر النائب بنموذج محادثة متاح حاليا يذكر في مدخله ضمن /api/v1/models دعما لمرفقات الصور في chat_capabilities. نموذج claude-sonnet-5-chat هو مثال نصي فقط مستخدم في بقية الصفحة، ولا يجوز استخدامه لطلب المرفقات هذا. تعيد النماذج التي لا تدعم مرفقات الصور الخطأ chat_attachment_not_supported.

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

{
  "model": "claude-sonnet-5-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": "claude-sonnet-5-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-Key لكل طلب إنتاج من نوع POST /api/v1/chat/completions وPOST /api/v1/chat/completions/stream.

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

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

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

صفحات ذات صلة

• نماذج API

• واجهة API للملفات

• رصيد API

• أخطاء API وحدودها

• OpenAPI وعقد المخطط