Chat API

Gunakan POST /api/v1/chat/completions untuk satu respons chat lengkap tanpa penstriman, 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.

Halaman ini mendokumenkan kontrak API Awam v1 yang telah dilaksanakan. Akses semasa operasi tetap memerlukan API Awam diaktifkan untuk persekitaran pelaksanaan, akaun mempunyai kunci API yang aktif dan model yang dipilih melaporkan status API tersedia. Semak senarai model aktif sebelum menghantar permintaan produksi.

Skop 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 file_id daripada API Fail

Chat API v1 tidak menyokong:

• sejarah messages mentah yang dibekalkan pengguna

• meneruskan sesi chat Studio sahaja

• URL lampiran luaran sewenang-wenangnya

• event webhook Chat

Skop Diperlukan

Gunakan kunci API dengan:

chat:create
chat:read

Kunci baharu yang dicipta dalam Tetapan menyertakan kedua-dua skop secara lalai. Kunci 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": "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
  }
}

Stream Chat Completion

Gunakan POST /api/v1/chat/completions/stream apabila pelayan anda perlu menerima perubahan jawapan pembantu sebaik sahaja 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": "claude-sonnet-5-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:

Contoh stream:

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 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 klien terputus sebelum selesai, Rivya menghentikan aliran penjanaan yang sedang berjalan apabila boleh. Bahagian separa tidak disimpan sebagai mesej pembantu akhir. Jika pelayan sudah menyimpan 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": "claude-sonnet-5-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 API Fail, bukan URL luaran.

1. Muat naik imej 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_..."
    }
  ]
}

Fail mesti milik akaun yang sama, mempunyai kind: "image" dan tersedia. Gantikan nilai contoh dengan model Chat yang sedang tersedia dan melaporkan sokongan lampiran imej dalam chat_capabilities pada entri /api/v1/models. claude-sonnet-5-chat ialah contoh model teks sahaja yang digunakan di bahagian lain halaman ini dan tidak boleh digunakan untuk permintaan lampiran ini. Model yang tidak menyokong lampiran imej mengembalikan chat_attachment_not_supported.

Kawalan Pilihan

{
  "model": "claude-sonnet-5-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 kunci 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": "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"
    }
  ]
}

Dapatkan Sesi

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

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

Respons menyertakan mesej pengguna dan pembantu yang sudah disimpan. Ia tidak mendedahkan medan dalaman penyedia.

Idempotency

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

Jika percubaan semula menggunakan kunci dan badan permintaan yang sama, Rivya boleh mengembalikan respons tersimpan tanpa mencipta mesej lain atau menggunakan kredit sekali lagi. Jika kunci yang sama digunakan semula dengan masukan berbeza, API mengembalikan idempotency_conflict.

Untuk percubaan semula penstriman, Rivya tidak memainkan semula perubahan token terdahulu. Permintaan lengkap yang dimainkan semula mengembalikan urutan SSE minimum dengan session.created, message.completed, usage.completed dan done.

Ralat Lazim

Halaman Berkaitan

• Model API

• API Fail

• Kredit API

• Ralat dan Had API

• OpenAPI dan Kontrak Skema