Chat API

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

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

Trang này mô tả hợp đồng Public API v1 đã được triển khai. Quyền truy cập khi chạy vẫn phụ thuộc vào Public API được bật cho bản triển khai, tài khoản có khóa API đang hoạt động và mô hình được chọn báo trạng thái API khả dụng. Hãy kiểm tra danh sách mô hình trực tiếp trước khi gửi yêu cầu sản xuất.

Phạm vi hiện tại

Chat API v1 hỗ trợ:

• phản hồi assistant không truyền theo luồng

• SSE truyền theo luồng với text/event-stream

• trò chuyện phiên do API tạo

• dự trữ điểm tín dụng 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 trò chuyện phiên 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 phạm vi. 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": "claude-sonnet-5-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": "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

Dùng POST /api/v1/chat/completions/stream khi máy chủ 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": "claude-sonnet-5-chat",
    "message": "Write a concise launch plan for a new product image campaign",
    "client_request_id": "chat-stream-001"
  }'

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

Sự kiện:

Ví dụ luồng:

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}

Nếu lỗi xảy ra sau sự kiện SSE đầu tiên, luồng 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 ứng dụng khách ngắt kết nối trước khi hoàn tất, Rivya sẽ dừng tạo nội dung luồng đang chạy khi có thể. Partial deltas không được lưu thành assistant tin nhắn cuối cùng. Nếu máy chủ đã ghi nhận 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 phiên

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

Phiên 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 trò chuyện phiên chỉ thuộc Studio.

Ảnh đính kèm

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

1. Tải ảnh lên bằng POST /api/v1/files.

2. Dùng id được trả về làm attachments[].file_id.

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

Tệp phải thuộc cùng tài khoản, có kind: "image" và đang khả dụng. Thay placeholder bằng mô hình trò chuyện đang khả dụng có mục /api/v1/models báo hỗ trợ tệp ảnh trong chat_capabilities. claude-sonnet-5-chat là ví dụ chỉ dùng văn bản ở các phần khác và không được dùng cho yêu cầu đính kèm này. Mô hình không hỗ trợ sẽ trả về chat_attachment_not_supported.

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

{
  "model": "claude-sonnet-5-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ê phiêns

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ề phiên do API tạo:

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

Lấy một phiên

Dùng GET /api/v1/chat/sessions/{sessionId} để đọc một phiên do API tạo và các tin nhắn đã ghi nhận 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 tin nhắn đã ghi nhận. Phản hồi không để lộ trường nhà cung cấp nội bộ.

Idempotency

Dùng Idempotency-Key cho mọi yêu cầu môi trường vận hành POST /api/v1/chat/completions và POST /api/v1/chat/completions/stream.

Nếu một lần thử lại 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 tin nhắn hoặc tiêu điểm tín dụng lần nữa. Nếu cùng key được dùng lại với dữ liệu đầu vào khác, API trả về idempotency_conflict.

Với thử lại truyền theo luồng, 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

Trang liên quan

• Mô hình API

• Files API

• API Điểm tín dụng

• Lỗi và giới hạn API

• OpenAPI và hợp đồng lược đồ