> ## Documentation Index
> Fetch the complete documentation index at: https://doc.xihuyun.com.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# Seedance 使用教程

> Seedance 视频生成使用教程

本文介绍 Seedance 2.0 系列模型在 AiSDK 上的常见调用方式，涵盖多模态参考、视频编辑、视频延长、4K 输出、Web Search 工具、虚拟数字人与授权真人素材等场景。示例统一使用 Python + AiSDK 网关域名。

## 环境准备

```bash theme={null}
pip install --upgrade openai
```

```python theme={null}
from openai import OpenAI

client = OpenAI(
    base_url="https://your-domain.com/v1",
    api_key="sk-xxx",  # 替换为你在 AiSDK 中申请的 Key
)
```

<Note>
  Seedance 视频生成属于**异步任务**：请求提交后返回 `task_id`，需轮询任务状态获取最终视频 URL。以下示例均使用 OpenAI SDK 直连 AiSDK 的 `/v1/video/generations` 与 `/v1/videos` 兼容接口。
</Note>

## 基础调用：文生视频

```python theme={null}
import time

# 1. 提交任务
task = client.post(
    "/video/generations",
    body={
        "model": "seedance-2.0-pro",
        "prompt": "一位穿红色连衣裙的女孩在海边奔跑，夕阳西下，电影感画面 --resolution 1080p --duration 5",
    },
    cast_to=object,
)
task_id = task["id"]
print("task_id:", task_id)

# 2. 轮询任务状态
while True:
    result = client.get(f"/video/generations/{task_id}", cast_to=object)
    status = result["status"]
    if status == "succeeded":
        print("video url:", result["content"][0]["video_url"]["url"])
        break
    if status == "failed":
        raise RuntimeError(result.get("error"))
    time.sleep(3)
```

**常用参数**（在 prompt 中通过 `--参数` 传入）：

| 参数              | 说明                                                  | 示例                   |
| --------------- | --------------------------------------------------- | -------------------- |
| `--resolution`  | 分辨率：480p / 720p / 1080p / 4k                        | `--resolution 1080p` |
| `--duration`    | 时长（秒）：5 / 10                                        | `--duration 5`       |
| `--ratio`       | 宽高比：16:9 / 9:16 / 1:1 / 4:3 / 3:4 / 21:9 / adaptive | `--ratio 16:9`       |
| `--fps`         | 帧率：24                                               | `--fps 24`           |
| `--watermark`   | 是否添加水印：true / false                                 | `--watermark false`  |
| `--seed`        | 随机种子                                                | `--seed 42`          |
| `--camerafixed` | 固定镜头：true / false                                   | `--camerafixed true` |

## 图生视频（首帧参考）

```python theme={null}
task = client.post(
    "/video/generations",
    body={
        "model": "seedance-2.0-pro",
        "content": [
            {"type": "text", "text": "女孩缓慢转头微笑，镜头轻微推近 --resolution 1080p --duration 5"},
            {"type": "image_url", "image_url": {"url": "https://your-cdn.com/portrait.jpg"}},
        ],
    },
    cast_to=object,
)
```

<Tip>
  `image_url` 支持 HTTPS 直链或 base64 data URL（`data:image/jpeg;base64,...`）。
</Tip>

## 多模态参考（图片 + 视频 + 音频）

Seedance 2.0 支持同时输入图片、视频、音频作为参考。使用 `@图片N` / `@视频N` / `@音频N` 在提示词中指代：

```python theme={null}
task = client.post(
    "/video/generations",
    body={
        "model": "seedance-2.0-pro",
        "content": [
            {
                "type": "text",
                "text": (
                    "参考 @图片1 中的女孩、@图片2 的宿舍场景、@视频1 的运镜，"
                    "生成女孩推门进入宿舍并与舍友对话的画面。"
                    "背景音乐参考 @音频1。 --resolution 1080p --duration 10"
                ),
            },
            {"type": "image_url", "image_url": {"url": "https://your-cdn.com/girl.jpg"}},
            {"type": "image_url", "image_url": {"url": "https://your-cdn.com/dorm.jpg"}},
            {"type": "video_url", "video_url": {"url": "https://your-cdn.com/camera-ref.mp4"}},
            {"type": "audio_url", "audio_url": {"url": "https://your-cdn.com/bgm.mp3"}},
        ],
    },
    cast_to=object,
)
```

**素材数量建议**：图片 ≤ 4 张，视频 ≤ 3 段，音频 ≤ 1 段。总时长（视频参考）不超过 15 秒。

## 视频编辑

对已有视频进行局部修改、元素增删、属性调整。**直接使用 `视频N` 指代**，不要写"参考视频N"：

```python theme={null}
task = client.post(
    "/video/generations",
    body={
        "model": "seedance-2.0-pro",
        "content": [
            {
                "type": "text",
                "text": "严格编辑 视频1，将其中女孩手里的香水替换为 图片1 中的面霜，动作和运镜保持不变。",
            },
            {"type": "video_url", "video_url": {"url": "https://your-cdn.com/source.mp4"}},
            {"type": "image_url", "image_url": {"url": "https://your-cdn.com/cream.jpg"}},
        ],
    },
    cast_to=object,
)
```

## 视频延长

在已有视频基础上向后（或向前）续写：

```python theme={null}
task = client.post(
    "/video/generations",
    body={
        "model": "seedance-2.0-pro",
        "content": [
            {
                "type": "text",
                "text": "向后延长 视频1，五个人终于全部到齐，围坐在桌边热烈聊天。 --duration 5",
            },
            {"type": "video_url", "video_url": {"url": "https://your-cdn.com/part1.mp4"}},
        ],
    },
    cast_to=object,
)
```

<Note>
  延长任务会自动截取衔接部分，原视频片段不会重复生成。
</Note>

## 4K 输出

```python theme={null}
task = client.post(
    "/video/generations",
    body={
        "model": "seedance-2.0-pro",
        "prompt": "延时摄影：城市夜景车流光轨，从傍晚过渡到深夜 --resolution 4k --duration 5",
    },
    cast_to=object,
)
```

<Warning>
  4K 生成耗时和计费明显高于 1080p，请根据实际需求选用。
</Warning>

## Web Search 工具（联网参考）

在生成前让模型联网搜索最新素材，用于时事、明星（需授权）、新品发布等场景：

```python theme={null}
task = client.post(
    "/video/generations",
    body={
        "model": "seedance-2.0-pro",
        "prompt": "根据最近发布的新品手机外观，生成一段产品旋转展示视频",
        "tools": [{"type": "web_search"}],
    },
    cast_to=object,
)
```

## 虚拟数字人

通过参考图（数字人形象）+ 音频（台词）驱动虚拟人开口说话：

```python theme={null}
task = client.post(
    "/video/generations",
    body={
        "model": "seedance-2.0-pro",
        "content": [
            {
                "type": "text",
                "text": "让 图片1 中的数字人正对镜头，按 音频1 的内容自然口播，表情自然，中景。",
            },
            {"type": "image_url", "image_url": {"url": "https://your-cdn.com/avatar.jpg"}},
            {"type": "audio_url", "audio_url": {"url": "https://your-cdn.com/script.mp3"}},
        ],
    },
    cast_to=object,
)
```

## 授权真人素材

如需使用真人（明星、KOL、员工）形象，必须在请求中声明已获得肖像授权：

```python theme={null}
task = client.post(
    "/video/generations",
    body={
        "model": "seedance-2.0-pro",
        "content": [
            {"type": "text", "text": "让 图片1 中的人物在演播厅内进行产品介绍口播。"},
            {"type": "image_url", "image_url": {"url": "https://your-cdn.com/authorized-person.jpg"}},
        ],
        "extra_body": {
            "portrait_authorized": True,
            "authorization_id": "your-authorization-id",
        },
    },
    cast_to=object,
)
```

<Warning>
  未获得授权使用真人素材将被上游安全策略拦截。请确保授权凭证真实有效。
</Warning>

## 任务查询与取消

```python theme={null}
# 查询任务
result = client.get(f"/video/generations/{task_id}", cast_to=object)

# 取消任务（仅在 queued / running 状态可取消）
client.delete(f"/video/generations/{task_id}", cast_to=object)
```

**任务状态**：

| 状态          | 说明                                  |
| ----------- | ----------------------------------- |
| `queued`    | 排队中                                 |
| `running`   | 生成中                                 |
| `succeeded` | 成功，`content[0].video_url.url` 为视频地址 |
| `failed`    | 失败，见 `error` 字段                     |
| `cancelled` | 已取消                                 |

<Note>
  视频 URL 有效期通常为 24 小时，请及时下载或转存到自有存储。
</Note>

## 计费说明

Seedance 按**分辨率 × 时长**计费，具体单价请以 AiSDK 后台"模型价格"页面为准。视频延长与编辑任务按最终输出时长计费。

## 常见问题

**Q：任务一直是 running 怎么办？** A：Seedance 单任务通常 1–5 分钟，4K 任务可能需要 5–15 分钟。若超过 20 分钟仍未完成，请提交工单。

**Q：视频链接打不开？** A：链接是临时签名 URL，通常 24 小时后失效。建议生成后立即下载。

**Q：能否用 OpenAI Python SDK 的 `videos.generate` 方法？** A：可以。AiSDK 完全兼容 OpenAI 的 `/v1/videos` 接口，同样返回 `task_id`，查询与轮询逻辑一致。