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

# 视频生成(Seedance)

> POST /seedance/v1/videos/generations —— Seedance 标准视频生成

通过 Seedance 模型生成视频,兼容 [seevio.ai](https://seevio.ai/api-docs) 标准 API。采用 **异步任务** 流程:提交后获取任务 ID,轮询完成后下载视频。

## 提交任务

```bash theme={null}
curl https://openp.ai/seedance/v1/videos/generations \
  -H "Authorization: Bearer $OPENPAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-0-fast",
    "input": {
      "prompt": "A golden retriever running on a beach at sunset, cinematic",
      "duration": 5,
      "aspect_ratio": "16:9",
      "resolution": "720p"
    }
  }'
```

### 参数

| 字段      | 类型     |  必填 | 说明        |
| ------- | ------ | :-: | --------- |
| `model` | string |  ✅  | 见下方模型列表   |
| `input` | object |  ✅  | 生成参数,字段见下 |

### input 字段

| 字段                | 类型      |  必填 | 说明                                                                |
| ----------------- | ------- | :-: | ----------------------------------------------------------------- |
| `prompt`          | string  |  ✅  | 视频描述                                                              |
| `generation_type` | string  |     | 生成模式:`text-to-video`(默认)/ `image-to-video` / `reference-to-video` |
| `image_urls`      | array   |  条件 | 图片 URL 列表。图生视频:1 张(首帧)或 2 张(首+尾帧);参考生视频:参考图                       |
| `video_urls`      | array   |     | 参考视频 URL 列表(仅参考生视频)                                               |
| `audio_urls`      | array   |     | 参考音频 URL 列表(仅参考生视频)                                               |
| `duration`        | integer |     | 时长(秒),默认 5                                                        |
| `aspect_ratio`    | string  |     | `16:9` / `4:3` / `1:1` / `3:4` / `9:16` / `21:9` / `adaptive`(默认) |
| `resolution`      | string  |     | `480p` / `720p`(默认)/ `1080p`                                      |
| `generate_audio`  | boolean |     | 是否生成配音,默认 `true`                                                  |
| `negative_prompt` | string  |     | 负面提示词                                                             |

媒体 URL 可以是公开可访问的 http(s) 地址,也可以是 data URL(`data:image/png;base64,...`)。

### 模型列表

`seedance-2-5` / `seedance-2-0` / `seedance-2-0-fast` / `seedance-2-0-mini` / `seedance-2-0-enhanced` / `seedance-2-0-mini-enhanced` / `seedance-1-5-pro`

## 生成模式

### 图生视频(首帧)

`image_urls` 传 1 张图片作为首帧:

```bash theme={null}
curl https://openp.ai/seedance/v1/videos/generations \
  -H "Authorization: Bearer $OPENPAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-5",
    "input": {
      "prompt": "the subject turns toward camera, soft studio motion",
      "generation_type": "image-to-video",
      "image_urls": ["https://your.cdn.com/first-frame.jpg"],
      "duration": 5,
      "resolution": "720p"
    }
  }'
```

媒体也支持 data URL 内联(`data:<mime>;base64,...`),适合直接上传本地素材而无需先托管。图片:

```json theme={null}
{
  "model": "seedance-2-0-fast",
  "input": {
    "prompt": "gentle ocean waves under a warm sunset sky, cinematic",
    "generation_type": "image-to-video",
    "image_urls": ["data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEASABIAAD..."],
    "duration": 4,
    "resolution": "480p"
  }
}
```

参考视频与参考音频同样适用(`video/mp4`、`audio/mpeg` 等 MIME 类型):

```json theme={null}
{
  "model": "seedance-2-5",
  "input": {
    "prompt": "the character from image 1 performs the motion from the video with the reference voice",
    "generation_type": "reference-to-video",
    "image_urls": ["data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEASABIAAD..."],
    "video_urls": ["data:video/mp4;base64,AAAAIGZ0eXBpc29tAAACAGlzb20..."],
    "audio_urls": ["data:audio/mpeg;base64,SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjU4..."],
    "duration": 8
  }
}
```

<Note>内联视频/音频会让请求体显著增大(base64 约膨胀 33%),单个素材上限 100 MB;素材较大或需复用时建议改用公开 URL。</Note>

### 图生视频(首帧 + 尾帧)

`image_urls` 传 2 张图片,模型在首帧与尾帧之间插值生成:

```json theme={null}
{
  "model": "seedance-2-5",
  "input": {
    "prompt": "smooth camera push-in from the first frame to the last",
    "generation_type": "image-to-video",
    "image_urls": [
      "https://your.cdn.com/first-frame.jpg",
      "https://your.cdn.com/last-frame.jpg"
    ],
    "duration": 5
  }
}
```

### 参考生视频(图片 + 视频)

用参考图锁定主体,用参考视频复刻运镜/动作:

```json theme={null}
{
  "model": "seedance-2-5",
  "input": {
    "prompt": "use the product from image 1 and the camera motion from the reference video",
    "generation_type": "reference-to-video",
    "image_urls": ["https://your.cdn.com/product.jpg"],
    "video_urls": ["https://your.cdn.com/camera-motion.mp4"],
    "duration": 8,
    "resolution": "720p"
  }
}
```

### 参考生视频(图片 + 音频)

让人物/主体按照参考音频说话或演唱:

```json theme={null}
{
  "model": "seedance-2-5",
  "input": {
    "prompt": "the woman from image 1 sings the reference song on stage",
    "generation_type": "reference-to-video",
    "image_urls": ["https://your.cdn.com/singer.jpg"],
    "audio_urls": ["https://your.cdn.com/song.mp3"],
    "duration": 10
  }
}
```

### 参考生视频(图片 + 视频 + 音频)

三种素材可以同时组合使用:

```json theme={null}
{
  "model": "seedance-2-5",
  "input": {
    "prompt": "the character from image 1 performs the motion from the video with the reference voice",
    "generation_type": "reference-to-video",
    "image_urls": ["https://your.cdn.com/character.jpg"],
    "video_urls": ["https://your.cdn.com/motion.mp4"],
    "audio_urls": ["https://your.cdn.com/voice.mp3"],
    "duration": 8
  }
}
```

### 参考生视频(仅音频)

`seedance-2-5` 支持仅音频作为参考;`seedance-2-0` 系列使用音频时需至少搭配 1 张图片或 1 段视频:

```json theme={null}
{
  "model": "seedance-2-5",
  "input": {
    "prompt": "a music video visualizer following the rhythm of the reference track",
    "generation_type": "reference-to-video",
    "audio_urls": ["https://your.cdn.com/track.mp3"],
    "duration": 10
  }
}
```

### 素材限制

| 模型                | 图片   | 视频                       | 音频                       | 总量   |
| ----------------- | ---- | ------------------------ | ------------------------ | ---- |
| `seedance-2-5`    | ≤ 30 | ≤ 10,每段 2-30 秒,合计 ≤ 30 秒 | ≤ 10,每段 2-30 秒,合计 ≤ 30 秒 | ≤ 50 |
| `seedance-2-0` 系列 | ≤ 9  | ≤ 3,合计 ≤ 15 秒            | ≤ 3,合计 ≤ 15 秒            | —    |

## 响应(任务创建)

```json theme={null}
{
  "taskId": "task_id",
  "credits": 28
}
```

`taskId` 即任务 ID,`credits` 为预估扣费。

## 查询任务状态

```bash theme={null}
curl https://openp.ai/seedance/v1/tasks/task_id \
  -H "Authorization: Bearer $OPENPAI_API_KEY"
```

```json theme={null}
{
  "id": "task_id",
  "status": "completed",
  "created_at": 1786176476,
  "model": "seedance-2-0-fast",
  "billing_status": "charged",
  "credits": 28,
  "data": {
    "results": [
      "https://openp.ai/seedance/v1/videos/generations/task_id.mp4"
    ],
    "processing_time": 104
  }
}
```

| 字段                     | 说明                                               |
| ---------------------- | ------------------------------------------------ |
| `status`               | `queued` / `generating` / `completed` / `failed` |
| `billing_status`       | `reserved`(预扣)/ `charged`(已扣费)/ `refunded`(已退款)  |
| `credits`              | 实际扣费                                             |
| `failed_reason`        | 失败原因(仅 `failed` 时返回,此时无 `data`)                  |
| `data.results`         | 视频下载 URL 列表(仅 `completed` 时返回)                   |
| `data.processing_time` | 生成耗时(秒)                                          |

## 下载视频

```bash theme={null}
curl -L https://openp.ai/seedance/v1/videos/generations/task_id.mp4 \
  -H "Authorization: Bearer $OPENPAI_API_KEY" \
  -o video.mp4
```

返回 `video/mp4` 字节流。

## 轮询建议

* 初始延迟 5-10 秒后开始轮询。
* 间隔 10-30 秒一次。
* 通常 1-3 分钟完成。
* 失败时 `failed_reason` 字段说明原因。

## 计费

按 **模型单价 × 生成秒数** 扣费,提交时预扣、完成时结算。失败的任务自动退款(`billing_status` 变为 `refunded`)。