查看 Rivya API v1 的 Schema 来源、兼容规则、公共字段和只读 OpenAPI JSON 契约。

Rivya API v1 在这里提供只读 schema 合同：

https://rivya.ai/api/v1/openapi.json

这个 route 只输出公开合同。它不会读取用户 session 数据，不会提交模型任务，也不会暴露私有账户数据。

合同来源

合同来自：

公共 API 请求 schema
公共错误码
公共 API 模型参考层
/api/v1/models 使用的同一模型目录

模型列表是动态的。不要让集成依赖人工写死的模型数量。

版本策略

当前 API 版本是 v1。

兼容性变更可以包括：

给 /api/v1/models 增加模型
增加可选响应字段
给某个模型增加可选请求参数
增加新的公共错误码

破坏性变更需要新版本或明确迁移路径。

公共字段边界

公共 schema 字段使用公开命名：

id
status
model
session_id
message
usage
reserved_credits
final_credits
created_at
updated_at
result
error

不要依赖内部任务存储字段。它们不是公共合同的一部分。

请求 Schema

POST /api/v1/generations 接受：

model：必填，公共模型 ID
prompt：可选字符串，很多模型实际需要
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。每张 Image5、Grok Imagine Image 2.0 或 Wan 3.0 参考图都必须使用原始模型绑定上传响应返回的图片签名 token 与绑定字节数；图层拆分还会校验文档规定的几何边界。每个 Video8 或 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} 会返回该 API 账户名下文件的公共元数据；未持久化的签名元数据 token 可能为 null，此时必须重新上传。

video_metadata_token 会绑定 API 账户、目标模型、URL、MIME、宽高、帧率、码率和上传字节数。它不能替代 duration_token；同时使用两类合同的 Video8 和 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

OpenAPI 输出会记录这些公共响应结构：

ModelList，用于 GET /api/v1/models
PublicApiModel 和 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 API
CreditBalance，用于 GET /api/v1/credits
WebhookEndpoint、WebhookEvent、WebhookDelivery 和 WebhookTestResult，用于签名 API webhooks
PublicApiError，用于稳定错误响应

这份 schema 可以用于客户端校验和内部集成测试。TypeScript SDK beta 继续受这份 schema 约束。

示例治理

文档中的 curl、JavaScript 和 Python 示例使用同一套公共字段：

Authorization: Bearer rvya_sk_...
Idempotency-Key
model
prompt
message
session_id
params
client_request_id

Chat 示例还会使用：

chat:create
chat:read
file_id

Webhook 示例还会使用：

Rivya-Webhook-Signature
Rivya-Webhook-Timestamp
webhooks:manage

当模型参数变化时，先更新模型目录和 public serializer。文档和调试器应该消费同一层公共数据，而不是复制另一张表。

OpenAPI 与 Schema 契约