Chat API

ایک complete non-streaming chat response کے لیے POST /api/v1/chat/completions استعمال کریں، یا Server-Sent Events کے لیے POST /api/v1/chat/completions/stream استعمال کریں۔

Chat API session-based ہے۔ نئی API chat session شروع کرنے کے لیے session_id omit کریں۔ اسی API-created session کو continue کرنے کے لیے returned session_id pass کریں۔

Current Scope

Chat API v1 support کرتا ہے:

• non-streaming assistant responses
• text/event-stream کے ساتھ SSE streaming
• API-created chat sessions
• account credit reservation اور final token-based settlement
• selected model support کرے تو optional web search، reasoning effort، اور thought mode
• Files API file_id values کے ذریعے image attachments

Chat API v1 support نہیں کرتا:

• user-supplied raw messages history
• Studio-only chat sessions continue کرنا
• arbitrary external attachment URLs
• Chat webhook events

Required Scopes

ایسی API key استعمال کریں جس میں:

chat:create
chat:read

Settings میں created new keys default طور پر دونوں scopes include کرتی ہیں۔ Older keys کو Chat API call کرنے سے پہلے recreate کرنا پڑ سکتا ہے۔

Create A 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"
  }'

Response:

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

Stream A Chat Completion

جب آپ کا server assistant deltas کو arrive ہوتے ہی receive کرنا چاہے تو 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"
  }'

Streaming responses Content-Type: text/event-stream; charset=utf-8 استعمال کرتی ہیں۔

Events:

Example stream:

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}

اگر first SSE event کے بعد error ہو جائے تو stream event: error بھیجتا ہے اور پھر close ہو جاتا ہے:

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

اگر client completion سے پہلے disconnect ہو جائے تو Rivya ممکن ہو تو in-flight generation stream روک دیتا ہے۔ Partial deltas final assistant message کے طور پر save نہیں ہوتے۔ اگر server پہلے ہی message.completed commit کر چکا ہو تو final result بعد میں GET /api/v1/chat/sessions/{sessionId} سے read کیا جا سکتا ہے۔

Continue A Session

Returned 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."
  }'

Session اسی Rivya account سے belong کرنی چاہیے اور Public API نے create کی ہونی چاہیے۔ Studio-only chat sessions Chat API سے return یا continue نہیں ہوتے۔

Image Attachments

Chat attachments external URLs نہیں بلکہ Files API records استعمال کرتے ہیں۔

1. POST /api/v1/files سے image upload کریں۔
2. Returned id کو attachments[].file_id کے طور پر استعمال کریں۔

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

File اسی account سے belong کرنی چاہیے، اس کا kind: "image" ہونا چاہیے، اور وہ available ہونی چاہیے۔ جو models image attachments support نہیں کرتے وہ chat_attachment_not_supported return کرتے ہیں۔

Optional Controls

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

Control support model کے لحاظ سے vary کرتی ہے۔ اپنی UI میں controls expose کرنے سے پہلے /api/v1/models read کریں اور chat_capabilities check کریں۔

List Sessions

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

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

یہ صرف API-created sessions return کرتا ہے:

{
  "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 A Session

ایک API-created session اور اس کے committed messages read کرنے کے لیے GET /api/v1/chat/sessions/{sessionId} استعمال کریں۔

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

Response committed user اور assistant messages include کرتا ہے۔ یہ internal provider fields expose نہیں کرتا۔

Idempotency

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

اگر retry same key اور same body استعمال کرے تو Rivya another message create کیے یا credits دوبارہ consume کیے بغیر stored response return کر سکتا ہے۔ اگر same key different input کے ساتھ reuse ہو تو API idempotency_conflict return کرتی ہے۔

Streaming retries کے لیے Rivya historical token deltas replay نہیں کرتا۔ Completed replay ایک minimal SSE sequence return کرتا ہے جس میں session.created، message.completed، usage.completed، اور done شامل ہوتے ہیں۔

Common Errors

Related Pages

• API Models
• Files API
• API Credits
• API Errors and Limits
• OpenAPI and Schema Contract