一条好的 Rivya API 接入，不只是向某个模型发一次请求。
真实产品流程通常是一条小链路：选模型、准备输入、需要时上传参考文件、提交任务、跟踪状态、处理积分，并在结果完成后通知产品里的正确位置。
这篇讲的是规划方式。最短可运行路径请看 Rivya API 快速开始，具体请求字段以 API 文档为准。
先定义产品动作
选端点前，先用一句话写清楚产品动作。
比如：
卖家提交 listing brief 后，创建一版产品图草稿。campaign manager 确认静帧方向后，生成一版短视频概念。在内部研究工具里发送一轮 Chat，并把 streaming 回复展示给用户。上传参考图，提交支持该输入的模型请求，并在结果完成后通知用户。
这句话能避免接入变成一堆松散 API 调用。
写代码前先画出工作流
打开 schema 前，先看这张表。
| 工作流步骤 | 产品问题 | API 区域 |
|---|---|---|
| 账号访问 | 哪个 Rivya 账号承担这次使用？ | API 鉴权 |
| 模型选择 | 哪个公开模型 ID 适合这件事？ | API 模型列表 |
| 参考输入 | 模型是否需要上传媒体？ | Files API |
| 生成任务 | 这是异步图片、视频还是音频任务？ | 创建生成任务 |
| Chat | 这是 Chat turn，而不是生成任务吗？ | Chat API |
| 状态 | 产品怎么知道结果已经完成？ | 生成任务状态 |
| 完成事件 | 另一个系统需要签名回调吗？ | API Webhooks |
| 积分 | 团队怎样理解成本？ | API 积分 |
工作流应该清楚到每一块 API 都有存在理由。
第 1 步：为这个接入创建 Key
为具体应用、环境或工作流创建 API Key。
不要一把 Key 用在所有地方。按用途命名，后续更容易审查：
production-image-workflowstaging-video-testsinternal-chat-assistantwebhook-smoke-test
保存 Key 前先读 API 鉴权。完整密钥只展示一次，所以团队应该立即保存到正确的服务端密钥管理位置。
第 2 步：从公开 API 模型列表里选模型
不要因为某个模型在人工测试里跑通过，就直接写死到产品里。
通过 API 模型列表 和 模型 API Reference 确认：
- 公开模型 ID
- 是否已开放 API 调用
- 支持的输入形态
- 提示词和参数要求
- 是否依赖 Files API
- 积分行为和 readiness 提示
很多接入在这一步会变清楚。适合手动 Studio 测试的模型，不一定就是自动化产品流程的第一选择。
第 3 步：决定第一版是否需要 Files API
如果模型可以只靠文本输入运行，第一版就先保持 text-only。
只有工作流真的需要参考素材时，再加入 Files API。
加入前先定义：
- 产品接受哪些文件类型
- 谁负责清理文件
- 上传失败时怎么处理
- 返回的文件数据怎样传入模型参数
- 同一文件是复用还是重新上传
这样可以避免一个脆弱的文件体验被藏在看起来很干净的生成按钮后面。
第 4 步：先提交一条生成任务
对图片、视频和音频生成，常见模式是：
- 准备模型 ID、提示词和支持的参数
- 加上幂等键，方便安全重试
- 通过生成端点提交任务
- 保存公开任务 ID
- 轮询状态，直到任务进入终态
产品里应把 queued、processing、succeeded 和 failed 当成用户可理解的状态。不要让用户读系统细节，也不要猜测任务为什么慢。
第 5 步：Chat 模型使用 Chat API
Chat 模型应该使用 Chat API，不要走生成任务端点。
原因是 Chat 的行为不同：
- Chat turn 可以属于 API 创建的 session
- 非 streaming 和 SSE streaming 对用户体验影响不同
- 图片附件使用 Files API 返回的 file ID
- 积分结算跟随 Chat turn，而不是普通异步媒体任务
如果你的产品需要在自己的界面里展示 assistant 回复，Chat API 可能适合。如果用户仍在探索想法，直接使用 Rivya Chat 或 Studio 可能更自然。
第 6 步：先轮询，再加 Webhook
第一版用轮询更容易理解。
当下面情况出现时，再加入 API Webhooks：
- 产品里有很多异步任务
- 等待中的客户端不应该直接轮询
- 下游系统需要签名完成事件
- 重试和重复事件处理已经设计好
Webhook 接收端应该无聊且严格：验签、接受重复安全的事件、只更新一条产品记录，并且只记录安全日志。
第 7 步：让积分在产品里可理解
Rivya API 使用和 Studio 相同的账户积分。
你的接入需要决定展示多少信息。至少团队应该知道：
- 哪个账号拥有这把 API Key
- 哪条工作流会消耗积分
- 积分不足时发生什么
- 生成失败状态如何解释
- 用户应该去哪里看积分和账单问题
用户可见的钱包模型可以继续读 API 积分、Rivya 积分与账单 和 怎样理解 Rivya 的积分、积分包和套餐。
一个小而稳的第一版
好的第一版应该刻意克制。
例如：
- 一把 API Key
- 一个已选定的图片模型
- 暂时不做文件上传
- 一条生成请求
- 一条状态轮询路径
- 产品里一个简单结果预览
- 一个清楚的积分错误提示
这个版本先证明连接是通的，再逐步增加复杂度。
更完整的版本可以加什么
第一版跑通后，完整工作流可以继续加入：
- 为参考图片或视频加入 Files API
- 模型特定参数控制
- 和产品记录绑定的幂等键
- 用于完成事件的签名 Webhook
- 用于 assistant turn 的 Chat API
- 需要实时输出时的服务端 event stream
- 给管理员或支持团队看的失败任务视图
每一项都应该回应真实产品需求。如果只是让 demo 看起来更大，可以先不加。
常见接入错误
避免这些做法：
- 第一版就接入所有 API 能力
- 让账号负责人看不清积分消耗
- 把 Studio 私有假设带进 API 流程
- 把文件上传当成附属细节
- 不带幂等键就重试生成请求
- 把应该异步生成的任务误用 Chat API
- 把 Chat turn 误走生成端点
- 记录完整 API Key、Webhook secret 或临时文件细节
最安全的 API 工作流，会把归属、状态和失败处理都说清楚。
下一步看哪里
- 从 Developers 进入公开 API 入口。
- 用 Rivya API 快速开始 跑通第一条请求。
- 选模型前先看 API 模型列表。
- 只有模型真的需要参考素材时，再看 Files API。
- Chat turn 和 streaming chat 回复看 Chat API。
- 轮询不够用时，再接 API Webhooks。
- 如果这条工作流还需要人工探索，先读 什么时候该用 Rivya API，而不是 Studio？，再决定是否自动化。
