查看 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。POST /api/v1/generations 不接受顶层 files 字段。

POST /api/v1/files 接受 multipart form data，字段包括 file、kind、可选 model 和可选 client_request_id。响应结构是 PublicApiFile。GET /api/v1/files/{fileId} 会返回该 API 账户名下文件的同一套公共元数据。

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 合同