# AI 生图、视频、配音 API 接口怎么接：一个接口生成图片、透明底图标、视频和语音
URL: https://www.rooyun.com/learn/rooyun-api-generate-media
更新于: 2026-11-05
文中价格按价格页实时显示（价目更新于 2026 年 11 月 5 日），以[价格页](https://www.rooyun.com/pricing)为准。

RooYun（如云）开放 API 用**一个生成接口** `POST /api/v1/generations` 覆盖 AI 生图（含透明底 PNG）、图生视频、文字转语音、音乐和音效：发一个请求拿到任务 id，等它完成后把文件下载回来。生成不需要先建项目或画布，按积分计费，提交前可以先报价。

适合这些场景：

- 给自己的 App 或网站批量做图标、插画、空状态图；
- 给小游戏生成角色立绘（透明底）、音效和背景音乐；
- 给内容工具接上配音、数字人口播或图生视频；
- 写个脚本，每天自动出一张配图或一段语音。

不想自己写代码，也可以让 Claude Code、Codex 这类智能体替你写，后面有说法。

![RooYun Agent 接入页：接进来之后 AI 能做什么，每项能力列出对应的 API 端点](https://api.rooyun.com/storage/v1/object/public/content-media/learn/a8a71e181611a080d2bfdd5495edc11b0c42b13b59eafe9942392e408cf8cb82.png)

## 一个接口能调哪些能力

生图、视频、配音都走同一个接口，用 `capability` 区分：

| capability | 做什么 | 必填参数（在 params 里） |
|---|---|---|
| `t2i` | 文生图；加 `transparentBackground: true` 出透明底 PNG | `prompt` |
| `i2i` | 图生图、编辑、放大、抠图 | `image`（源图的资产 id） |
| `i2v` | 图生视频 | `firstFrame` + `prompt` |
| `flf2v` | 首尾帧生视频 | `firstFrame` + `lastFrame` + `prompt` |
| `ref2v` | 参考图生视频（请求顶层带 `referenceAssetIds`） | `prompt` |
| `avatar` | 数字人口播 | `drivingAudio` + `firstFrame` |
| `t2a` | 配音 | `text` + `voiceId` 或 `voiceName` |
| `music` | 音乐 | `text`（风格描述），可选 `lyrics`、`instrumental` |
| `sfx` | 音效 | `text`，可选 `durationSec` |
| `upscale` | 视频高清 | `video` |

素材一律用资产 id 传：本地图片、音频先上传，换成资产 id 再用。

## 第一步：拿到 API 令牌

两种方式：

- **手动创建**：登录后到 [个人中心 → API 访问](https://www.rooyun.com/profile#api) 创建令牌，令牌以 `dj_pat_` 开头。可以只勾选需要的权限，并设一个消费上限。
- **让智能体授权**：装好 RooYun Skill 后让智能体运行 `dj login`，浏览器弹出授权页，点一次「授权」，令牌保存在本机 `~/.rooyun/credentials.json`。

验证令牌能用：

```bash
curl -s "https://www.rooyun.com/api/v1/me" -H "Authorization: Bearer $ROOYUN_TOKEN"
```

返回账号 id、令牌名、权限和已用额度，就说明鉴权通了。令牌只放在环境变量或服务端配置里，不要写进前端代码。

## 第二步：选模型，先报价（API 怎么收费）

![MCP 接入三步：创建 API 令牌、在 Claude Code 或 Cursor 里添加服务、让 AI 开工](https://api.rooyun.com/storage/v1/object/public/content-media/learn/e352e16b520811b6dce71aee24c825d455ee401d9372e48443c7c4dd453df1cc.png)

先查模型目录，看每个模型支持哪些能力、多少积分一次：

```bash
curl -s "https://www.rooyun.com/api/v1/models?capability=t2i" -H "Authorization: Bearer $ROOYUN_TOKEN"
```

提交前可以用 `POST /api/v1/generations/precheck` 预估这次要花多少积分、余额够不够，口径和网页上生成前显示的一致。

参考价格（1 元 = 1 积分，以生成前显示为准）：

| 用途 | 模型 | 价格 |
|---|---|---|
| 图标、透明底立绘 | Qwen-Image-2.1 · GPU | 每张 0.05 元 |
| 配音 | 自建配音 · VoxCPM2 | 每秒 0.02 元 |
| 音效 | 自建音效 · 文生音效 | 每次 0.024 元 |
| 背景音乐 | 自建音乐 · MiniMax-Music3 | 每首 0.1 元 |
| 图生视频 | MiniMax H3 · 文生视频 | 每秒 0.08 元 |

完整价目见 [价格页](https://www.rooyun.com/pricing)。

## 第三步：调用生图接口（以透明底图标为例）

```bash
curl -s -X POST "https://www.rooyun.com/api/v1/generations" \
  -H "Authorization: Bearer $ROOYUN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "8f14e45f-ceea-4672-9e5c-2a1b3c4d5e6f",
    "model": "<从模型目录里选的模型 id>",
    "capability": "t2i",
    "params": {
      "prompt": "一个圆角方形的天气 App 图标，太阳和云，扁平插画风格",
      "transparentBackground": true,
      "size": "1k"
    }
  }'
```

几个要点：

- **`requestId` 必填**，是 uuid 形态的幂等键。每笔生成新取一个并存下来；网络出错重试时复用同一个，不会重复扣费。
- **透明底要选支持的模型**：在模型目录里筛 `image.transparentBackground` 为 `true` 的模型，目前是 Qwen-Image-2.1。别的模型会静默忽略这个参数，出来的是普通图片。
- **画面里只写主体，不描述背景**，透明底交给参数，不用在提示词里写「透明背景」。
- 想让产物落到画布上的某张卡片，请求里加 `canvasId` 和 `nodeId`；不加就只进资产库。

## 第四步：查任务状态，下载文件

图生视频、文字转语音的调用方式一样，只是 `capability` 和 `params` 不同，例如配音用 `"capability": "t2a"`，`params` 里放 `text` 和 `voiceId`（音色先用 `GET /api/v1/voices` 查）。

下载步骤：提交后返回任务 id。用 `GET /api/v1/generations/{taskId}` 查状态，图片通常几秒到几十秒，视频要几分钟。完成后从任务结果里拿到资产 id，再用 `GET /api/v1/assets/{assetId}/download` 下载文件。

生成失败时积分会退回，任务结果里有失败原因：服务繁忙一类的失败，换一个新的 `requestId` 重提即可。

## 让智能体替你写接入代码

如果你用 Claude Code、Codex、Cursor，不用照着上面一行行写。把这句话发给它：

> 请阅读 https://www.rooyun.com/developers/llms.txt（RooYun 的 Agent 接入说明），按说明帮我把 RooYun 接上：安装 Skill、帮我登录授权，最后做一次连通检查。

接好后直接说需求，比如：

- 「给这个 App 的 12 个功能入口各生成一个透明底图标，统一扁平风格，先报价」；
- 「给这个小游戏生成跳跃、得分、失败三个音效，再配一段 30 秒的循环背景音乐」；
- 「写一个脚本，读 posts 目录里的文章，给每篇生成一张头图」。

智能体每次生成前会先报价，你确认了才提交。

![RooYun Agent 接入页方式一：复制一句话发给智能体，它自己装好 Skill 并请你点授权](https://api.rooyun.com/storage/v1/object/public/content-media/learn/3e0cac119da3416b469d150b7d8ba756144892b97b509bc4b2c7e2fb32e9e6ab.png)

## 有哪些限制

- **API 不拼成片**：视频是一镜一段，要拼成完整成片，用你自己的 ffmpeg，或在画布上点「合成成片」。
- **单个上传文件不超过 50MB**：大视频先压缩再上传。
- **生成会消耗积分**：建议给令牌设消费上限，额度用尽后新的生成会被拒绝，不会继续扣钱。

## 相关链接

- [Agent 接入说明](https://www.rooyun.com/developers)
- [用 Claude Code、Codex 等 AI Agent 自动做漫剧](https://www.rooyun.com/learn/agent-auto-manju)
- [Claude Code、Codex 能生成图片和视频吗](https://www.rooyun.com/learn/agent-fun-ai-projects)
- [价格页](https://www.rooyun.com/pricing)

## 常见问题

**必须先建项目和画布才能生成吗？** 不用。生成请求里的 canvasId、nodeId 是可选的：带上时产物落回画布上的卡片，不带时产物只进你的资产库，用资产下载接口取回。

**能生成透明底的图标和贴纸吗？** 能。文生图请求里传 params.transparentBackground: true，产物是带 alpha 通道的 PNG。目前只有部分模型支持，先在模型目录里筛 image.transparentBackground 为 true 的模型，其他模型会忽略这个参数。

**失败了会扣钱吗？重试会不会重复扣？** 生成失败会退回积分。每个生成请求要带一个 requestId（uuid 形态的幂等键），重试时复用同一个 requestId 不会重复扣费。

**怎么防止代码出错把余额花光？** 在个人中心 → API 访问给令牌设消费上限，额度用尽后新的生成会被拒绝。也可以去掉用不到的权限，或随时吊销令牌。