使用 Rivya Chat API 發送非串流或 SSE 回合、API 建立的工作階段、file_id 圖片附件，並依 token 結算點數。

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

Chat API 以工作階段為基礎。省略 session_id 會開始新的 API chat 工作階段。傳入回傳的 session_id，即可繼續同一個由 API 建立的工作階段。

目前範圍

Chat API v1 支援：

非串流 assistant 回應
使用 text/event-stream 的 SSE 串流
API 建立的聊天工作階段
帳號點數預留和最終依 token 結算
在所選模型支援時，可使用選用的 web search、reasoning effort 和 thought mode
透過 Files API file_id 值加入圖片附件

Chat API v1 不支援：

使用者自行提供原始 messages 歷史
繼續 Studio-only 的聊天工作階段
任意外部附件 URL
Chat webhook events

所需 Scopes

使用包含以下 scopes 的 API key：

chat:create
chat:read

在 Settings 中新建立的 key 預設包含這兩個 scopes。較早建立的 key 可能需要重新建立，才能呼叫 Chat API。

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

回應：

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

串流 Chat Completion

當你的伺服器想在 assistant delta 抵達時即時接收，請使用 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": "gpt-5-2-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`	API key、模型、工作階段、附件、速率限制和點數預留檢查均已通過。
`message.delta`	assistant 訊息的顯示 delta。這還不是已提交的訊息。
`message.completed`	assistant 訊息已提交到 API 建立的工作階段。
`usage.completed`	Token 使用量和最終點數已完成結算。
`heartbeat`	長時間停頓期間的 keepalive 事件。
`error`	串流開始後失敗時的公開 API error envelope。
`done`	串流已成功完成。

範例串流：

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}

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

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

如果用戶端在完成前斷線，Rivya 會在可行時停止進行中的生成串流。部分 delta 不會儲存為最終 assistant 訊息。如果伺服器已經提交 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": "gpt-5-2-chat",
    "session_id": "session_id",
    "message": "Now turn that into a 5-step execution checklist."
  }'

這個工作階段必須屬於同一個 Rivya 帳號，且必須由 Public API 建立。Studio-only 的聊天工作階段不會由 Chat API 回傳或繼續。

圖片附件

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

使用 POST /api/v1/files 上傳圖片。
使用回傳的 id 作為 attachments[].file_id。

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

檔案必須屬於同一個帳號、具備 kind: "image"，且狀態可用。不支援圖片附件的模型會回傳 chat_attachment_not_supported。

選用控制項

{
  "model": "gpt-5-2-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 的 key。

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

這只會回傳 API 建立的工作階段：

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

取得工作階段

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

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

回應包含已提交的 user 和 assistant 訊息。不會暴露內部 provider 欄位。

冪等性

對每個 production 請求都使用 Idempotency-Key：POST /api/v1/chat/completions 和 POST /api/v1/chat/completions/stream。

如果重試使用相同 key 和相同 body，Rivya 可以回傳已儲存的回應，而不會再建立另一則訊息或再次消耗點數。如果相同 key 搭配不同輸入重複使用，API 會回傳 idempotency_conflict。

對於串流重試，Rivya 不會重播歷史 token delta。已完成的重播會回傳最小 SSE 序列，包含 session.created、message.completed、usage.completed 和 done。

常見錯誤

Code	意義
`chat_model_not_supported`	所選模型不適用於 Chat API。
`chat_session_conflict`	這個工作階段不能用於此請求。
`chat_attachment_not_supported`	附件缺失、不屬於該帳號、不是圖片，或模型不支援。
`insufficient_credits`	帳號沒有足夠點數完成這一回合。
`idempotency_conflict`	冪等 key 以不同輸入重複使用。

Chat API