API 更新记录
跟踪 Rivya API v1 文档、端点、模型参考、Schema 和后续能力更新。
最近审阅于 2026年11月11日
这个页面记录会影响开发者的 Rivya API 公共变更。
提示词单位与完整图层结果
读取 GET /api/v1/models 时,请将 prompt_length_unit 与 max_prompt_length 一起使用。utf8_bytes 计算原文的 UTF-8 字节,包含空格和换行;utf16_code_units 计算 JavaScript 的 UTF-16 代码单元。上限为 null 不代表文字不限长或可以不填。Gemini TTS 使用字节单位。
已完成的图层拆分结果可在完整的 result.urls 之外提供 result.layers。请保留每层返回的 z_index、URL、尺寸、名称、说明和边界框,索引零是底图。TypeScript SDK 已提供这些字段。参考文件必须按所选模型上传,并传回原始签名元数据;单独声明尺寸或时长不能代替核验。
Suno Speech:场景与指定脚本
Suno Speech: prompt 在简单模式(params.customMode="false")中是场景描述,在高级模式("true")中是朗读脚本。tone、variety、vocalGender、backgroundMusic 只用于高级模式;简单模式须省略。不要在 params 中另传 script 或 prompt。
2026-05-11
本条文档记录日期为 2026 年 5 月 11 日。下表列举 API v1 文档,不表示各功能在该日上线。
API 总览
快速开始
鉴权
OpenAPI 与 schema 合同
API 模型列表
动态模型 API Reference
提交生成任务
轮询生成任务状态
查询积分余额
错误码与限制
Files API 参考素材上传
API Webhooks 签名生成完成事件
非 streaming 与 streaming Chat API 和 API 创建的 session
当前 API 版本覆盖通过 API Key 和账户积分调用异步图片、视频和音频生成,也包含用于模型参考素材的 Files API 上传、用于生成任务终态通知的签名 webhooks,以及支持非 streaming 或 SSE streaming response 的 Chat API turn。
当前 API v1 范围
API v1 支持异步图片、视频和音频生成、通过文件 API 上传模型参考素材,以及 JSON 或 SSE 聊天响应。创建生成任务或聊天轮次需要部署已开启 API、Key 具有所需权限,且模型可供对应端点调用。两者使用 Key 所属账户的积分。
签名生成事件只覆盖 API 创建的任务。generation.succeeded 要求任务成功且 settlement_status 为 SETTLED;generation.failed 用于失败任务。还需开启 Webhook 功能、账户具有有效端点,并订阅对应事件。签名与投递规则见 API Webhooks。工作台任务和聊天轮次不会发出这些生成事件。
当前端点范围
模型发现和 OpenAPI 公开只读;其他端点需要具有对应权限的 Key,管理 Webhook 还需开启其功能。
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/webhooks/{endpointId}PATCH /api/v1/webhooks/{endpointId}DELETE /api/v1/webhooks/{endpointId}POST /api/v1/webhooks/{endpointId}/rotate-secretGET /api/v1/webhook-eventsGET /api/v1/webhooks/{endpointId}/deliveriesPOST /api/v1/webhooks/{endpointId}/testGET /api/v1/openapi.json
尚未开放
聊天 Webhook 事件尚不支持。TypeScript SDK 已有私有测试版,尚未发布到公共 npm;已获源码访问权限时可按SDK 指南接入,否则直接使用 HTTP。
兼容性说明
OpenAPI 契约为新的生成、聊天与上传请求分别列出模型枚举。历史生成及聊天响应的 model 仍为字符串,可保留旧 ID;不能用新请求的枚举拒绝历史响应。
随着 Rivya 新增、移除或灰度模型,模型列表会变化。请使用 /api/v1/models 或 模型 API Reference,不要依赖固定模型数量。
