الموارد · Chat API

توثيق Chat API

مرجع مؤسسي لـ /chat/completions يشمل هيكل الطلب، وأحداث البث، وسلوك التشغيل، ودلالات الأخطاء.

نقاط النهاية

GET /api/v1/chat/health

POST /api/v1/chat/completions

الهيدرز المطلوبة

Authorization: Bearer [token] أو API key authContent-Type: application/jsonX-Scope-Type: personal | workspaceX-Workspace-ID: مطلوب فقط عند scope = workspace

هيكل الطلب

json

{
  "message": "Summarize the last meeting in bullet points",
  "session_id": "sess_123",
  "stream": true,
  "attachments": [],
  "metadata": {
    "locale": "en",
    "channel": "web"
  }
}

هيكل الاستجابة

json

{
  "success": true,
  "session_id": "sess_123",
  "content": "• Discussed roadmap\n• Confirmed release scope\n• Assigned owners",
  "provider": "pulse",
  "usage": {
    "input_tokens": 324,
    "output_tokens": 118
  },
  "metadata": {
    "latency_ms": 612
  }
}

أحداث البث

response.started — بدء تنفيذ طلب المحادثة
response.delta — أجزاء نصية متدفقة من النموذج
response.tool_call — حدث استدعاء أداة (عند الحاجة)
response.usage — تحديث الاستهلاك/التوكنز
response.completed — الاستجابة النهائية المجمعة

سلوك التشغيل

التحكم في الضغط يعيد 503 عند الحمل الزائد.
قفل موزع يمنع تكرار المعالجة المتزامنة.
ذاكرة dedup تخدم الطلبات غير المتدفقة المكررة.
حفظ الجلسة يسجل رسائل المستخدم والمساعد.
التحقق يشمل body والمرفقات وسياق الوصول.

نماذج الأخطاء

400

طلب غير صالح أو حقول إلزامية ناقصة.

401

مصادقة مفقودة أو غير صحيحة.

403

تقييد نطاق/صلاحيات.

409

تعارض قفل: الطلب قيد المعالجة بالفعل.

422

فشل التحقق في الهيدرز/الطلب/السياق.

429

تم تجاوز حد المعدل.

503

ضغط نظام أو عدم توفر خدمة upstream.

أمثلة

bash

curl -X POST "/api/v1/chat/completions" \
  -H "Authorization: Bearer [token]" \
  -H "Content-Type: application/json" \
  -H "X-Scope-Type: personal" \
  -d '{
    "message":"Write a short product update",
    "session_id":"sess_123",
    "stream":false
  }'