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

# Seedance 2.0 创建视频任务

> 使用 `POST /v1/videos` 创建 Seedance 2.0 异步视频生成任务。

# Seedance 2.0 创建视频任务

Seedance 2.0 视频生成接口用于提交文生视频、首帧生视频、首尾帧生视频和参考素材生成任务。

* 异步处理模式，提交成功后返回视频任务 ID。
* 支持 `doubao-seedance-2-0-260128`、`doubao-seedance-2-0-fast-260128`。
* 使用 `application/json` 提交；素材字段传公网 URL 或 `asset://{asset_id}`。
* 支持首帧图、尾帧图、参考图、参考视频和参考音频 URL。
* `last_image` 必须和 `first_image` 同时传入。

## 方法与路径

```http theme={null}
POST /v1/videos
```

<RequestExample>
  ```bash 文生视频 cURL theme={null}
  curl -X POST https://magic666.top/v1/videos \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "doubao-seedance-2-0-260128",
      "prompt": "雨夜街头，一位穿红色雨衣的女孩慢跑，镜头缓慢跟拍，电影感光影",
      "duration": 6,
      "aspect_ratio": "16:9",
      "resolution": "720P",
      "watermark": false
    }'
  ```

  ```bash 首帧生视频 cURL theme={null}
  curl -X POST https://magic666.top/v1/videos \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "doubao-seedance-2-0-fast-260128",
      "prompt": "让画面中的人物自然转身，看向镜头并微笑，背景灯光轻微闪烁",
      "duration": 5,
      "aspect_ratio": "9:16",
      "first_image": "https://example.com/assets/first-frame.png"
    }'
  ```

  ```bash 首尾帧生视频 cURL theme={null}
  curl -X POST https://magic666.top/v1/videos \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "doubao-seedance-2-0-260128",
      "prompt": "从首帧自然过渡到尾帧，保持人物服装和场景一致，动作连贯",
      "duration": 6,
      "aspect_ratio": "16:9",
      "first_image": "https://example.com/assets/opening-frame.png",
      "last_image": "https://example.com/assets/ending-frame.png"
    }'
  ```

  ```bash 多参考素材 cURL theme={null}
  curl -X POST https://magic666.top/v1/videos \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "doubao-seedance-2-0-260128",
      "prompt": "参考图片中的产品外观、参考视频的镜头运动，并使用参考音频作为背景音乐，生成广告感短视频",
      "duration": 6,
      "aspect_ratio": "16:9",
      "reference_image_urls": [
        "https://example.com/assets/product-front.png",
        "https://example.com/assets/product-side.png"
      ],
      "reference_video_urls": [
        "https://example.com/assets/camera-motion.mp4"
      ],
      "reference_audio_urls": [
        "https://example.com/assets/background-music.mp3"
      ],
      "generate_audio": true
    }'
  ```

  ```bash 单个参考视频和音频 cURL theme={null}
  curl -X POST https://magic666.top/v1/videos \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "doubao-seedance-2-0-260128",
      "prompt": "参考视频的运动节奏和音频情绪，生成一段自然真实的短片",
      "duration": 8,
      "aspect_ratio": "16:9",
      "reference_video_url": "https://example.com/assets/motion.mp4",
      "audio_url": "https://example.com/assets/voice.mp3",
      "generate_audio": true
    }'
  ```

  ```python Python theme={null}
  import requests

  resp = requests.post(
      "https://magic666.top/v1/videos",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      json={
          "model": "doubao-seedance-2-0-260128",
          "prompt": "雨夜街头，一位穿红色雨衣的女孩慢跑，镜头缓慢跟拍，电影感光影",
          "duration": 6,
          "aspect_ratio": "16:9",
          "resolution": "720P",
          "watermark": False,
      },
      timeout=60,
  )

  print(resp.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://magic666.top/v1/videos", {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "doubao-seedance-2-0-260128",
      prompt: "雨夜街头，一位穿红色雨衣的女孩慢跑，镜头缓慢跟拍，电影感光影",
      duration: 6,
      aspect_ratio: "16:9",
      resolution: "720P",
      watermark: false,
    }),
  });

  console.log(await response.json());
  ```

  ```go Go theme={null}
  package main

  import (
  	"bytes"
  	"encoding/json"
  	"fmt"
  	"io"
  	"net/http"
  )

  func main() {
  	payload := map[string]any{
  		"model":        "doubao-seedance-2-0-260128",
  		"prompt":       "雨夜街头，一位穿红色雨衣的女孩慢跑，镜头缓慢跟拍，电影感光影",
  		"duration":     6,
  		"aspect_ratio": "16:9",
  		"resolution":   "720P",
  		"watermark":    false,
  	}

  	body, err := json.Marshal(payload)
  	if err != nil {
  		panic(err)
  	}

  	req, err := http.NewRequest("POST", "https://magic666.top/v1/videos", bytes.NewReader(body))
  	if err != nil {
  		panic(err)
  	}
  	req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
  	req.Header.Set("Content-Type", "application/json")

  	resp, err := http.DefaultClient.Do(req)
  	if err != nil {
  		panic(err)
  	}
  	defer resp.Body.Close()

  	respBody, err := io.ReadAll(resp.Body)
  	if err != nil {
  		panic(err)
  	}
  	fmt.Println(string(respBody))
  }
  ```
</RequestExample>

## 文件 URL 与素材引用

Seedance 2.0 的素材字段只接收 URL 字符串，不直接接收二进制文件。使用本地图片、视频或音频时，先把文件上传到服务端可访问的公网 URL，再填入对应字段；也可以先调用 [创建素材](./asset-create-media)，再用 `asset://{asset_id}` 引用素材。

通过素材接口得到的 `Result.Id` 是裸素材 ID，例如 `asset-20260528143012-a8x7k`。在视频生成请求中引用它时，需要加上 `asset://` 前缀：

```text theme={null}
asset://asset-20260528143012-a8x7k
```

查询素材状态时仍然使用裸素材 ID：

```http theme={null}
GET /api/asset/get?id=asset-20260528143012-a8x7k
```

支持 `asset://{asset_id}` 的字段：

| 字段                     | 用途          | 示例                                                               |
| ---------------------- | ----------- | ---------------------------------------------------------------- |
| `first_image`          | 首帧图         | `"first_image": "asset://asset-20260528143012-a8x7k"`            |
| `last_image`           | 尾帧图         | `"last_image": "asset://asset-20260528143351-b2n6q"`             |
| `reference_image_urls` | 多张参考图       | `"reference_image_urls": ["asset://asset-20260528143012-a8x7k"]` |
| `reference_video_url`  | 单个参考视频      | `"reference_video_url": "asset://asset-20260528143708-k9m2p"`    |
| `reference_video_urls` | 多个参考视频      | `"reference_video_urls": ["asset://asset-20260528143708-k9m2p"]` |
| `reference_audios`     | 参考音频数组      | `"reference_audios": ["asset://asset-20260528144123-r4s6n"]`     |
| `reference_audio_urls` | 参考音频 URL 数组 | `"reference_audio_urls": ["asset://asset-20260528144123-r4s6n"]` |
| `audio_url`            | 单个参考音频      | `"audio_url": "asset://asset-20260528144123-r4s6n"`              |

<Tip>
  使用素材 ID 前，建议先调用 `GET /api/asset/get`，确认 `Result.Status` 已经变为 `Active`。
</Tip>

## 响应示例

<ResponseExample>
  ```json 200 - 视频任务已提交 theme={null}
  {
    "id": "task_01jz8s3dbke8p9vq2m8r9a7gk4",
    "object": "video",
    "created": 1790557800,
    "model": "doubao-seedance-2-0-260128",
    "status": "queued"
  }
  ```

  ```json 400 - 缺少提示词 theme={null}
  {
    "code": "invalid_request",
    "message": "prompt is required"
  }
  ```

  ```json 401 - 未提供有效 API Key theme={null}
  {
    "error": {
      "message": "无效的令牌",
      "type": "invalid_request_error"
    }
  }
  ```

  ```json 402 - 额度不足 theme={null}
  {
    "error": {
      "message": "余额不足",
      "type": "insufficient_quota"
    }
  }
  ```

  ```json 429 - 请求过于频繁 theme={null}
  {
    "error": {
      "message": "rate limit exceeded",
      "type": "rate_limit_exceeded"
    }
  }
  ```

  ```json 500 - 上游请求失败 theme={null}
  {
    "code": "do_request_failed",
    "message": "upstream request failed"
  }
  ```
</ResponseExample>

## 认证

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

## Body

<ParamField body="model" type="string" required>
  模型名称。支持标准档 `doubao-seedance-2-0-260128` 和 fast 档 `doubao-seedance-2-0-fast-260128`。
</ParamField>

<ParamField body="prompt" type="string" required>
  视频生成提示词。
</ParamField>

<ParamField body="duration" type="number">
  视频时长，单位秒。当前推荐使用该字段传入时长。
</ParamField>

<ParamField body="aspect_ratio" type="string">
  画幅比例。支持 `21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`。
</ParamField>

<ParamField body="size" type="string">
  固定输出尺寸，例如 `1280x720`。该字段只接收固定尺寸，不接收 `16:9` 这类比例写法。
</ParamField>

<ParamField body="resolution" type="string">
  输出清晰度，例如 `480P`、`720P`、`1080P`。具体可用值以模型档位为准。
</ParamField>

<ParamField body="watermark" type="boolean">
  是否添加水印。
</ParamField>

<ParamField body="generate_audio" type="boolean">
  是否启用音频生成或音频参考。传 `true` 时可同时提供 `reference_audios`、`reference_audio_urls` 或 `audio_url`。
</ParamField>

<ParamField body="first_image" type="string">
  首帧图 URL 或素材引用 URI。可以传公网 URL，也可以传 `asset://asset-20260528143012-a8x7k`。
</ParamField>

<ParamField body="last_image" type="string">
  尾帧图 URL 或素材引用 URI。必须和 `first_image` 同时使用。
</ParamField>

<ParamField body="reference_image_urls" type="array<string>">
  参考图片 URL 或素材引用 URI 数组。适合传入主体、风格或产品参考图。
</ParamField>

<ParamField body="reference_video_url" type="string">
  单个参考视频 URL 或素材引用 URI。
</ParamField>

<ParamField body="reference_video_urls" type="array<string>">
  多个参考视频 URL 或素材引用 URI。适合传入镜头运动或动作参考。
</ParamField>

<ParamField body="reference_audios" type="array<string>">
  参考音频 URL 或素材引用 URI 数组。
</ParamField>

<ParamField body="reference_audio_urls" type="array<string>">
  参考音频 URL 或素材引用 URI 数组。
</ParamField>

<ParamField body="audio_url" type="string">
  单个参考音频 URL 或素材引用 URI。
</ParamField>

## Response

<ResponseField name="id" type="string">
  视频任务 ID。后续用 `GET /v1/videos/{id}` 查询结果。
</ResponseField>

<ResponseField name="object" type="string">
  对象类型，通常为 `video`。
</ResponseField>

<ResponseField name="created" type="integer">
  任务创建时间戳。
</ResponseField>

<ResponseField name="model" type="string">
  本次任务使用的模型。
</ResponseField>

<ResponseField name="status" type="string">
  任务状态。常见值为 `queued`、`in_progress`、`completed`、`failed`。
</ResponseField>

<ResponseField name="video_url" type="string">
  任务完成后的公开视频 URL。提交阶段通常为空，查询完成任务时返回。
</ResponseField>

<ResponseField name="actualDuration" type="integer">
  实际生成的视频时长。上游返回该字段时透出。
</ResponseField>

<ResponseField name="totalTokens" type="integer">
  任务计费用量。上游返回该字段时透出。
</ResponseField>

<ResponseField name="error" type="string">
  任务失败原因。
</ResponseField>

## 使用场景

### 文生视频

只传 `model`、`prompt`、`duration` 和 `aspect_ratio`，适合从纯文本生成视频。

```json theme={null}
{
  "model": "doubao-seedance-2-0-fast-260128",
  "prompt": "清晨海边，航拍镜头掠过浪花，阳光穿过薄雾",
  "duration": 5,
  "aspect_ratio": "16:9"
}
```

### 首帧生视频

传入 `first_image`，让静态图中的主体动起来。

```json theme={null}
{
  "model": "doubao-seedance-2-0-260128",
  "prompt": "让人物自然抬头，微笑，看向镜头",
  "duration": 6,
  "aspect_ratio": "9:16",
  "first_image": "https://example.com/assets/person-first-frame.png"
}
```

### 首尾帧生视频

同时传入 `first_image` 和 `last_image`，用于约束视频开头和结尾。

```json theme={null}
{
  "model": "doubao-seedance-2-0-260128",
  "prompt": "从首帧自然过渡到尾帧，保持人物身份和场景连续",
  "duration": 6,
  "aspect_ratio": "16:9",
  "first_image": "https://example.com/assets/opening-frame.png",
  "last_image": "https://example.com/assets/ending-frame.png"
}
```

### 使用素材 ID 生成视频

先用 [创建素材](./asset-create-media) 注册图片、视频或音频，再把返回的 `Result.Id` 拼成 `asset://{asset_id}` 传入视频生成请求。

```json theme={null}
{
  "model": "doubao-seedance-2-0-260128",
  "prompt": "参考素材中的产品外观和镜头运动，生成一条广告感短视频",
  "duration": 6,
  "aspect_ratio": "16:9",
  "reference_image_urls": ["asset://asset-20260528143012-a8x7k"],
  "reference_video_urls": ["asset://asset-20260528143708-k9m2p"],
  "reference_audio_urls": ["asset://asset-20260528144123-r4s6n"],
  "generate_audio": true
}
```

### 多参考素材生成

同时传参考图、参考视频和参考音频，用于控制主体外观、镜头语言和声音风格。

```json theme={null}
{
  "model": "doubao-seedance-2-0-260128",
  "prompt": "参考产品图和镜头运动生成一条广告感短视频",
  "duration": 6,
  "aspect_ratio": "16:9",
  "reference_image_urls": ["https://example.com/assets/product.png"],
  "reference_video_url": "https://example.com/assets/motion.mp4",
  "audio_url": "https://example.com/assets/music.mp3",
  "generate_audio": true
}
```

## 注意事项

* `prompt` 和 `model` 必填。
* 推荐使用 `duration` 传入视频时长。
* `aspect_ratio` 只支持枚举值：`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`。
* `size` 只支持固定尺寸，不支持 `16:9` 这类比例值。
* `last_image` 必须和 `first_image` 同时传入。
* 素材字段只接收公网 URL 或 `asset://{asset_id}`，不支持直接上传二进制文件。
* `asset://{asset_id}` 只用于视频生成的素材字段；查询素材状态时不要给 `id` 参数加 `asset://` 前缀。

## 相关页面

* [Seedance 2.0 概览](./overview)
* [查询视频任务](./query)
* [创建素材](./asset-create-media)