Chat API

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

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

Halaman ini mendokumentasikan kontrak Public API v1 yang diterapkan. Akses runtime tetap bergantung pada Public API yang aktif untuk penerapan, akun yang memiliki kunci API aktif, dan model terpilih yang melaporkan status API tersedia. Periksa daftar model langsung sebelum mengirim permintaan produksi.

Cakupan Saat Ini

Chat API v1 mendukung:

• respons asisten non-aliran langsung

• aliran langsung SSE dengan text/event-stream

• sesi chat yang dibuat API

• reservasi kredit 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 sesi chat khusus Studio

• URL lampiran eksternal sembarang

• peristiwa webhook Chat

Scope yang Dibutuhkan

Gunakan API kunci dengan:

chat:create
chat:read

Kunci baru yang dibuat di Pengaturan menyertakan kedua cakupan secara default. Kunci 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": "claude-sonnet-5-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": "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
  }
}

Streaming Chat Completion

Gunakan POST /api/v1/chat/completions/stream saat server Anda ingin menerima delta asisten 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": "claude-sonnet-5-chat",
    "message": "Write a concise launch plan for a new product image campaign",
    "client_request_id": "chat-stream-001"
  }'

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

Peristiwa:

Contoh aliran:

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}

Jika kesalahan terjadi setelah peristiwa SSE pertama, aliran 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 aliran generasi yang sedang berjalan jika memungkinkan. Delta parsial tidak disimpan sebagai pesan asisten akhir. Jika server sudah committed message.completed, hasil akhir bisa dibaca nanti dengan GET /api/v1/chat/sessions/{sessionId}.

Melanjutkan 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": "claude-sonnet-5-chat",
    "session_id": "session_id",
    "message": "Now turn that into a 5-step execution checklist."
  }'

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

Lampiran Gambar

Lampiran chat menggunakan catatan Files API, bukan URL eksternal.

1. Unggah gambar dengan POST /api/v1/files.

2. Gunakan id yang dikembalikan sebagai attachments[].file_id.

{
  "model": "<image-capable-chat-model-id>",
  "message": "Review this product photo and suggest a cleaner editorial direction.",
  "attachments": [
    {
      "file_id": "file_..."
    }
  ]
}

Berkas harus milik akun yang sama, memiliki kind: "image", dan tersedia. Ganti placeholder dengan model chat yang tersedia dan entri /api/v1/models-nya melaporkan dukungan lampiran gambar dalam chat_capabilities. claude-sonnet-5-chat adalah contoh teks-saja di bagian lain halaman ini dan tidak boleh digunakan untuk permintaan lampiran. Model tanpa dukungan akan mengembalikan chat_attachment_not_supported.

Kontrol Opsional

{
  "model": "claude-sonnet-5-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 Sesi

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

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

Ini hanya mengembalikan sesi yang dibuat 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"
    }
  ]
}

Mengambil Satu Sesi

Gunakan GET /api/v1/chat/sessions/{sessionId} untuk membaca satu sesi 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 asisten yang sudah committed. Respons tidak mengekspos kolom penyedia internal.

Idempotensi

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

Jika percobaan ulang menggunakan kunci yang sama dan body yang sama, Rivya dapat mengembalikan respons tersimpan tanpa membuat pesan lain atau memakai kredit lagi. Jika kunci yang sama dipakai ulang dengan masukan berbeda, API mengembalikan idempotency_conflict.

Untuk percobaan ulang aliran langsung, 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

Halaman Terkait

• Model API

• Files API

• Kredit API

• Error dan Limit API

• Kontrak OpenAPI dan Skema