# 多模态任务与工作流 API 参考

> BigModel.io 图片、视频、数字人、配音、音乐、音效与短剧工作流接口的完整参考：请求字段、任务对象、状态、错误码和计费规则。

网页版: https://bigmodel.io/zh-cn/docs/api-media-tasks · 更新于 2026-10-18

所有接口都使用 `Authorization: Bearer $BIGMODEL_API_KEY`，Base URL 为 `https://bigmodel.io/v1`。

## 接口一览

| 方法 | 路径 | 说明 |
|---|---|---|
| `POST` | `/v1/images/generations` | 文生图，同步返回 |
| `POST` | `/v1/images/edits` | 改图、放大、抠图，同步返回（multipart 或 JSON） |
| `POST` | `/v1/videos` | 创建视频、数字人或视频工具任务 |
| `GET` | `/v1/videos/{id}` | 查询任务 |
| `GET` | `/v1/videos/{id}/content` | 跳转到产物（302） |
| `POST` | `/v1/videos/{id}/cancel` | 取消任务 |
| `POST` | `/v1/audio/speech` | 配音，成功时直接返回音频字节 |
| `GET` | `/v1/audio/voices` | 系统音色列表 |
| `POST` | `/v1/audio/generations` | 创建音乐、音效或音频工具任务 |
| `GET` | `/v1/audio/generations/{id}` | 查询任务 |
| `GET` | `/v1/audio/generations/{id}/content` | 跳转到产物（302） |
| `POST` | `/v1/audio/generations/{id}/cancel` | 取消任务 |
| `POST` | `/v1/workflows/short-drama` | 创建短剧工作流 |
| `GET` | `/v1/workflows/{id}` | 查询工作流 |
| `POST` | `/v1/workflows/{id}/cancel` | 取消工作流 |

## 通用请求头

| 请求头 | 说明 |
|---|---|
| `Idempotency-Key` | 可选，最长 200 字符。同一个 Key 和同一个值重复提交，返回第一次创建的任务，不会重复生成和扣费。 |
| `Content-Type: application/json` | 创建类接口使用 JSON。素材以 `https://` 链接或 base64 data URI 传入，请求体最大 80 MB（工作流 1 MB）。 |

## 任务字段（创建请求）

| 字段 | 适用 | 说明 |
|---|---|---|
| `model` | 全部 | 必填，模型 ID。 |
| `prompt` | 视频、数字人、音乐、音效 | 文字描述。音乐的风格、音效的描述也写在这里。 |
| `image` / `first_frame` | 视频、数字人 | 首帧或人物图片。视频模型必填。 |
| `last_frame` | 视频 | 尾帧，仅支持首尾帧的模型。 |
| `reference_images`、`reference_videos`、`reference_audios` | 视频 | 参考素材数组，仅支持参考输入的模型。 |
| `seconds` / `duration` | 视频、音效 | 输出时长（秒），在模型允许的范围内，默认 5。 |
| `resolution` | 视频 | 例如 `480p`、`720p`、`1080p`、`2k`、`4k`，取决于模型。 |
| `aspect_ratio` / `size` | 视频 | `16:9`、`9:16`、`1:1`，或 `1280x720` 这样的尺寸。 |
| `audio` | 视频 | 是否生成原生音频，仅支持的模型。 |
| `seed` | 视频 | 随机种子。 |
| `video` | 数字人、视频工具、音频工具 | 源视频或动作视频。 |
| `input_audio` | 数字人 | 驱动口型的配音或歌曲。 |
| `target_resolution` | 视频放大 | `1080p`（默认）或 `2k`。 |
| `mode` | 转白模 | `clay`、`clay_masked`（默认）、`sculpt`。 |
| `keep_audio` | 转白模 | 是否保留源视频音轨。 |
| `isolate_voice`、`transcribe` | 抽音轨 | 分离人声；输出转写文字。 |
| `input` | 配音 | 要朗读的文字，最多 4000 字。 |
| `voice` | 配音 | 音色 ID，见 `GET /v1/audio/voices`。 |
| `speed` | 配音 | 语速，0.5–2。 |
| `emotion` | 配音 | `happy`、`sad`、`angry`、`fearful`、`disgusted`、`surprised`、`calm`、`fluent`、`whisper`。 |
| `lyrics`、`instrumental` | 音乐 | 歌词；是否纯音乐。 |
| `dry_run` | 全部创建接口 | `true` 时只返回预估费用，不生成。 |

## 任务对象

```json
{
  "id": "9abb6ad1-167a-43b2-a4cd-95c712c11969",
  "object": "video",
  "model": "seedance-2.0-mini",
  "status": "succeeded",
  "progress": 100,
  "created_at": 1760000000,
  "completed_at": 1760000111,
  "estimated_cost_usd": 0.0823,
  "cost_usd": 0.0823,
  "output": {"type": "video", "url": "https://bigmodel.io/v1/media/…", "expires_in": 86400}
}
```

| 字段 | 说明 |
|---|---|
| `object` | `video` 或 `audio.generation`。 |
| `status` | `queued`、`running`、`succeeded`、`failed`、`canceled`。 |
| `progress` | 0–100，部分模型在运行中提供。 |
| `estimated_cost_usd` | 创建时预留的预估费用。 |
| `cost_usd` | 结算后的实际费用，仅成功任务有。 |
| `output.url` | 产物签名链接，24 小时有效；过期后重新查询任务获取新链接。 |
| `error.message` | 失败原因。 |

`POST /v1/audio/speech` 成功时直接返回音频（`Content-Type: audio/mpeg`），响应头 `X-Task-Id` 是对应的任务 ID。超过 85 秒还没完成时返回 `202` 和任务对象，之后用 `GET /v1/audio/generations/{id}` 查询。

## 预估费用（dry_run）

```json
{"object": "quote", "model": "seedance-2.0", "unit": "per_second", "estimated_units": 10, "estimated_cost_usd": 0.66}
```

## 工作流

请求字段和结果对象见[短剧工作流](https://bigmodel.io/zh-cn/docs/short-drama-workflow)。

## 错误

| 状态码 | `error.type` | 含义 |
|---|---|---|
| `400` | `invalid_request_error` | 参数不符合模型要求，`message` 说明原因。 |
| `401` | `authentication_error` | Key 无效。 |
| `402` | `insufficient_balance` | 余额不足以覆盖预估费用（含未完成任务的预留）。 |
| `404` | `model_not_available` | 该 Key 所在分组不提供此模型，或模型不属于这个接口。 |
| `404` | `not_found_error` | 任务不存在或不属于你。 |
| `409` | `not_ready` | 请求产物时任务尚未完成。 |
| `503` | `api_error` | 暂时不可用，稍后重试；带 `Idempotency-Key` 重试是安全的。 |

## 计费规则

- 图片按成功返回的张数计费。
- 视频、数字人、视频工具按输出秒数计费；配音按字符数或音频秒数；音乐、音效按次；抽音轨按视频秒数。
- 任务成功后结算并写入控制台「日志」；失败、取消的任务不收费。
- 创建时预留预估费用，余额减去所有未完成任务的预留后不足时返回 `402`。

## 相关文档

- [多模态总览](https://bigmodel.io/zh-cn/docs/multimodal-overview)
- [短剧工作流](https://bigmodel.io/zh-cn/docs/short-drama-workflow)