# 短剧工作流 API：从剧本到成片

> 用一个请求把剧本变成角色定妆图、分镜、首帧和视频片段。POST /v1/workflows/short-drama 自动完成剧本分析、分镜、出图和出片，每一步按所用模型计价。

网页版: https://bigmodel.io/zh-cn/docs/short-drama-workflow · 更新于 2026-10-18

`POST /v1/workflows/short-drama` 接收一段剧本，按顺序自动完成：

1. **提取角色**：识别剧本里的人物和动物，生成外观描述；
2. **拆分镜**：按场景拆成镜头，给出景别、运镜、画面、台词和音效，并按视频模型的时长上限把镜头打包成片段；
3. **角色定妆图**：每个角色一张全身设定图，用来保持角色在各个镜头里长得一样；
4. **首帧**：每个片段生成一张首帧，带上出场角色的定妆图作参考；
5. **视频片段**：用首帧和片段提示词生成视频，对白和音效写在提示词里，支持原生音频的模型会直接出声音。

整个流程是一个异步任务。你提交剧本拿到工作流 ID，之后轮询结果。每一步都是一个普通的生成任务，按所用模型的单价计费，费用会出现在控制台「日志」里；失败的步骤不收费。

不想写代码？可以看看 [AI 短剧方案](https://bigmodel.io/zh-cn/solutions/short-drama) 里的无代码工具。

## 先预估费用

```bash
curl https://bigmodel.io/v1/workflows/short-drama \
  -H "Authorization: Bearer $BIGMODEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"script": "第一场 雨夜 便利店门口……", "max_segments": 6, "dry_run": true}'
```

```json
{"object": "quote", "workflow": "short_drama", "max_segments": 6, "estimated_cost_usd": 4.24}
```

预估按 `max_segments` 个片段和典型片段时长计算，实际费用按实际生成的片段数和秒数结算，通常更低。

## 创建工作流

```bash [cURL]
curl https://bigmodel.io/v1/workflows/short-drama \
  -H "Authorization: Bearer $BIGMODEL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: episode-01" \
  -d '{
    "script": "第一场 雨夜 街角便利店 外\n林小满（二十岁，短发，黄色雨衣）抱着一只湿透的小狗跑进屋檐下。\n林小满：别怕，我们到家了。",
    "style": "温暖电影感，写实",
    "aspect_ratio": "9:16",
    "image_model": "qwen-image-2.1",
    "video_model": "seedance-2.0-fast",
    "max_segments": 6
  }'
```

```python [Python]
import os, time, requests

BASE = "https://bigmodel.io/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['BIGMODEL_API_KEY']}"}

wf = requests.post(f"{BASE}/workflows/short-drama", headers={**HEADERS, "Idempotency-Key": "episode-01"}, json={
    "script": open("episode-01.txt", encoding="utf-8").read(),
    "style": "温暖电影感，写实",
    "aspect_ratio": "9:16",
    "video_model": "seedance-2.0-fast",
    "max_segments": 6,
}).json()

while wf["status"] in ("queued", "running"):
    time.sleep(15)
    wf = requests.get(f"{BASE}/workflows/{wf['id']}", headers=HEADERS).json()
    print(wf["stage"], wf["progress"])

for seg in wf["segments"]:
    print(seg["title"], (seg["video"] or {}).get("url"))
print("total", wf["cost_usd"])
```

### 请求字段

| 字段 | 默认值 | 说明 |
|---|---|---|
| `script` | 必填 | 剧本正文，最多 20000 字。场景头、人物、动作和台词写得越清楚，分镜越准确。 |
| `style` | 空 | 画面风格，例如「温暖电影感，写实」「日系动画」。会加到定妆图、首帧的提示词里。 |
| `aspect_ratio` | `9:16` | `9:16`（竖屏短剧）、`16:9` 或 `1:1`。 |
| `image_model` | `qwen-image-2.1` | 生成定妆图和首帧的文生图模型。`qwen-image-2.1` 能把定妆图作为参考，角色一致性最好。 |
| `video_model` | `seedance-2.0-fast` | 生成片段的视频模型，必须支持图生视频。支持参考图的模型（如 `seedance-2.0` 系列、`minimax-h3`）会同时参考首帧和角色定妆图。 |
| `resolution` | 模型默认（通常 `720p`） | 必须是该视频模型支持的分辨率。 |
| `audio` | 模型默认 | 是否生成原生音频，仅支持音频的视频模型可用。 |
| `max_segments` | `6` | 最多生成多少个片段（1–20）。剧本更长时只做前面的片段。 |
| `stop_after` | `videos` | 提前结束：`storyboard`（只要角色和分镜）、`frames`（再加定妆图和首帧）、`videos`（完整流程）。 |
| `dry_run` | `false` | 只返回预估费用。 |

请求头 `Idempotency-Key` 可选：同一个值重复提交，返回同一个工作流。

## 查询进度和结果

`GET /v1/workflows/{id}` 返回：

```json
{
  "id": "e5d2c392-…",
  "object": "workflow.short_drama",
  "status": "running",
  "stage": "videos",
  "progress": {"clips_done": 1, "clips_total": 2},
  "estimated_cost_usd": 0.60,
  "cost_usd": 0.21,
  "characters": [
    {"name": "林小满", "look": "二十岁，短发，黄色雨衣……", "image": {"task_id": "…", "status": "succeeded", "url": "https://bigmodel.io/v1/media/…"}}
  ],
  "segments": [
    {
      "index": 1, "title": "镜01 · 全景", "scene": "雨夜 街角便利店", "seconds": 4, "cast": ["林小满", "小狗"],
      "picture": "店内暖光从右侧门玻璃透出……",
      "video_prompt": "【镜头1｜00:00-00:04】……",
      "frame": {"task_id": "…", "status": "succeeded", "url": "https://bigmodel.io/v1/media/…"},
      "video": {"task_id": "…", "status": "running"}
    }
  ],
  "storyboard": {"visualTone": "…", "scenes": [ … ]}
}
```

| 字段 | 说明 |
|---|---|
| `status` | `queued`、`running`、`succeeded`、`failed`、`canceled`。 |
| `stage` | 当前步骤：`characters`、`storyboard`、`character_images`、`frames`、`videos`、`done`。 |
| `characters[].image` | 角色定妆图任务。 |
| `segments[].frame`、`segments[].video` | 每个片段的首帧和视频任务。`url` 是 24 小时有效的签名链接，过期后重新查询即可。 |
| `storyboard` | 完整分镜：场景、镜头（景别、运镜、画面、台词音效、出场角色）。可以拿去自己重新组合。 |
| `cost_usd` | 已结算的费用，随步骤完成增加。 |

单个片段失败不会让整个工作流失败：首帧失败的片段不出视频，其他片段照常完成。只有全部首帧或全部视频都失败时，工作流才是 `failed`。

## 取消

```bash
curl -X POST https://bigmodel.io/v1/workflows/{id}/cancel -H "Authorization: Bearer $BIGMODEL_API_KEY"
```

已经完成的步骤照常计费，正在进行的生成会被取消，不收费。

## 用时与费用参考

| 步骤 | 用时（参考） | 计价 |
|---|---|---|
| 提取角色、拆分镜 | 1–3 分钟 | 每轮少量费用（通常不到 $0.05） |
| 定妆图、首帧 | 每张 20–60 秒，并行 | 图片模型单价 × 张数 |
| 视频片段 | 每段 1–5 分钟，并行 | 视频模型每秒单价 × 秒数 |

例如 6 个 5 秒片段、`seedance-2.0-fast`：视频约 30 秒，加上几张图和两轮分析，总价可以先用 `dry_run` 估算。

## 拼成完整一集

工作流输出的是按顺序排好的片段。把它们拼起来，可以用剪辑软件，也可以用 ffmpeg：

```bash
# 把 segments 的视频按顺序下载为 01.mp4、02.mp4 …
printf "file '%s'\n" *.mp4 > list.txt
ffmpeg -f concat -safe 0 -i list.txt -c copy episode.mp4
```

## 常见问题排查

| 现象 | 处理 |
|---|---|
| `400` script is required | `script` 为空。 |
| `400` video_model must be a video model that animates an image | 换一个支持图生视频的模型，见[模型目录 → 视频](https://bigmodel.io/zh-cn/models?type=Video)。 |
| `402` | 余额不足以覆盖预估费用。充值或减少 `max_segments`。 |
| `failed`，Script analysis failed | 剧本无法解析。补充场景头、人物和动作描写后重试。 |
| 角色前后不一致 | 用 `qwen-image-2.1` 作 `image_model`，并选择支持参考图的视频模型；在 `style` 里写清画风。 |

## 相关文档

- [多模态总览](https://bigmodel.io/zh-cn/docs/multimodal-overview)
- [视频生成](https://bigmodel.io/zh-cn/docs/video-generation)
- [图片生成](https://bigmodel.io/zh-cn/docs/image-generation)
- [多模态任务 API 参考](https://bigmodel.io/zh-cn/docs/api-media-tasks)