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

# SD2.0 视频生成 API

> 使用 /v1/video/generations 调用 SD2.0 视频生成模型，支持图片参考、视频参考和文生视频。

**权限说明**
SD2.0 暂未对所有用户开放。
如需开通调用权限，请联系YeLinAI 客服协助处理：[hi@yelinai.com](mailto:hi@yelinai.com)

**Base URL:** `https://api.yelinai.com`

**需要接入的接口：** 2 个

1. `POST /v1/video/generations`：创建视频生成任务
2. `GET /v1/video/generations/{task_id}`：查询任务状态与获取结果 URL

## 接口流程

SD2.0 视频生成是异步任务接口。业务侧需要先创建任务，拿到 `task_id` 后轮询查询状态，直到任务完成并返回视频 URL。

1. **创建任务**

调用 `POST /v1/video/generations`，传入模型、提示词、视频参数和可选参考素材文件。

2. **查询状态**

调用 `GET /v1/video/generations/{task_id}`，轮询 `status`。

3. **下载视频**

当 `status=completed` 时，从响应中读取视频 URL 并下载 mp4。

常见状态流转：

```
pending -> running -> succeeded -> completed
```

失败时通常返回 `failed`，并在响应中包含 `error` 字段。

## 模型

| 模型             | 说明         | 推荐用途           |
| -------------- | ---------- | -------------- |
| `seedance-2.0` | SD2.0 视频生成 | 视频生成、图片参考、视频参考 |

## 创建任务

`POST /v1/video/generations`

创建 SD2.0 视频生成任务。

### 请求头

| Header          | 必填 | 说明                    |
| --------------- | -- | --------------------- |
| `Authorization` | 是  | `Bearer $API_KEY`     |
| `Content-Type`  | 是  | `multipart/form-data` |

### 请求参数

| 参数                  | 类型      | 必填 | 说明                                   |
| ------------------- | ------- | -- | ------------------------------------ |
| `model`             | string  | 是  | 模型 ID，固定为 `seedance-2.0`             |
| `prompt`            | string  | 是  | 视频生成提示词，支持引用上传的文件                    |
| `duration`          | integer | 否  | 输出时长（秒），默认 5 秒                       |
| `aspect_ratio`      | string  | 否  | 输出比例，如 `16:9`、`9:16`、`1:1`，默认 `16:9` |
| `files`             | file    | 否  | 参考素材文件，支持图片（jpg/png）和视频（mp4）         |
| `first_frame_image` | file    | 否  | 首帧图片文件，指定视频开头画面                      |
| `last_frame_image`  | file    | 否  | 尾帧图片文件，指定视频结尾画面                      |

### 文件引用语法

在 `prompt` 中按上传顺序引用文件：

| 写法       | 含义           |
| -------- | ------------ |
| `@IMG_1` | 第 1 个上传的图片文件 |
| `@IMG_2` | 第 2 个上传的图片文件 |
| `@VID_1` | 第 1 个上传的视频文件 |
| `@VID_2` | 第 2 个上传的视频文件 |

### 文生视频示例

```bash theme={"system"}
curl -X POST https://api.yelinai.com/v1/video/generations \
  -H "Authorization: Bearer $API_KEY" \
  -F "model=seedance-2.0" \
  -F "prompt=一只可爱的小猫在草地上玩耍，阳光明媚" \
  -F "duration=5" \
  -F "aspect_ratio=16:9"
```

### 图片参考示例

```bash theme={"system"}
curl -X POST https://api.yelinai.com/v1/video/generations \
  -H "Authorization: Bearer $API_KEY" \
  -F "model=seedance-2.0" \
  -F "prompt=@IMG_1 中的人物在海边散步" \
  -F "duration=5" \
  -F "aspect_ratio=16:9" \
  -F "files=@/path/to/image1.jpg"
```

### 多素材参考示例

```bash theme={"system"}
curl -X POST https://api.yelinai.com/v1/video/generations \
  -H "Authorization: Bearer $API_KEY" \
  -F "model=seedance-2.0" \
  -F "prompt=@IMG_1 和 @IMG_3 与 @VID_1 中的人一起跳舞" \
  -F "duration=5" \
  -F "aspect_ratio=16:9" \
  -F "files=@/path/to/image1.jpg" \
  -F "files=@/path/to/image2.jpg" \
  -F "files=@/path/to/video1.mp4"
```

### 首尾帧控制示例

```bash theme={"system"}
curl -X POST https://api.yelinai.com/v1/video/generations \
  -H "Authorization: Bearer $API_KEY" \
  -F "model=seedance-2.0" \
  -F "prompt=一个人从房间走到户外的场景" \
  -F "duration=8" \
  -F "aspect_ratio=16:9" \
  -F "first_frame_image=@/path/to/first_frame.jpg" \
  -F "last_frame_image=@/path/to/last_frame.jpg"
```

### 创建响应

```json theme={"system"}
{
  "task_id": "task-20260501120000-abc123",
  "status": "pending",
  "created_at": "2026-05-01T12:00:00Z"
}
```

响应字段：

| 字段           | 类型     | 说明                 |
| ------------ | ------ | ------------------ |
| `task_id`    | string | 任务 ID，后续查询状态使用     |
| `status`     | string | 初始状态，常见为 `pending` |
| `created_at` | string | 创建时间（ISO 格式）       |

## 查询任务

`GET /v1/video/generations/{task_id}`

查询视频生成任务状态。

```bash theme={"system"}
curl https://api.yelinai.com/v1/video/generations/task-20260501120000-abc123 \
  -H "Authorization: Bearer $API_KEY"
```

### 路径参数

| 参数        | 类型     | 必填 | 说明                 |
| --------- | ------ | -- | ------------------ |
| `task_id` | string | 是  | 创建任务时返回的 `task_id` |

### 查询响应

任务进行中：

```json theme={"system"}
{
  "task_id": "task-20260501120000-abc123",
  "status": "running",
  "progress": 50,
  "created_at": "2026-05-01T12:00:00Z",
  "updated_at": "2026-05-01T12:01:00Z"
}
```

任务完成：

```json theme={"system"}
{
  "task_id": "task-20260501120000-abc123",
  "status": "completed",
  "video_url": "https://example.com/generated-video.mp4",
  "created_at": "2026-05-01T12:00:00Z",
  "updated_at": "2026-05-01T12:05:00Z"
}
```

任务失败：

```json theme={"system"}
{
  "task_id": "task-20260501120000-abc123",
  "status": "failed",
  "error": {
    "code": "GENERATION_FAILED",
    "message": "视频生成失败"
  },
  "created_at": "2026-05-01T12:00:00Z",
  "updated_at": "2026-05-01T12:03:00Z"
}
```

响应字段：

| 字段           | 类型      | 说明                                                   |
| ------------ | ------- | ---------------------------------------------------- |
| `task_id`    | string  | 任务 ID                                                |
| `status`     | string  | `pending`、`running`、`succeeded`、`completed`、`failed` |
| `progress`   | integer | 任务进度（0-100）                                          |
| `video_url`  | string  | 任务完成后返回的视频 URL                                       |
| `created_at` | string  | 创建时间                                                 |
| `updated_at` | string  | 更新时间                                                 |
| `error`      | object  | 失败时的错误信息                                             |

## 下载视频

查询响应进入 `completed` 后，读取 `video_url` 并直接下载：

```bash theme={"system"}
curl -L "$VIDEO_URL" -o output.mp4
```

`video_url` 通常是临时签名 URL。生产环境建议任务完成后立即下载，或转存到自己的对象存储。

## Python 完整示例

```python theme={"system"}
import os
import time
import requests

API_KEY = os.environ["API_KEY"]
BASE_URL = "https://api.yelinai.com/v1/video/generations"

headers = {
    "Authorization": f"Bearer {API_KEY}",
}

files = {
    "model": (None, "seedance-2.0"),
    "prompt": (None, "@IMG_1 中的人物在海边散步"),
    "duration": (None, "5"),
    "aspect_ratio": (None, "16:9"),
    "files": open("/path/to/image.jpg", "rb"),
}

create_resp = requests.post(BASE_URL, headers=headers, files=files, timeout=60)
create_resp.raise_for_status()
task_id = create_resp.json()["task_id"]

while True:
    query_resp = requests.get(f"{BASE_URL}/{task_id}", headers=headers, timeout=60)
    query_resp.raise_for_status()
    task = query_resp.json()
    status = task.get("status")

    if status == "completed":
        video_url = task.get("video_url")
        video_resp = requests.get(video_url, timeout=120)
        video_resp.raise_for_status()
        with open(f"{task_id}.mp4", "wb") as f:
            f.write(video_resp.content)
        break

    if status == "failed":
        raise RuntimeError(task.get("error") or task)

    time.sleep(20)
```

## 常见问题

文件上传有什么限制？

目前支持 jpg、png 图片格式和 mp4 视频格式。单个文件大小建议不超过 50MB。

如何正确引用上传的文件？

按文件上传顺序，图片使用 `@IMG_1`、`@IMG_2` 引用，视频使用 `@VID_1`、`@VID_2` 引用。

任务需要多久完成？

通常需要 20 - 30分钟，具体取决于视频时长和服务器负载。建议轮询间隔设为 20-30 秒。