Gunakan Rivya Chat API untuk turn non-streaming atau SSE, session yang dibuat API, lampiran gambar file_id, dan penyelesaian credits berbasis token.

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

Chat API berbasis session. Hilangkan session_id untuk memulai session chat API baru. Kirim session_id yang dikembalikan untuk melanjutkan session yang sama yang dibuat API.

Cakupan Saat Ini

Chat API v1 mendukung:

respons assistant non-streaming
streaming SSE dengan text/event-stream
session chat yang dibuat API
reservasi credits akun dan penyelesaian akhir berbasis token
web search, reasoning effort, dan thought mode opsional saat didukung oleh model yang dipilih
lampiran gambar melalui nilai file_id dari Files API

Chat API v1 tidak mendukung:

riwayat raw messages yang dikirim pengguna
melanjutkan session chat khusus Studio
URL lampiran eksternal sembarang
event webhook Chat

Scope yang Dibutuhkan

Gunakan API key dengan:

chat:create
chat:read

Key baru yang dibuat di Settings menyertakan kedua scope secara default. Key lama mungkin perlu dibuat ulang sebelum memanggil Chat API.

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

Streaming Chat Completion

Gunakan POST /api/v1/chat/completions/stream saat server Anda ingin menerima delta assistant saat tersedia:

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	Arti
`session.created`	API key, model, session, lampiran, rate limit, dan pemeriksaan reservasi credits berhasil.
`message.delta`	Delta tampilan untuk pesan assistant. Ini belum menjadi pesan yang committed.
`message.completed`	Pesan assistant sudah committed ke session yang dibuat API.
`usage.completed`	Penggunaan token dan credits final sudah diselesaikan.
`heartbeat`	Event keepalive selama jeda panjang.
`error`	Public API error envelope untuk kegagalan setelah streaming dimulai.
`done`	Stream selesai dengan sukses.

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 error terjadi setelah event SSE pertama, stream mengirim event: error lalu menutup:

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

Jika klien terputus sebelum selesai, Rivya menghentikan stream generasi yang sedang berjalan jika memungkinkan. Delta parsial tidak disimpan sebagai pesan assistant final. Jika server sudah committed message.completed, hasil final bisa dibaca nanti dengan GET /api/v1/chat/sessions/{sessionId}.

Melanjutkan Session

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

Session tersebut harus milik akun Rivya yang sama dan harus dibuat oleh Public API. Session chat khusus Studio tidak dikembalikan atau dilanjutkan oleh Chat API.

Lampiran Gambar

Lampiran chat menggunakan record Files API, bukan URL eksternal.

Unggah gambar 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_..."
    }
  ]
}

File harus milik akun yang sama, memiliki kind: "image", dan tersedia. Model yang tidak mendukung lampiran gambar akan mengembalikan chat_attachment_not_supported.

Kontrol Opsional

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

Dukungan kontrol berbeda menurut model. Baca /api/v1/models dan periksa chat_capabilities sebelum menampilkan kontrol di UI Anda.

Mencantumkan Session

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 session yang dibuat 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"
    }
  ]
}

Mengambil Satu Session

Gunakan GET /api/v1/chat/sessions/{sessionId} untuk membaca satu session yang dibuat API beserta pesan committed-nya.

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

Respons menyertakan pesan user dan assistant yang sudah committed. Respons tidak mengekspos field provider internal.

Idempotensi

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 dapat mengembalikan respons tersimpan tanpa membuat pesan lain atau memakai credits lagi. Jika key yang sama dipakai ulang dengan input berbeda, API mengembalikan idempotency_conflict.

Untuk retry streaming, Rivya tidak memutar ulang delta token historis. Replay yang sudah selesai mengembalikan urutan SSE minimal dengan session.created, message.completed, usage.completed, dan done.

Error Umum

Code	Arti
`chat_model_not_supported`	Model yang dipilih tidak tersedia untuk Chat API.
`chat_session_conflict`	Session tidak dapat digunakan untuk permintaan ini.
`chat_attachment_not_supported`	Lampiran hilang, bukan milik akun, bukan gambar, atau tidak didukung oleh model.
`insufficient_credits`	Akun tidak memiliki credits yang cukup untuk turn ini.
`idempotency_conflict`	Idempotency key dipakai ulang dengan input berbeda.

Chat API