Rivya API 是什么？

当部署已启用 Public API，且你的账号具备访问权限时，Rivya API 就是从自有产品、脚本或工作流调用 Rivya 已支持模型能力的开发者契约。

它不是 Rivya Studio 之外的另一套产品。它仍然使用同一个账号边界、同一个积分钱包，以及用户在 Rivya 里看到的公开模型层。区别在于任务从哪里开始：不是人在 Studio 里点击操作，而是你的应用通过 API Key 发起请求。

如果你需要端点和请求字段，请从 Rivya API 总览 和 Rivya API 快速开始 读起。这篇文章只回答产品层问题：API 适合做什么、放在什么位置、什么时候不该一上来就用 API。

先用短句理解

Rivya API v1 允许符合条件的登录账号创建 API Key，并从网页界面之外调用支持 API 的 Rivya 模型能力。开发者页面描述的是已经实现的契约；请求能否实际运行，取决于当前部署、账号权限和模型就绪状态。

已实现的 API 能力包括：

• 通过 API 模型列表发现可调用模型

• 提交异步图片、视频和音频生成任务

• 为需要参考素材的模型使用 Files API 上传文件

• 通过公开任务 ID 查询生成状态

• 查询账户积分

• 调用 Chat API，包括可选 SSE streaming

• 部署已启用 webhook 时，为生成任务完成结果配置签名 webhook

• 使用仓库内 TypeScript SDK beta 封装部分调用

公开开发者入口是 Developers。如果你想先看整体能力、API Key 入口和安全调试方式，先从那里开始更顺。

Rivya 为什么需要 API

当人还在选模型、改提示词、看输出、决定下一步时，Studio 更适合。

当这件事已经变成可重复的产品流程或运营流程时，API 更适合。

在 API 访问已启用时，常见场景包括：

• 用户在你的产品里提交任务简报后，自动生成图片变体

• 营销流程根据结构化的营销活动输入生成视觉草稿

• 内部工具不经过浏览器，直接提交视频或音频任务

• 支持系统或内容系统想在自己的界面里调用一轮 Chat 模型

• 后端服务希望任务完成后收到签名回调

这些场景里，Rivya API 的价值是让模型选择、计费和任务状态仍然留在同一个 Rivya 账号体系里，而不是再搭一套分散链路。

API 不替代什么

API 不应该替代所有直接使用 Rivya 的理由。

下面这些情况更适合继续使用 Studio 或公开工作入口：

• 提示词还在探索

• 模型选择还不稳定

• 创作者需要肉眼比较输出

• 项目依赖保存历史和人工复核

• 团队还没决定哪种输入和输出值得自动化

工作流清楚到可以自动化时，再用 API。

这个边界很重要。模糊的创意问题通常先留在 Studio。输入和输出都比较稳定的产品流程，才适合搬到 API。

API 的主要组成

可以把 API 理解成 6 个互相连接的部分。

请求和响应结构以 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。围绕它设计前，先确认这项功能可用。接收端要保持克制：验签、处理重复事件，并避免把密钥写进日志。

第一个 API 项目应该多小

第一个 API 项目最好小而具体。

可以按这个顺序：

1. 确认部署和账号已启用 API 访问

2. 在设置里创建 API Key

3. 调用模型列表

4. 选择一个支持 API 的模型

5. 带幂等键提交一条生成任务

6. 轮询状态接口

7. 对比请求前后的积分

8. 再决定是否加入部署已开放的 Files API、Chat API 或 Webhooks

这样可以先得到一个可工作的接入，不会在第一次测试里把所有 API 能力混在一起。

什么时候不该先用 API

下面这些情况，API 通常不是第一步：

• 团队还没选定模型类型

• 每次想要的输出都在变化

• 提示词高度依赖人工品味和复核

• 集成会让真正需要理解积分的人看不清消耗

• 产品还需要公开演示，而不是后台自动化

这时先从 Image、Video、Audio、Chat 或 AI 模型 开始。等路径可重复后，再把稳定的部分搬到 API。

下一步看哪里

• 打开 Developers，先看公开 API 入口和调试器。

• 阅读 Rivya API 快速开始，跑通第一条安全请求。

• 把 Key 放到服务器前，先读 API 鉴权。

• 选择模型前，先读 API 模型列表。

• 如果还没判断该用 API 还是 Studio，读 什么时候该用 Rivya API，而不是 Studio？。

• 如果要规划完整接入，读 如何用 Rivya API 接入多模态 AI 工作流。