# API 体系输出规则

## 目标

把每个分镜片段从“给人看的提示词”升级为“可交给程序调用的请求规格”。

每个视频片段必须输出：

1. 资产映射：内部引用 → 文件路径/URL/asset URI。
2. 官网提示词：适合在网页端 @ 已上传图片。
3. API 提示词：适合在请求体中引用图片输入。
4. API 请求体草案：JSON 或 JSONL。
5. 任务参数：模型、时长、分辨率、比例、回调地址占位。

## 火山方舟/Seedance 官方能力要点

根据火山方舟官方文档：

- 视频生成 API 是异步任务，通常需要先创建任务，再查询结果或接收回调。
- 输入 `content` 支持文本、图片等信息；公开模型能力强调音频、视频、图片、文本均可作为参考。
- 可信素材/真人素材可使用 `asset://<asset_id>` URI，并在 `content` 中以 `role: "reference_image"` 传入。
- 真人素材入库有格式和一致性校验要求，建议正面清晰图。
- 单条任务的文本提示词要写明参考职责，例如“参考图1锁定角色外貌，不参考图中背景；参考图2锁定场景空间”。
- 如果平台或接口支持首帧、尾帧、返回最后一帧或视频延展，连续短剧优先用上一段尾帧作为下一段首帧参考。

参考：

- `https://www.volcengine.com/docs/82379/1520757`
- `https://www.volcengine.com/docs/82379/2315856`
- `https://www.volcengine.com/docs/6492/2165104`

## 资产 URI 类型

| 类型 | 示例 | 适用 |
| --- | --- | --- |
| 公网 URL | `https://cdn.example.com/jiang-shangli.png` | 普通参考图 |
| 火山资产 | `asset://asset-20260222234430-mxpgh` | 可信素材库/真人素材/虚拟人像 |
| 本地文件 | `assets/characters/jiang.png` | 仅用于清单，不可直接提交 API |

本地文件必须先上传到对象存储、CDN、火山素材库或 Files API，变成 URL/asset URI 后才能进入视频 API。

## 官网 @ 上传图片写法

如果官网支持对已上传图片直接 `@`，提示词应该写成：

```text
@姜尚离_百姓装 @霍念_粗布农夫 @伯府狗洞_泥地
自然克制的真实演员表演。姜尚离从狗洞外泥地站起，先低头看自己沾泥的指节，停半秒，再看向霍念……
```

要求：

- 输出“官网上传名”，也就是用户上传图片后在官网里给图片/素材起的名字。
- `@` 后的名字要和官网素材名一致，不要只使用内部引用。
- 同一角色跨片段使用同一个上传名。

## API content 草案

火山方舟文档中的素材引用形态类似：

```json
{
  "type": "image_url",
  "image_url": {
    "url": "asset://asset-20260222234430-mxpgh"
  },
  "role": "reference_image"
}
```

## 上传后二次生成硬约束

`10_接口请求体.jsonl` 不能在图片上传前定稿。上传脚本完成后，AI 必须重新读取全局 `09_接口资产清单.md`，用其中真实可用的 `公网URL` 或 `asset://` URI 重新生成每集 JSONL。

硬性要求：

- `@角色名`、`@场景名`、`@道具名` 只允许出现在文本说明、`source_ref` 或官网 Prompt 中，不能作为 API 图片输入。
- API 图片输入必须写进 `content` 数组，字段形态为 `{"type":"image_url","image_url":{"url":"https://..."},"role":"reference_image"}`。
- `image_url.url` 只能是 `https://...`、`http://...` 或 `asset://...`。不能是本地路径、`pending_upload`、`replace-with-uploaded-url`、空字符串或纯 `@素材名`。
- 文本中的“参考图1/图2/图3”必须和 `content` 中图片对象顺序一致。
- 资产未上传成功时，不要把它写入 `content[].image_url`；在同一 JSON 行增加 `asset_warnings`，列出缺失资产和状态。
- 如果某个角色/场景在分集 `04_资产引用.md` 中出现，但 `10_接口请求体.jsonl` 没有对应图片 URL 或明确 `asset_warnings`，该集不合格。

建议每个片段生成如下草案。具体字段以你账号控制台文档为准：

```json
{
  "model": "doubao-seedance-2-0-pro",
  "content": [
    {
      "type": "text",
      "text": "参考图1锁定姜尚离外貌、发型和服装，不参考图中背景；参考图2锁定霍念外貌和服装；参考图3锁定伯府狗洞场景空间、泥地材质和冷天光。中景，姜尚离从狗洞外泥地站起，12s，9:16，电影级写实。首帧……镜头……时间节拍：0-3s 动作；3-7s 姜尚离低声说“我自己来”；7-12s 霍念听见后停半秒。对白/口型/表演：Seedance 生成姜尚离同期对白“我自己来”，声音很低，语速慢，口型自然，霍念无对白。声音：屋外轻微风声，木桌轻响，无VO，无背景音乐。尾帧……约束：不要字幕，不要把对白文字显示在画面里，不要水印，不要变脸，不要新增人物，不要多余旁白。"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "asset://asset-xxxx-jiang-shangli"
      },
      "role": "reference_image"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "asset://asset-xxxx-huo-nian"
      },
      "role": "reference_image"
    }
  ],
  "parameters": {
    "duration": 12,
    "resolution": "720p",
    "aspect_ratio": "9:16",
    "return_last_frame": true
  },
  "callback_url": "https://your-domain.com/seedance/callback"
}
```

`return_last_frame` 只是连续性占位字段，只有账号实际接口支持时才保留；如果接口字段名不同，按控制台文档替换。

## 输出文件

每集新增两个文件：

- `09_官网提示词.md`：官网 @ 上传图片版提示词。
- `10_接口请求体.jsonl`：每行一个视频生成任务 JSON 草案。

全剧新增：

- `09_接口资产清单.md`：所有资产的文件名、URL、asset URI、官网上传名。
- 如需批量执行计划，可另行输出 `10_接口批处理计划.md` 或放入项目级执行文档；不得占用分集 `10_接口请求体.jsonl` 命名。