使用 Rivya Chat API 发送非 streaming 或 SSE turn，继续 API 创建的 session，使用 file_id 图片附件，并按 token usage 结算积分。

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

当前范围

Chat API v1 支持：

非 streaming assistant response
使用 text/event-stream 的 SSE streaming
API 创建的 chat session
账户积分预留和基于 token usage 的最终结算
在模型支持时使用 web search、reasoning effort 和 thought mode
通过 Files API file_id 使用图片附件

Chat API v1 不支持：

用户自传 raw messages 历史
继续 Studio-only chat session
任意外部附件 URL
Chat webhook event

所需 Scope

使用包含以下 scope 的 API Key：

chat:create
chat:read

Settings 中新建的 key 默认包含这两个 scope。较早创建的 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
  }
}

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

Streaming response 使用 Content-Type: text/event-stream; charset=utf-8。

事件：

Event	含义
`session.created`	API key、模型、session、附件、rate limit 和积分预留校验已通过。
`message.delta`	assistant message 的展示增量，还不是已提交消息。
`message.completed`	assistant message 已写入 API 创建的 session。
`usage.completed`	token usage 和最终积分已完成结算。
`heartbeat`	长时间无 token 输出时的 keepalive。
`error`	streaming 开始后发生失败时的 Public API error envelope。
`done`	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}

如果第一条 SSE event 已经写出后才失败，stream 会发送 event: error 并关闭：

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

如果客户端在完成前断开，Rivya 会尽可能停止正在进行的生成流。partial delta 不会保存为最终 assistant message。若服务端已经完成 message.completed 提交，之后可以用 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": "gpt-5-2-chat",
    "session_id": "session_id",
    "message": "Now turn that into a 5-step execution checklist."
  }'

这个 session 必须属于同一个 Rivya 账户，并且必须由 Public API 创建。Chat API 不会返回或继续 Studio-only 对话 session。

图片附件

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。

查询 Sessions

使用具备 chat:read scope 的 key 调用 GET /api/v1/chat/sessions。

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

该接口只返回 API 创建的 session：

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

查询单个 Session

使用 GET /api/v1/chat/sessions/{sessionId} 读取一个 API 创建的 session 及其已提交 messages。

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

响应会包含已提交的 user 和 assistant messages，不暴露内部 provider 字段。

幂等

生产调用 POST /api/v1/chat/completions 和 POST /api/v1/chat/completions/stream 时建议始终发送 Idempotency-Key。

如果重试使用同一个 key 和同一个请求体，Rivya 可以返回已保存响应，而不会再创建一条 message 或再次扣费。如果同一个 key 搭配不同输入，API 会返回 idempotency_conflict。

对 streaming 重试，Rivya 不承诺重放历史 token delta。已完成请求的重放会返回最小 SSE 序列：session.created、message.completed、usage.completed 和 done。

常见错误

Code	含义
`chat_model_not_supported`	所选模型当前不支持 Chat API。
`chat_session_conflict`	该 session 不能用于当前请求。
`chat_attachment_not_supported`	附件不存在、不属于当前账户、不是图片，或模型不支持该附件。
`insufficient_credits`	账户积分不足，无法完成本轮对话。
`idempotency_conflict`	幂等 key 被用于不同输入。

Chat API