Chat API

ایک مکمل غیر مسلسل جواب کے لیے POST /api/v1/chat/completions یا سرور سے بھیجے جانے والے مسلسل واقعات کے لیے POST /api/v1/chat/completions/stream استعمال کریں۔

Chat API نشست پر مبنی ہے۔ نئی API گفتگو شروع کرنے کے لیے session_id نہ بھیجیں۔ API سے بنی اسی نشست کو جاری رکھنے کے لیے جواب میں ملنے والا session_id بھیجیں۔

یہ صفحہ نافذ شدہ Public API v1 معاہدہ بیان کرتا ہے۔ عملی رسائی کے لیے متعلقہ تنصیب میں Public API فعال، اکاؤنٹ میں فعال API کلید اور منتخب ماڈل کی API حالت دستیاب ہونا ضروری ہے۔ پیداواری درخواست سے پہلے براہِ راست ماڈل فہرست دیکھیں۔

موجودہ دائرہ

Chat API v1 ان چیزوں کی معاونت کرتا ہے:

• معاون کے غیر مسلسل جوابات

• text/event-stream کے ساتھ SSE ترسیل

• API سے بنی گفتگو کی نشستیں

• اکاؤنٹ کے کریڈٹس کی ابتدائی تخصیص اور رمزی استعمال کے مطابق حتمی تصفیہ

• منتخب ماڈل کی معاونت ہونے پر اختیاری ویب تلاش، استدلال کی سطح اور اندرونی غور کا طریقہ

• Files API کی file_id قدروں سے تصویری منسلکات

Chat API v1 ان چیزوں کی معاونت نہیں کرتا:

• صارف کی فراہم کردہ خام messages تاریخ

• صرف Studio میں بنی گفتگو کی نشست جاری رکھنا

• من مانے بیرونی منسلک URL

• Chat کے ویب ہک واقعات

مطلوبہ دائرے

ایسی API کلید استعمال کریں جس میں یہ دائرے ہوں:

chat:create
chat:read

ترتیبات میں بننے والی نئی کلیدیں عموماً دونوں دائرے رکھتی ہیں۔ پرانی کلید کو Chat 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": "مصنوعات کی نئی تصویری مہم کے اجرا کا مختصر منصوبہ لکھیں",
    "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": "مصنوعات کی نئی تصویری مہم کے اجرا کا مختصر منصوبہ لکھیں",
    "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": "اب اسے عمل کی پانچ مرحلوں والی جانچ فہرست میں بدلیں۔"
  }'

نشست اسی Rivya اکاؤنٹ کی اور Public API سے بنی ہونی چاہیے۔ صرف Studio میں بنی گفتگو کی نشست Chat API سے نہ واپس ملتی ہے نہ جاری رکھی جا سکتی ہے۔

تصویری منسلکات

گفتگو کے منسلکات بیرونی URL کے بجائے Files API کے ریکارڈ استعمال کرتے ہیں۔

1. POST /api/v1/files سے تصویر اپ لوڈ کریں۔

2. جواب کے id کو attachments[].file_id کے طور پر استعمال کریں۔

{
  "model": "<image-capable-chat-model-id>",
  "message": "مصنوعات کی اس تصویر کا جائزہ لے کر زیادہ صاف ادارتی سمت تجویز کریں۔",
  "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": "اجرا کے تین اختیارات کا موازنہ کریں۔",
  "enable_web_search": false,
  "reasoning_effort": "default",
  "thought_mode": "default"
}

اختیارات کی معاونت ماڈل کے لحاظ سے بدلتی ہے۔ انہیں اپنے انٹرفیس میں دکھانے سے پہلے /api/v1/models پڑھیں اور chat_capabilities دیکھیں۔

نشستوں کی فہرست

chat:read والی کلید کے ساتھ GET /api/v1/chat/sessions استعمال کریں۔

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"
    }
  ]
}

ایک نشست حاصل کریں

API سے بنی ایک نشست اور اس کے محفوظ پیغامات پڑھنے کے لیے GET /api/v1/chat/sessions/{sessionId} استعمال کریں۔

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

جواب میں محفوظ صارف اور معاون کے پیغامات شامل ہوتے ہیں۔ اندرونی فراہم کنندہ کے خانے ظاہر نہیں ہوتے۔

یکساں نتیجہ دینے والی درخواست

پیداوار میں ہر POST /api/v1/chat/completions اور POST /api/v1/chat/completions/stream درخواست کے ساتھ Idempotency-Key استعمال کریں۔

دوبارہ کوشش میں وہی کلید اور وہی مواد ہو تو Rivya دوسرا پیغام بنائے یا دوبارہ کریڈٹس خرچ کیے بغیر محفوظ جواب لوٹا سکتا ہے۔ ایک ہی کلید مختلف اندراج کے ساتھ دوبارہ استعمال ہو تو API idempotency_conflict دیتی ہے۔

مسلسل جواب کی دوبارہ کوشش میں Rivya سابقہ رمزی جزوی متن دوبارہ نہیں بھیجتا۔ مکمل جواب کی تکرار ایک مختصر SSE ترتیب دیتی ہے، جس میں session.created، message.completed، usage.completed اور done شامل ہیں۔

عام خرابیاں

متعلقہ صفحات

• API ماڈلز

• Files API

• API کریڈٹس

• API خرابیاں اور حدیں

• OpenAPI اور خاکہ معاہدہ