Dùng Rivya Chat API cho các lượt không streaming hoặc SSE, session do API tạo, ảnh đính kèm bằng file_id và quyết toán credits theo token.

Dùng POST /api/v1/chat/completions để nhận một phản hồi chat hoàn chỉnh không streaming, hoặc POST /api/v1/chat/completions/stream cho Server-Sent Events.

Chat API dựa trên session. Bỏ qua session_id để bắt đầu một API chat session mới. Truyền session_id được trả về để tiếp tục chính session do API tạo đó.

Phạm vi hiện tại

Chat API v1 hỗ trợ:

phản hồi assistant không streaming
SSE streaming với text/event-stream
chat session do API tạo
dự trữ credits tài khoản và quyết toán cuối dựa trên token
web search, reasoning effort và thought mode tùy chọn khi mô hình đã chọn hỗ trợ
ảnh đính kèm thông qua giá trị file_id của Files API

Chat API v1 không hỗ trợ:

lịch sử raw messages do người dùng tự cung cấp
tiếp tục chat session chỉ thuộc Studio
URL đính kèm ngoài tùy ý
sự kiện Chat webhook

Scope bắt buộc

Dùng API key có:

chat:create
chat:read

Key mới được tạo trong Settings mặc định bao gồm cả hai scope. Key cũ hơn có thể cần được tạo lại trước khi gọi Chat API.

Tạo 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"
  }'

Phản hồi:

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

Dùng POST /api/v1/chat/completions/stream khi server của bạn muốn nhận delta của assistant ngay khi chúng xuất hiện:

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

Phản hồi streaming dùng Content-Type: text/event-stream; charset=utf-8.

Sự kiện:

Event	Ý nghĩa
`session.created`	API key, mô hình, session, attachments, rate limit và kiểm tra dự trữ credits đã vượt qua.
`message.delta`	Delta hiển thị cho assistant message. Đây chưa phải message đã commit.
`message.completed`	Assistant message đã được commit vào session do API tạo.
`usage.completed`	Token usage và credits cuối đã được quyết toán.
`heartbeat`	Sự kiện keepalive trong các khoảng dừng dài.
`error`	Public API error envelope cho lỗi sau khi streaming đã bắt đầu.
`done`	Stream đã hoàn tất thành công.

Ví dụ 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}

Nếu lỗi xảy ra sau sự kiện SSE đầu tiên, stream sẽ gửi event: error rồi đóng:

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

Nếu client ngắt kết nối trước khi hoàn tất, Rivya sẽ dừng generation stream đang chạy khi có thể. Partial deltas không được lưu thành assistant message cuối cùng. Nếu server đã commit message.completed, kết quả cuối có thể đọc lại sau bằng GET /api/v1/chat/sessions/{sessionId}.

Tiếp tục session

Dùng session_id được trả về:

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 phải thuộc cùng một tài khoản Rivya và phải được tạo bởi Public API. Chat API không trả về hoặc tiếp tục các chat session chỉ thuộc Studio.

Ảnh đính kèm

Chat attachments dùng bản ghi Files API, không dùng URL ngoài.

Tải ảnh lên bằng POST /api/v1/files.
Dùng id được trả về làm attachments[].file_id.

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

File phải thuộc cùng tài khoản, có kind: "image" và đang khả dụng. Mô hình không hỗ trợ ảnh đính kèm sẽ trả về chat_attachment_not_supported.

Điều khiển tùy chọn

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

Khả năng hỗ trợ điều khiển thay đổi theo mô hình. Hãy đọc /api/v1/models và kiểm tra chat_capabilities trước khi hiển thị điều khiển trong UI của bạn.

Liệt kê sessions

Dùng GET /api/v1/chat/sessions với key bao gồm chat:read.

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

Endpoint này chỉ trả về session do API tạo:

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

Lấy một session

Dùng GET /api/v1/chat/sessions/{sessionId} để đọc một session do API tạo và các message đã commit của nó.

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

Phản hồi bao gồm các user và assistant messages đã commit. Phản hồi không để lộ trường provider nội bộ.

Idempotency

Dùng Idempotency-Key cho mọi yêu cầu production POST /api/v1/chat/completions và POST /api/v1/chat/completions/stream.

Nếu một lần retry dùng cùng key và cùng body, Rivya có thể trả về phản hồi đã lưu mà không tạo thêm message hoặc tiêu credits lần nữa. Nếu cùng key được dùng lại với input khác, API trả về idempotency_conflict.

Với retry streaming, Rivya không phát lại các token delta lịch sử. Replay của yêu cầu đã hoàn tất trả về chuỗi SSE tối thiểu gồm session.created, message.completed, usage.completed và done.

Lỗi thường gặp

Code	Ý nghĩa
`chat_model_not_supported`	Mô hình đã chọn không khả dụng cho Chat API.
`chat_session_conflict`	Session không thể dùng cho yêu cầu này.
`chat_attachment_not_supported`	Attachment bị thiếu, không thuộc tài khoản, không phải ảnh hoặc không được mô hình hỗ trợ.
`insufficient_credits`	Tài khoản không đủ credits cho lượt này.
`idempotency_conflict`	Idempotency key đã được dùng lại với input khác.

Chat API