OpenAPI 与 Schema 契约
查看 Rivya API v1 的 Schema 来源、兼容规则、公共字段和只读 OpenAPI JSON 契约。
最近审阅于 2026年11月11日
Rivya API v1 在这里提供只读 schema 合同:
https://rivya.ai/api/v1/openapi.json用以下命令读取公开的实时契约:
curl --fail https://rivya.ai/api/v1/openapi.json -o rivya-openapi.json这个 route 只输出公开合同。它不会读取用户 session 数据,不会提交模型任务,也不会暴露私有账户数据。
提示词单位与完整图层结果
读取 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 已提供这些字段。参考文件必须按所选模型上传,并传回原始签名元数据;单独声明尺寸或时长不能代替核验。
合同来源
此文档端点公开且不需 Key;文档所述的受保护操作仍需对应权限,模型列表也公开。权限见API 鉴权。列表包含不可调用条目,选择前检查类别、api_status 与输入,见API 模型列表。
合同来自:
公共 API 请求 schema
公共错误码
公共 API 模型参考层
/api/v1/models使用的同一模型目录
模型列表是动态的。不要让集成依赖人工写死的模型数量。
版本策略
openapi: 3.1.0 是文档格式,info.version: v1 是 Rivya API 版本,两者不同。工具须支持OpenAPI 3.1及其 JSON Schema 条件规则;旧格式生成器可能丢失校验。客户端应允许新增模型、可选字段与未见过的公共错误码,复核集成时刷新契约,避免旧枚举拒绝新值。
当前 API 版本是 v1。
兼容性变更可以包括:
给
/api/v1/models增加模型增加可选响应字段
给某个模型增加可选请求参数
增加新的公共错误码
破坏性变更需要新版本或明确迁移路径。
公共字段边界
必填属性也可能允许 null:例如响应要求存在 PublicApiFile.duration_token,但值可为空。客户端类型须同时保留“字段存在”和可空性。
公共 schema 字段使用公开命名:
idstatusmodelsession_idmessageusagereserved_creditsfinal_creditssettlement_statuscreated_atupdated_atresulterror
不要依赖内部任务存储字段。它们不是公共合同的一部分。
请求 Schema
通用请求结构中标为可选的字段,在所选模型或模式下仍可能必填。model 须适用于所选端点;提示词要求及长度由模型/模式决定,client_request_id 最多 128 字符且不替代幂等键。参考项的通用可选字段也可能被模型要求必填。提交示例见创建生成。
图片签名要求适用于 seedream-5-pro, seedream-5-pro-layer-decomposition, nano-banana-2-lite, qwen-image-3, qwen-image-3-pro、Grok Imagine Image 2.0 与 Wan 3.0;视频签名要求适用于 seedance-2-mini, seedance-2-5, minimax-h3, gemini-omni-video, gemini-omni-flash-1-1, volcengine-video-lip-sync, wan-3-0-video。保留与账户、目标模型、URL 及上传元数据匹配的原始响应。
聊天串流开始前的失败使用 HTTP 错误,开始后需读 SSE 事件;参数、可用能力与会话规则见聊天 API。
POST /api/v1/generations 接受:
model:必填,公共模型 IDprompt:可选字符串,很多模型实际需要params:可选对象,放模型专属参数client_request_id:可选字符串,用于你的追踪 ID
模型专属 params 见 模型 API Reference。
/api/v1/files 返回的参考素材应放在 params.referenceMediaItems 中。schema 会说明 url、kind、可选 name、可选 mimeType、可选 durationSeconds / durationToken、可选 width / height / sizeBytes / imageDimensionsToken,以及可选 framesPerSecond / videoBitrateMbps / videoMetadataToken。每张 seedream-5-pro, seedream-5-pro-layer-decomposition, nano-banana-2-lite, qwen-image-3, qwen-image-3-pro、Grok Imagine Image 2.0 或 Wan 3.0 参考图都必须使用原始模型绑定上传响应返回的图片签名 token 与绑定字节数;图层拆分还会校验文档规定的几何边界。每个 seedance-2-mini, seedance-2-5, minimax-h3, gemini-omni-video, gemini-omni-flash-1-1, volcengine-video-lip-sync, wan-3-0-video 或 Wan 3.0 参考视频都必须使用原始模型绑定上传响应返回的时长签名和视频元数据签名。POST /api/v1/generations 不接受顶层 files 字段。
POST /api/v1/files 接受 multipart form data,字段包括 file、kind、可选 model 和可选 client_request_id。响应结构是 PublicApiFile,包括 size_bytes、可空的图片宽高、image_dimensions_token,以及可空的 video_width、video_height、frames_per_second、video_bitrate_mbps、video_file_size_bytes 和 video_metadata_token。
GET /api/v1/files/{fileId} 只读取所属账户可用文件;图片尺寸、视频测量及图片/视频元数据签名均固定为 null。重新签发的音频 duration_token 不含 MIME 与字节数,不能替代严格音频校验需要的原始绑定 token。为签名参考保留完整上传响应,必需信息缺失或过期时重新上传;详见文件 API。
video_metadata_token 会绑定 API 账户、目标模型、URL、MIME、宽高、帧率、码率和上传字节数。它不能替代 duration_token;同时使用两类合同的 seedance-2-mini, seedance-2-5, minimax-h3, gemini-omni-video, gemini-omni-flash-1-1, volcengine-video-lip-sync, wan-3-0-video 和 Wan 3.0 参考视频必须携带两个 token。Wan 3.0 音频的时长 token 还会绑定 MIME 和上传字节数。
对于 wan-3-0-video,params 只接受 seedance_scene、variant、resolution、aspect_ratio、duration、audio、seed 和 referenceMediaItems。文本、首尾帧和参考场景互斥。智能时长为 -1,按 30 秒预留,且不能与参考视频同时使用;任意未知字段、未签名媒体、文件转视频快捷模式和链接转视频快捷模式都会 fail closed。
POST /api/v1/chat/completions 接受 model、message、可选 session_id、可选控制项、可选 Files API file_id 附件和可选 client_request_id。它返回一条完整的非 streaming assistant message。
POST /api/v1/chat/completions/stream 使用同一套 request schema,并返回 text/event-stream,事件包括 session.created、message.delta、message.completed、usage.completed、heartbeat、error 和 done。Chat API v1 不接受 raw messages 数组。
响应 Schema
通过 schema 校验不保证可执行,仍检查账户权限、输入组合、签名元数据与运行时可用性,错误处理见API 错误与限制。生成 status 与 settlement_status 分开,成功也可能待结算且 result.primary_url 可为 null;见生成状态与API 积分。TypeScript SDK是未上公共 npm 的私有测试版,静态类型不做完整运行时 schema 校验,也不会开启不可用模型。
OpenAPI 输出会记录这些公共响应结构:
ModelList,用于GET /api/v1/modelsPublicApiModel和ModelParam,用于模型选择和参数表单PublicApiFile,用于POST /api/v1/files和GET /api/v1/files/{fileId}ReferenceMediaItem,用于带文件引用的生成参数PublicGeneration,用于创建任务和查询状态响应GenerationResult和GenerationError,用于已完成任务ChatCompletionRequest、ChatCompletion、ChatSession、ChatMessage、ChatUsage、ChatCredits和 Chat stream event schemas,用于 Chat APICreditBalance,用于GET /api/v1/creditsWebhookEndpoint、WebhookEvent、WebhookDelivery和WebhookTestResult,用于签名 API webhooksPublicApiError,用于稳定错误响应
这份 schema 可以用于客户端校验和内部集成测试。TypeScript SDK beta 继续受这份 schema 约束。
示例治理
文档中的 curl、JavaScript 和 Python 示例使用同一套公共字段:
Authorization: Bearer rvya_sk_...Idempotency-Keymodelpromptmessagesession_idparamsclient_request_id
Chat 示例还会使用:
chat:createchat:readfile_id
Webhook 示例还会使用:
Rivya-Webhook-SignatureRivya-Webhook-Timestampwebhooks:manage
当模型参数变化时,先更新模型目录和 public serializer。文档和调试器应该消费同一层公共数据,而不是复制另一张表。
常见问题
下载 OpenAPI 需要密钥吗?
不需要,该端点公开;文档中的受保护操作仍需正确 Key 和权限。
Schema 校验通过就能生成吗?
不能保证。还须核对模型类别、api_status、输入、参数、账户权限与余额。
