Chat API

使用 POST /api/v1/chat/completions 取得一則完整的非串流聊天回應，或使用 POST /api/v1/chat/completions/stream 取得 Server-Sent Events。

Chat API 以工作階段為基礎。省略 session_id 會建立新的 API 聊天工作階段；傳入回傳的 session_id，即可接續同一個由 API 建立的工作階段。

本文介紹的是已實作的公開 API v1 規格。實際能否執行，仍取決於目前部署是否啟用公開 API、帳號是否有有效的 API 金鑰，以及所選模型在即時模型清單中是否標示為可透過 API 使用；有文件不代表每個環境都能呼叫。

目前範圍

Chat API v1 支援：

• 非串流的助理回應

• 使用 text/event-stream 的 SSE 串流

• API 建立的聊天工作階段

• 預留帳號點數，並依最終權杖用量結算

• 所選模型支援時，可選用網頁搜尋、推理強度和思考模式

• 透過 Files API file_id 值加入圖片附件

Chat API v1 不支援：

• 使用者自行提供完整的 messages 歷史記錄

• 接續只能在 Studio 使用的聊天工作階段

• 任意外部附件 URL

• Chat Webhook 事件

所需權限範圍

使用包含以下權限範圍的 API 金鑰：

chat:create
chat:read

在設定中建立的新金鑰預設包含這兩項權限。較早建立的金鑰可能需要重新建立，才能呼叫 Chat API。

建立 Chat 回覆

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

回應：

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

串流 Chat 回覆

若伺服器要在助理的增量內容抵達時即時接收，請使用 POST /api/v1/chat/completions/stream：

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

串流回應使用 Content-Type: text/event-stream; charset=utf-8。

事件：

範例串流：

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}

如果第一個 SSE 事件之後才發生錯誤，串流會送出 event: error，然後關閉：

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

如果用戶端在完成前斷線，Rivya 會在可行時停止仍在進行的生成串流。未完成的增量內容不會儲存為最終助理訊息。如果伺服器已經提交 message.completed，之後可以使用 GET /api/v1/chat/sessions/{sessionId} 讀取最終結果。

繼續工作階段

使用回傳的 session_id：

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

這個工作階段必須屬於同一個 Rivya 帳號，而且必須由公開 API 建立。只能在 Studio 使用的聊天工作階段，無法透過 Chat API 回傳或接續。

圖片附件

Chat 附件使用 Files API 記錄，而不是外部 URL。

1. 使用 POST /api/v1/files 上傳圖片。

2. 使用回傳的 id 作為 attachments[].file_id。

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

檔案必須屬於同一帳號、kind 為 image，而且處於可用狀態。請將預留位置換成目前可用，且 /api/v1/models 的 chat_capabilities 明確標示支援圖片附件的聊天模型。本文其他範例使用的 claude-sonnet-5-chat 僅支援文字，不能用於這項附件請求。不支援圖片附件的模型會回傳 chat_attachment_not_supported。

選用控制項

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

控制項支援會因模型而異。在你的 UI 中公開控制項前，請讀取 /api/v1/models 並檢查 chat_capabilities。

列出工作階段

使用 GET /api/v1/chat/sessions，並搭配包含 chat:read 權限的金鑰。

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

這只會回傳 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"
    }
  ]
}

取得工作階段

使用 GET /api/v1/chat/sessions/{sessionId} 讀取一個 API 建立的工作階段和其中已提交的訊息。

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

回應包含已提交的使用者與助理訊息，不會公開內部供應商欄位。

冪等性

每個正式環境請求都應使用 Idempotency-Key：POST /api/v1/chat/completions 和 POST /api/v1/chat/completions/stream。

如果重試時使用相同金鑰值與相同請求內容，Rivya 可以回傳已儲存的回應，不會再建立另一則訊息或重複消耗點數。若同一金鑰值搭配不同輸入重複使用，API 會回傳 idempotency_conflict。

重試串流請求時，Rivya 不會重播過去的權杖增量。若原請求已完成，重播時會回傳最精簡的 SSE 序列，包括 session.created、message.completed、usage.completed 和 done。

常見錯誤

相關頁面

• API 模型

• Files API

• API 點數

• API 錯誤與限制

• OpenAPI 與結構描述規格