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

# 创建视频

> 使用 `POST /v1/video/generations` 提交 Seedance 2.0 多模态视频生成任务。

# 创建视频

提交 Seedance 2.0 视频生成任务，支持文生视频、首帧/首尾帧、参考图/视频/音频、视频延续、视频编辑与多模态合成等模式。素材库资产在 `content` 中推荐使用 `asset://{assetId}` 引用（见 [上传素材](./asset-create-media)）。

## 方法与路径

```http theme={null}
POST /v1/video/generations
```

## 请求示例

<CodeGroup>
  ```json 文生视频 theme={null}
  {
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {
        "type": "text",
        "text": "第一人称视角果茶广告：0-2秒 手摘苹果；2-4秒 切镜头投入雪克杯摇晃；4-6秒 倒入透明杯特写；6-8秒 举杯到镜头前"
      },
      {
        "type": "image_url",
        "image_url": { "url": "https://example.com/apple.jpg" },
        "role": "reference_image"
      },
      {
        "type": "image_url",
        "image_url": { "url": "https://example.com/cup.jpg" },
        "role": "reference_image"
      },
      {
        "type": "video_url",
        "video_url": { "url": "https://example.com/pov_reference.mp4" },
        "role": "reference_video"
      },
      {
        "type": "audio_url",
        "audio_url": { "url": "https://example.com/bgm.mp3" },
        "role": "reference_audio"
      }
    ],
    "metadata": {
      "duration": 8,
      "resolution": "720p",
      "ratio": "16:9",
      "generate_audio": true,
      "watermark": false
    }
  }
  ```

  ```json 首帧图生视频 theme={null}
  {
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {
        "type": "text",
        "text": "Animate naturally from the first frame"
      },
      {
        "type": "image_url",
        "image_url": { "url": "https://example.com/first.jpg" },
        "role": "first_frame"
      }
    ],
    "metadata": {
      "duration": 10,
      "resolution": "720p",
      "ratio": "adaptive"
    }
  }
  ```

  ```json 首尾帧生视频 theme={null}
  {
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {
        "type": "text",
        "text": "Smooth transition from first frame to last frame"
      },
      {
        "type": "image_url",
        "image_url": { "url": "https://example.com/first.jpg" },
        "role": "first_frame"
      },
      {
        "type": "image_url",
        "image_url": { "url": "https://example.com/last.jpg" },
        "role": "last_frame"
      }
    ],
    "metadata": {
      "duration": 5,
      "resolution": "720p",
      "ratio": "16:9"
    }
  }
  ```

  ```json 参考图生视频 theme={null}
  {
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {
        "type": "text",
        "text": "The subject walks forward naturally"
      },
      {
        "type": "image_url",
        "image_url": { "url": "https://example.com/character.jpg" },
        "role": "reference_image"
      }
    ],
    "metadata": {
      "duration": 10,
      "resolution": "720p",
      "ratio": "16:9"
    }
  }
  ```

  ```json 视频延续 theme={null}
  {
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {
        "type": "text",
        "text": "Continue the motion and style of the source video"
      },
      {
        "type": "video_url",
        "video_url": { "url": "https://example.com/source.mp4" },
        "role": "reference_video"
      }
    ],
    "metadata": {
      "duration": 8,
      "resolution": "720p",
      "ratio": "adaptive"
    }
  }
  ```

  ```json 视频编辑 theme={null}
  {
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {
        "type": "text",
        "text": "Replace product in video with product in image"
      },
      {
        "type": "video_url",
        "video_url": { "url": "https://example.com/source.mp4" },
        "role": "reference_video"
      },
      {
        "type": "image_url",
        "image_url": { "url": "https://example.com/product.jpg" },
        "role": "reference_image"
      }
    ],
    "metadata": {
      "duration": 8,
      "resolution": "720p",
      "ratio": "16:9",
      "return_last_frame": true
    }
  }
  ```

  ```json 多模态合成 theme={null}
  {
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {
        "type": "text",
        "text": "第一人称视角果茶广告"
      },
      {
        "type": "image_url",
        "image_url": { "url": "https://example.com/apple.jpg" },
        "role": "reference_image"
      },
      {
        "type": "image_url",
        "image_url": { "url": "https://example.com/cup.jpg" },
        "role": "reference_image"
      },
      {
        "type": "video_url",
        "video_url": { "url": "https://example.com/pov_reference.mp4" },
        "role": "reference_video"
      },
      {
        "type": "audio_url",
        "audio_url": { "url": "https://example.com/bgm.mp3" },
        "role": "reference_audio"
      }
    ],
    "metadata": {
      "duration": 8,
      "resolution": "720p",
      "ratio": "16:9",
      "generate_audio": true,
      "watermark": false
    }
  }
  ```

  ```json 引用素材 theme={null}
  {
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {
        "type": "text",
        "text": "第一人称视角果茶广告：0-2秒 手摘苹果；2-4秒 切镜头投入雪克杯摇晃；4-6秒 倒入透明杯特写；6-8秒 举杯到镜头前"
      },
      {
        "type": "image_url",
        "image_url": { "url": "asset://asset-xxx" },
        "role": "reference_image"
      },
      {
        "type": "image_url",
        "image_url": { "url": "asset://asset-xxx" },
        "role": "reference_image"
      },
      {
        "type": "video_url",
        "video_url": { "url": "asset://asset-xxx" },
        "role": "reference_video"
      },
      {
        "type": "audio_url",
        "audio_url": { "url": "asset://asset-xxx" },
        "role": "reference_audio"
      }
    ],
    "metadata": {
      "duration": 8,
      "resolution": "720p",
      "ratio": "16:9",
      "generate_audio": true,
      "watermark": false
    }
  }
  ```
</CodeGroup>

## 响应示例

<ResponseExample>
  ```json 200 theme={null}
  {
    "task_id": "cgt-20260412163502-x8k2m"
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "InvalidParameter",
      "message": "the parameter duration specified in the request is not valid",
      "type": "new_api_error"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": "Unauthorized",
      "message": "Invalid API key provided",
      "type": "new_api_error"
    }
  }
  ```

  ```json 403 theme={null}
  {
    "error": {
      "code": "Forbidden",
      "message": "access denied",
      "type": "new_api_error"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": "RateLimitExceeded",
      "message": "当前请求频率过高，请稍后再试",
      "type": "new_api_error"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "code": "InternalError",
      "message": "internal server error",
      "type": "new_api_error"
    }
  }
  ```
</ResponseExample>

提交后使用 [查询任务](./query) 轮询 `task_id`。

## 认证

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Body

<ParamField body="model" type="string" required>
  模型名称：

  * `doubao-seedance-2-0-260128`：标准版，追求最佳画质与复杂镜头调度
  * `doubao-seedance-2-0-fast-260128`：Fast 版，追求低延迟、成本敏感场景
</ParamField>

<ParamField body="content" type="array<object>" required>
  多模态输入数组，顺序影响角色分配。
</ParamField>

<ParamField body="content[].type" type="string" required>
  内容类型：`text`、`image_url`、`video_url`、`audio_url`、`draft_task`。
</ParamField>

<ParamField body="content[].text" type="string">
  当 `type=text` 时必填，提示词文本。
</ParamField>

<ParamField body="content[].image_url" type="object">
  当 `type=image_url` 时使用，须包含 `url`。
</ParamField>

<ParamField body="content[].image_url.url" type="string" required>
  图片公网 URL 或素材引用 `asset://{assetId}`。
</ParamField>

<ParamField body="content[].video_url" type="object">
  当 `type=video_url` 时使用，须包含 `url`。
</ParamField>

<ParamField body="content[].video_url.url" type="string" required>
  视频公网 URL 或 `asset://{assetId}`。
</ParamField>

<ParamField body="content[].audio_url" type="object">
  当 `type=audio_url` 时使用，须包含 `url`。
</ParamField>

<ParamField body="content[].audio_url.url" type="string" required>
  音频公网 URL 或 `asset://{assetId}`。
</ParamField>

<ParamField body="content[].draft_task" type="object">
  当 `type=draft_task` 时使用，须包含 `id`；且必须是 `content` 中唯一元素。
</ParamField>

<ParamField body="content[].draft_task.id" type="string" required>
  草稿任务 ID，用于基于草稿继续生成。
</ParamField>

<ParamField body="content[].role" type="string">
  媒体角色：

  * `first_frame`：首帧（图片）
  * `last_frame`：尾帧（图片）
  * `reference_image`：参考图
  * `reference_video`：参考/源视频（延续、编辑）
  * `reference_audio`：参考音频（须 `metadata.generate_audio=true`）
</ParamField>

<ParamField body="metadata" type="object">
  视频生成参数，均为可选。
</ParamField>

<ParamField body="metadata.duration" type="integer">
  视频时长（秒）。合法范围 `[4, 15]` 或 `-1`（由模型自动决定），默认 `5`。
</ParamField>

<ParamField body="metadata.resolution" type="string">
  分辨率：`480p`、`720p`、`1080p`，默认 `720p`。
</ParamField>

<ParamField body="metadata.ratio" type="string">
  宽高比：`16:9`、`9:16`、`1:1`、`4:3`、`adaptive`，默认 `16:9`。
</ParamField>

<ParamField body="metadata.frames" type="integer">
  视频总帧数。与 `duration` 二选一，传了 `frames` 时优先于 `duration`。
</ParamField>

<ParamField body="metadata.seed" type="integer">
  随机种子。相同 `seed` + 相同输入可得到相近结果。
</ParamField>

<ParamField body="metadata.camera_fixed" type="boolean">
  是否固定机位（抑制镜头运动），默认 `false`。
</ParamField>

<ParamField body="metadata.watermark" type="boolean">
  是否在视频右下角加水印，默认 `true`。
</ParamField>

<ParamField body="metadata.generate_audio" type="boolean">
  是否生成或合成音频。使用 `reference_audio` 时必须为 `true`，默认 `false`。
</ParamField>

<ParamField body="metadata.return_last_frame" type="boolean">
  是否返回末帧图片 URL，便于后续续写，默认 `false`。
</ParamField>

<ParamField body="metadata.draft" type="boolean">
  草稿模式：生成更快、质量略低，适合预览，默认 `false`。
</ParamField>

<ParamField body="metadata.service_tier" type="string">
  服务等级，默认 `default`。
</ParamField>

<ParamField body="metadata.execution_expires_after" type="integer">
  任务最长执行时间（秒），范围 `[3600, 259200]`（1 小时～3 天），默认 `172800`。
</ParamField>

<ParamField body="metadata.callback_url" type="string">
  任务完成时的回调 URL。
</ParamField>

## content 混用规则

违反以下规则可能返回 `400`：

* `reference_image` 不能与 `first_frame` / `last_frame` 同时出现
* `audio_url` 不能作为 `content` 中唯一输入，须至少搭配图片或视频
* `draft_task` 必须是 `content` 数组里的唯一元素

## 生成模式对照

| 模式     | 请求示例标签 | content 要点                                     |
| ------ | ------ | ---------------------------------------------- |
| 文生视频   | 文生视频   | `text` + 可选参考图/视频/音频                           |
| 首帧图生视频 | 首帧图生视频 | `text` + `first_frame`                         |
| 首尾帧生视频 | 首尾帧生视频 | `text` + `first_frame` + `last_frame`          |
| 参考图生视频 | 参考图生视频 | `text` + `reference_image`                     |
| 视频延续   | 视频延续   | `text` + `reference_video`                     |
| 视频编辑   | 视频编辑   | `text` + `reference_video` + `reference_image` |
| 多模态合成  | 多模态合成  | `text` + 多类型参考组合                               |
| 引用素材库  | 引用素材   | 各 URL 使用 `asset://{assetId}`                   |

## Response

<ResponseField name="task_id" type="string">
  任务 ID，用于 [查询任务](./query)。
</ResponseField>

## 相关页面

* [Seedance-2 概览](./overview)
* [查询任务](./query)
* [上传素材](./asset-create-media)