Rivya API 总览
使用 Rivya API v1 从你的产品调用 Rivya 生成模型和 Chat 模型,通过 API Key 鉴权、账户积分和可选 SSE streaming 集成。
最近审阅于 2026年11月5日
当部署已启用 Public API,且你的账号具备访问权限时,Rivya API v1 就是从自有产品调用 Rivya 已支持模型能力的开发者契约。
当前已实现的契约涵盖异步图片、视频和音频生成,以及支持非流式或 SSE 流式响应的 Chat API 对话。它使用 Rivya 模型 ID 和账户积分;生成任务使用公开任务 ID,Chat API 则使用服务端会话。文档列出某条路由,并不代表每个环境、账号或目录模型都能调用它;接入前请确认实时访问权限和模型就绪状态。
API 适合做什么
支持幂等的重试须保持同一 Idempotency-Key、API Key 和请求体。可读所属账户的生成任务及 API 创建的聊天会话;网页创建的聊天不能用 Chat API 继续。HTTP 示例从快速开始进入。
当你需要下面这些能力时,可以使用 API:
从你自己的应用提交图片、视频或音频生成任务
发送非 streaming 或 streaming Chat turn,并继续 API 创建的对话 session
让计费继续走同一个 Rivya 账户积分钱包
通过公开任务 ID 轮询任务状态
用幂等重试降低生产请求风险
让 Studio 和 API 使用保持在同一个账户边界内
API 是 Rivya 的产品层。公共响应只使用 Rivya 名称和公开字段。
当前版本范围
OpenAPI 契约提供完整请求、响应与其他 Webhook 管理路由。目录包含不可用和 Coming Soon 项;新请求先选 api_status: available 并检查模型参考中的运行类型、输入与参数,服务商支持不表示 Rivya 已开启。
签名 Webhook 仅覆盖 API 创建的异步生成。管理端点需要部署开启 API 和 Webhook,且管理请求的 Key 具有 webhooks:manage;事件投递按任务所属账户的有效端点及其事件订阅处理,详见API Webhooks。
SDK 是尚未发布到公共 npm 的私有测试版,需有源码访问权并在服务端使用;没有权限时直接采用快速开始的 HTTP 示例。客户端与串流能力见TypeScript SDK。
已实现的 v1 端点包括:
GET /api/v1/modelsPOST /api/v1/generationsPOST /api/v1/filesGET /api/v1/files/{fileId}POST /api/v1/chat/completionsPOST /api/v1/chat/completions/streamGET /api/v1/chat/sessionsGET /api/v1/chat/sessions/{sessionId}GET /api/v1/generations/{taskId}GET /api/v1/creditsGET /api/v1/webhooksPOST /api/v1/webhooksGET /api/v1/webhook-eventsGET /api/v1/openapi.json
当前契约包含用于异步生成结果的签名 webhook、Chat API,以及支持服务端流式传输的 TypeScript SDK beta。调用 webhook 相关端点前,部署必须已启用 webhook 功能和 Public API 访问。
鉴权
GET /api/v1/models 和 GET /api/v1/openapi.json 公开无需 Key,其他端点需有效 Key 和对应权限。密钥只保留在服务端,不能放进浏览器或公开仓库。
生成、状态和积分端点需要:
Authorization: Bearer rvya_sk_...在 API Keys 设置 创建和轮换 key。生产使用前,请先阅读 API 鉴权。
计费模型
API 与工作台共用账户余额,生成及聊天均在调用模型前预留积分。最终积分按模型规则与报告的积分用量结算,聊天 token 数量不等于积分扣费。结算待定时,金额可能仍反映预留,应查看 settlement_status。
退回取决于已确认的任务/轮次状态及结算规则。超时、断流或查询失败不证明任务失败或已退回;重试前检查原任务或会话。余额与结算见API 积分和积分与计费。
首次接入路径
目录选择须确认端点可调用与输入准备状态。为目标模型上传后保留完整原始响应及所需签名字段;通知缺失时仍查询原任务。Chat 附件仅在 chat_capabilities 允许时使用,当前可用 Claude 仅接收文字。
在 Settings 创建 API Key。
调用 API 模型列表 选择公开模型 ID。
阅读 模型 API Reference 查看模型参数。
查询API 积分,先核对可用余额。
如果模型需要参考素材,先使用 Files API 上传。
按 创建生成任务 提交任务。
通过 生成任务状态 轮询,直至任务成功或失败。如果部署和账号已启用 webhook,也可以改为订阅 API Webhooks,接收签名完成事件。
对 Chat 模型,请使用 Chat API,不要调用生成任务端点。Chat 图片附件必须引用 Files API 返回的
file_id。
相关页面
常见接入问题
必须使用 SDK 吗?
不必,可在服务端直接使用 API Key 调用 HTTP。SDK 可选且仍为私有测试版;快速开始提供 HTTP 示例。
超时后是否应该重新提交?
超时不确认失败。先检查原任务或聊天会话;支持幂等的端点按规则复用同一 API Key、Idempotency-Key 与请求体。
