↓
Rivya AI 文档

Chat API

使用 Rivya Chat API 发送文本轮次,了解请求字段、SSE 事件、会话规则与积分结算。

最近审阅于 2026年11月5日

使用 POST /api/v1/chat/completions 获取一轮完整的非 streaming Chat response;使用 POST /api/v1/chat/completions/stream 获取 Server-Sent Events。

Chat API 基于 session。省略 session_id 会创建新的 API chat session;传入返回的 session_id 可以继续同一个由 API 创建的 session。

本文介绍的是已经实现的 Public API v1 合同。实际运行仍取决于部署是否启用 Public API、账号是否有有效 API key,以及所选模型是否在实时模型列表中显示为 API 可用;文档存在不代表所有环境都能调用。

当前范围

Chat API v1 支持非流式回复、text/event-stream SSE、API 会话、账号积分预留、token 用量记录和积分结算。网络搜索、推理强度、思考模式及 Files 图片附件均以所选模型能力为限。

当前可调用的是仅接受文本的 Claude 模型,支持思考模式,不支持图片附件、网络搜索或可选推理强度。不可用或 Coming Soon 模型不能调用;以模型列表的可用性与 chat_capabilities 为准,不能套用提供商自己的功能列表。

不支持用户自传 messages 历史、继续仅在 Studio 创建的会话、任意外部附件 URL 或 Chat Webhook 事件。

所需 Scope

提交轮次需要 chat:create,列出或读取 API 会话需要 chat:read:

chat:create
chat:read

设置中新建的密钥默认包含两项权限;旧密钥缺少时需创建替代密钥。密钥须启用且未过期,所属账号须获准使用 API。

创建 Chat Completion

两个完成接口接受相同字段:

字段必填说明
model是当前可用的聊天模型 ID,最多 160 字符;继续会话时使用原模型。
message是去除首尾空白后 1–8,000 字符。系统加载已存对话,不传 messages 数组。
session_id否本账号的 API 会话,最多 160 字符;省略则新建。
tool_slug否Rivya 聊天预设标识,最多 160 字符;见可选控制项。
enable_web_search否布尔值;仅模型支持且为 true 时启用,否则关闭。
reasoning_effort否default、minimal、low、medium、high、xhigh;仅模型 chat_capabilities.reasoning_efforts 中的值生效,其他合法选择回到默认。
thought_mode否default、on、off;仅 chat_capabilities.thoughts 为真时 on/off 生效;default 不指定思考设置。
attachments否最多 6 个含 file_id 的对象,同时受模型图片上限限制;见图片附件。
client_request_id否最多 128 字符的审计跟踪标识,不能替代 Idempotency-Key。

发送前替换密钥占位符,每个新轮次使用不同幂等键,并确保可用积分足够:

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、时间、token 和积分数值均为示例,不是该提示词的报价:

{
  "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": "...",
    "created_at": "2026-05-11T00:00:00.000Z"
  },
  "usage": {
    "input_tokens": 1200,
    "output_tokens": 320,
    "total_tokens": 1520
  },
  "credits": {
    "reserved": 3,
    "final": 2,
    "settlement_status": "SETTLED"
  }
}

Rivya 在请求回复前预留积分,金额取决于模型、已存消息、本轮消息、预设指令及支持的附件。usage 记录 token 数,不代表最终积分费用。

credits.settlement_status 表示结算状态。报告的积分消耗有效且不超过预留时结算并返还余额;消耗缺失、无效或超出预留时为 RECONCILIATION_REQUIRED,credits.final 仍为预留额。因此已保存回复和已记录用量不代表结算完成。参阅API 积分。

Streaming Chat Completion

使用 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。

事件含义
session.created密钥、模型、会话、附件、限流和积分预留检查通过,本轮会话已准备好。
message.delta用于展示的文本片段,尚未保存为助手消息。
message.completed助手消息已提交到 API 会话。
usage.completedtoken 用量和积分值,包含 settlement_status;不保证结算完成。
heartbeat暂停输出时保持连接。
error流开始后的错误封装;查看错误码,不能据此断言轮次未提交。
done流成功结束,仍须单独检查结算状态。

已结算轮次的示例,数值与上文一致:

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,"settlement_status":"SETTLED"}}

event: done
data: {"request_id":"req_...","ok":true}

流开始前拒绝请求会返回带 HTTP 状态的 JSON 错误。开始后 HTTP 为 200;若仍能发送错误,则发送 event: error 并关闭,不发送 done:

event: error
data: {"error":{"code":"internal_error","message":"Rivya could not confirm the result of this request.","requestId":"req_..."}}

客户端断线时 Rivya 尝试停止上游流。展示片段不能证明提交,需以 message.completed 或已存会话确认。断线或截断不能确定消息是否提交、积分如何结算。收到 session_id 后,发送下一轮前先查询 GET /api/v1/chat/sessions/{sessionId};即使完成事件未送达,已提交回复仍可在那里读取。

继续 Session

使用返回的 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."
  }'

会话须属于同一账号且由 Public API 创建;不能列出、读取或继续仅在 Studio 创建的会话。同账号浏览器聊天历史也可能包含 API 会话。

保持原模型。会话已有预设时,省略 tool_slug 可复用,或传同一标识;不同预设会被拒绝。每轮显式传入所需控制项,省略时回到默认,不沿用前一请求。

图片附件

附件使用 Files 记录,不接受外部 URL。当前可用的 Claude 模型不接受附件;仅当可用模型的 chat_capabilities.image_attachments: true 时可使用以下合同。

  1. 用具有 files:create 的密钥调用 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"、状态可用,格式为 JPEG、PNG 或 WebP;ID 不可重复。schema 最多 6 张,模型上限可能更低。只用可用且支持图片的模型替换占位符;claude-sonnet-5-chat 不符合。能力不支持或文件缺失、不可用、格式错误、不属本账号时返回 chat_attachment_not_supported。能力与数量检查通过后,重复 ID 返回 validation_failed。

可选控制项

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

展示控制项前读取 /api/v1/models 的 chat_capabilities。schema 合法不代表功能可用:不支持的网络搜索保持关闭,推理选择回到默认,思考设置被省略。thought_mode 控制模型思考设置,不另行返回思考内容字段。

tool_slug 选择本轮预设指令,目前为 ai-calculator 与 ai-solver,不会运行独立计算器、自动验证答案或提供任意函数调用。创建会话时选定的预设会保存;原来没有预设的会话传入它时,仅对本轮生效,不保存为会话预设。

查询 Sessions

用具有 chat:read 的密钥读取 GET /api/v1/chat/sessions:

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

仅返回本账号 API 会话,按最近活动排序。limit 解析为整数,正数最多 100,否则默认 20;没有分页游标。

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

查询单个 Session

读取 API 会话及已提交消息:

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

按时间顺序返回已提交的用户与助手消息,排除处理中或失败轮次。消息含 id、role、content、created_at;不含 token 用量、积分结算、图片附件或内部提供商字段。

幂等

每个新的完成或流式完成 POST 轮次发送 Idempotency-Key。网络错误后核查时,保持同一 API 密钥、幂等键和正文。

匹配的已存响应会重放,不新建或收费另一轮;已存错误也会重放。不同正文、处理中记录或无可重放响应均返回 idempotency_conflict,不表示应该换新键再次提交。

成功流的重放依次发送 session.created、message.completed、usage.completed、done,无历史增量。已存失败以原 HTTP 状态的 JSON 错误返回,不重放错误流。

响应不完整时先核查原会话。未收到 session_id 时,可查最近 API 会话,并用原键与正文读取已存响应(若有)。client_request_id 仅用于审计;换新幂等键可能产生另一笔收费轮次。

常见错误

错误码含义
chat_model_not_supported模型缺失、不是聊天模型或当前不可调用。
chat_session_conflict模型或预设与会话冲突,或预设标识未知。
chat_attachment_not_supported模型不支持,或文件缺失、不可用、不属本账号、非图片或格式不支持。
insufficient_credits可用积分不足以预留本轮费用。
idempotency_conflict请求数据不同、仍在处理或无可重放响应。
not_found会话不存在、不属本账号或并非 API 创建。
validation_failed字段不符合 schema 或附件 ID 重复。
internal_error无法确认结果;创建新轮次前核查已存回复。

相关页面