Rivya API 是给开发者使用的接入路径，用来从你自己的产品、脚本或工作流里调用 Rivya 模型能力。
它不是 Rivya Studio 之外的另一套产品。它仍然使用同一个账号边界、同一个积分钱包，以及用户在 Rivya 里看到的公开模型层。区别在于任务从哪里开始：不是人在 Studio 里点击操作，而是你的应用通过 API Key 发起请求。
如果你需要端点和请求字段，请从 Rivya API 总览 和 Rivya API 快速开始 读起。这篇文章只回答产品层问题：API 适合做什么、放在什么位置、什么时候不该一上来就用 API。
先用短句理解
Rivya API v1 让登录账号可以创建 API Key，并从网页界面之外调用 Rivya 的模型能力。
当前 API 覆盖：
- 通过 API 模型列表发现可调用模型
- 提交异步图片、视频和音频生成任务
- 为需要参考素材的模型使用 Files API 上传文件
- 通过公开任务 ID 查询生成状态
- 查询账户积分
- 调用 Chat API，包括可选 SSE streaming
- 为生成任务完成结果配置签名 Webhook
- 使用仓库内 TypeScript SDK beta 封装部分调用
公开开发者入口是 Developers。如果你想先看整体能力、API Key 入口和安全调试方式，先从那里开始更顺。
Rivya 为什么需要 API
当人还在选模型、改提示词、看输出、决定下一步时，Studio 更适合。
当这件事已经变成可重复的产品流程或运营流程时，API 更适合。
常见场景包括：
- 用户在你的产品里提交 brief 后，自动生成图片变体
- 营销流程根据结构化 campaign 输入生成视觉草稿
- 内部工具不经过浏览器，直接提交视频或音频任务
- 支持系统或内容系统想在自己的界面里调用一轮 Chat 模型
- 后端服务希望任务完成后收到签名回调
这些场景里，Rivya API 的价值是让模型选择、计费和任务状态仍然留在同一个 Rivya 账号体系里，而不是再搭一套分散链路。
API 不替代什么
API 不应该替代所有直接使用 Rivya 的理由。
下面这些情况更适合继续使用 Studio 或公开工作入口：
- 提示词还在探索
- 模型选择还不稳定
- 创作者需要肉眼比较输出
- 项目依赖保存历史和人工复核
- 团队还没决定哪种输入和输出值得自动化
工作流清楚到可以自动化时，再用 API。
这个边界很重要。模糊的创意问题通常先留在 Studio。输入和输出都比较稳定的产品流程，才适合搬到 API。
API 的主要组成
可以把 API 理解成 6 个互相连接的部分。
| 模块 | 负责什么 | 继续阅读 |
|---|---|---|
| API Key | 让服务器从你的账号访问 API | API 鉴权 |
| Models | 查询公开模型 ID 和可用状态 | API 模型列表 |
| Generations | 提交异步图片、视频和音频任务 | 创建生成任务 |
| Files | 上传参考图片、视频或音频 | Files API |
| Chat | 发送非 streaming 或 streaming Chat turn | Chat API |
| Webhooks | 接收生成任务完成后的签名事件 | API Webhooks |
请求和响应结构以 API 文档为准。这篇文章只帮你判断应该先用哪一块。
积分怎么计算
API 调用使用和 Studio 相同的 Rivya 账户积分钱包。
也就是说，API 不是匿名模型代理。每个请求都属于一个 Rivya 账号，使用这个账号创建的 API Key，并遵守 API 积分 中描述的产品级积分边界。
这对团队很重要。你可以先在 Studio 里人工试模型，再把稳定下来的那部分接到 API，而不需要为计费、余额和失败处理另起一套系统。
Files API 什么时候需要
有些模型只靠文本输入就能运行。有些模型需要参考图片、视频或音频。
在 API 接入里，这类参考素材应该走 Files API。上传后会得到受管文件记录，再把它传入支持该参数的模型请求中。
实用规则是：
- 文本输入足够时，直接从生成任务端点开始
- 模型需要参考素材时，先上传文件
- Chat 模型需要图片附件时，使用 Chat API 和 file ID
不要把集成设计在只能通过浏览器上传、或只能依赖 Studio 已保存会话的路径上。API 有自己的公开文件边界。
Webhooks 适合放在哪里
轮询是最简单的首次接入路径。提交生成任务，保存公开任务 ID，然后查询到成功或失败。
当接入更接近生产流程时，Webhook 会更有价值：
- 不想让 worker 一直轮询每个任务
- 应用需要在生成完成后更新业务记录
- 需要一个可验签、可重试的完成事件
- 失败任务需要进入明确的恢复路径
签名事件合同请看 API Webhooks。接收端要保持克制：验签、处理重复事件，并避免把 secret 写进日志。
第一个 API 项目应该多小
第一个 API 项目最好小而具体。
可以按这个顺序：
- 在设置里创建 API Key
- 调用模型列表
- 选择一个可用模型
- 带幂等键提交一条生成任务
- 轮询状态接口
- 对比请求前后的积分
- 再决定是否加入 Files API、Chat API 或 Webhooks
这样可以先得到一个可工作的接入，不会在第一次测试里把所有 API 能力混在一起。
什么时候不该先用 API
下面这些情况，API 通常不是第一步：
- 团队还没选定模型类型
- 每次想要的输出都在变化
- 提示词高度依赖人工品味和复核
- 集成会让真正需要理解积分的人看不清消耗
- 产品还需要公开 demo，而不是后台自动化
这时先从 Image、Video、Audio、Chat 或 AI 模型 开始。等路径可重复后，再把稳定的部分搬到 API。
下一步看哪里
- 打开 Developers，先看公开 API 入口和调试器。
- 阅读 Rivya API 快速开始，跑通第一条安全请求。
- 把 Key 放到服务器前，先读 API 鉴权。
- 选择模型前，先读 API 模型列表。
- 如果还没判断该用 API 还是 Studio，读 什么时候该用 Rivya API，而不是 Studio？。
- 如果要规划完整接入，读 如何用 Rivya API 接入多模态 AI 工作流。
