Gunakan Rivya Chat API untuk turn tidak streaming atau SSE, sesi ciptaan API, lampiran imej file_id, dan penyelesaian kredit berasaskan token.

Gunakan POST /api/v1/chat/completions untuk satu respons chat lengkap yang tidak streaming, atau POST /api/v1/chat/completions/stream untuk Server-Sent Events.

Chat API berasaskan sesi. Tinggalkan session_id untuk memulakan sesi chat API baharu. Hantar session_id yang dikembalikan untuk meneruskan sesi ciptaan API yang sama.

Scope Semasa

Chat API v1 menyokong:

respons assistant tidak streaming
streaming SSE dengan text/event-stream
sesi chat ciptaan API
tempahan kredit akaun dan penyelesaian akhir berasaskan token
web search, reasoning effort, dan thought mode pilihan apabila disokong oleh model yang dipilih
lampiran imej melalui nilai Files API file_id

Chat API v1 tidak menyokong:

sejarah messages mentah yang dibekalkan pengguna
meneruskan sesi chat Studio sahaja
URL lampiran luaran sewenang-wenangnya
event webhook Chat

Scope Diperlukan

Gunakan API key dengan:

chat:create
chat:read

Key baharu yang dicipta dalam Settings menyertakan kedua-dua scope secara lalai. Key lama mungkin perlu dicipta semula sebelum memanggil Chat API.

Cipta 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"
  }'

Respons:

{
  "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 Chat Completion

Gunakan POST /api/v1/chat/completions/stream apabila server anda mahu delta assistant apabila ia tiba:

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

Respons streaming menggunakan Content-Type: text/event-stream; charset=utf-8.

Event:

Event	Maksud
`session.created`	Semakan API key, model, sesi, lampiran, had kadar, dan tempahan kredit lulus.
`message.delta`	Delta paparan untuk mesej assistant. Ini belum menjadi mesej yang committed.
`message.completed`	Mesej assistant sudah committed ke sesi ciptaan API.
`usage.completed`	Penggunaan token dan kredit akhir sudah diselesaikan.
`heartbeat`	Event keepalive semasa jeda panjang.
`error`	Envelope ralat API awam untuk kegagalan selepas streaming bermula.
`done`	Stream berjaya selesai.

Contoh 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}

Jika ralat berlaku selepas event SSE pertama, stream menghantar event: error dan kemudian ditutup:

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

Jika client terputus sebelum selesai, Rivya menghentikan stream generation yang sedang berjalan apabila boleh. Delta separa tidak disimpan sebagai mesej assistant akhir. Jika server sudah committed message.completed, hasil akhir boleh dibaca kemudian dengan GET /api/v1/chat/sessions/{sessionId}.

Teruskan Sesi

Gunakan session_id yang dikembalikan:

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

Sesi mesti milik akaun Rivya yang sama dan mesti dicipta oleh Public API. Sesi chat Studio sahaja tidak dikembalikan atau diteruskan oleh Chat API.

Lampiran Imej

Lampiran chat menggunakan rekod Files API, bukan URL luaran.

Muat naik imej dengan POST /api/v1/files.
Gunakan id yang dikembalikan sebagai attachments[].file_id.

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

Fail mesti milik akaun yang sama, mempunyai kind: "image", dan tersedia. Model yang tidak menyokong lampiran imej mengembalikan chat_attachment_not_supported.

Kawalan Pilihan

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

Sokongan kawalan berbeza mengikut model. Baca /api/v1/models dan semak chat_capabilities sebelum mendedahkan kawalan dalam UI anda.

Senaraikan Sesi

Gunakan GET /api/v1/chat/sessions dengan key yang menyertakan chat:read.

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

Ini hanya mengembalikan sesi ciptaan API:

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

Dapatkan Sesi

Gunakan GET /api/v1/chat/sessions/{sessionId} untuk membaca satu sesi ciptaan API dan mesej committed di dalamnya.

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

Respons menyertakan mesej user dan assistant yang sudah committed. Ia tidak mendedahkan medan provider dalaman.

Idempotency

Gunakan Idempotency-Key untuk setiap permintaan production POST /api/v1/chat/completions dan POST /api/v1/chat/completions/stream.

Jika retry menggunakan key yang sama dan body yang sama, Rivya boleh mengembalikan respons tersimpan tanpa mencipta mesej lain atau menggunakan kredit sekali lagi. Jika key yang sama digunakan semula dengan input berbeza, API mengembalikan idempotency_conflict.

Untuk retry streaming, Rivya tidak memainkan semula delta token sejarah. Replay yang sudah selesai mengembalikan urutan SSE minimum dengan session.created, message.completed, usage.completed, dan done.

Ralat Lazim

Code	Maksud
`chat_model_not_supported`	Model yang dipilih tidak tersedia untuk Chat API.
`chat_session_conflict`	Sesi tidak boleh digunakan untuk permintaan ini.
`chat_attachment_not_supported`	Lampiran tiada, bukan milik akaun, bukan imej, atau tidak disokong oleh model.
`insufficient_credits`	Akaun tidak mempunyai kredit yang cukup untuk turn ini.
`idempotency_conflict`	Idempotency key digunakan semula dengan input berbeza.

Chat API