Non-streaming या SSE turns, API-created sessions, file_id image attachments और token-based credit settlement के लिए Rivya Chat API इस्तेमाल करें।

एक पूरा 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 छोड़ दें। उसी 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

इन scopes वाली API key इस्तेमाल करें:

chat:create
chat:read

Settings में बनाई गई नई keys में default रूप से दोनों scopes शामिल होते हैं। Chat API call करने से पहले older keys को 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 आते ही चाहिए हों, तब 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:

Event	Meaning
`session.created`	API key, model, session, attachments, rate limit और credit reservation checks pass हुए।
`message.delta`	Assistant message के लिए display delta। यह अभी committed message नहीं है।
`message.completed`	Assistant message API-created session में commit हो गया।
`usage.completed`	Token usage और final credits settle हो गए।
`heartbeat`	लंबे pauses के दौरान keepalive event।
`error`	Streaming शुरू होने के बाद failure के लिए public API error envelope।
`done`	Stream successfully complete हुआ।

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 इस्तेमाल करते हैं।

POST /api/v1/files से image upload करें।
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 के हिसाब से बदलता है। अपने UI में controls expose करने से पहले /api/v1/models read करें और chat_capabilities check करें।

List Sessions

GET /api/v1/chat/sessions को ऐसी key के साथ इस्तेमाल करें जिसमें chat:read शामिल हो।

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 शामिल होते हैं। यह internal provider fields expose नहीं करता।

Idempotency

हर production request के लिए Idempotency-Key इस्तेमाल करें: POST /api/v1/chat/completions और POST /api/v1/chat/completions/stream।

अगर retry वही key और वही body इस्तेमाल करता है, तो Rivya दूसरा message create किए बिना या credits फिर consume किए बिना stored response return कर सकता है। अगर वही key अलग input के साथ reuse होती है, तो API idempotency_conflict return करता है।

Streaming retries के लिए Rivya historical token deltas replay नहीं करता। Completed replay session.created, message.completed, usage.completed और done के साथ minimal SSE sequence return करता है।

Common Errors

Code	Meaning
`chat_model_not_supported`	Selected model Chat API के लिए available नहीं है।
`chat_session_conflict`	Session इस request के लिए इस्तेमाल नहीं हो सकता।
`chat_attachment_not_supported`	Attachment missing है, account की owned नहीं है, image नहीं है, या model द्वारा unsupported है।
`insufficient_credits`	Account के पास इस turn के लिए पर्याप्त credits नहीं हैं।
`idempotency_conflict`	Idempotency key अलग input के साथ reuse हुई।

Chat API

विषय-सूची