---
title: 建立影片任務
description: 提交文字或參考素材，建立非同步影片生成任務。
icon: video
openapi: POST /v1/videos
---

建立一個非同步影片生成任務。介面接受 JSON 請求，並在成功提交後返回任務 ID。

## 請求引數

<ParamField body="model" type="string" required>
  模型廣場中的完整模型名稱。
</ParamField>

<ParamField body="prompt" type="string" required>
  影片生成提示詞。建議明確描述主體、動作、鏡頭、場景和期望風格。
</ParamField>

<ParamField body="duration" type="integer" required>
  計費與呼叫時長引數。按次模型傳 `1`；按秒模型傳實際秒數，並與 `video_duration` 保持一致。
</ParamField>

<ParamField body="video_duration" type="integer" required>
  目標影片秒數。必須符合所選模型在模型廣場中標註的支援範圍。
</ParamField>

<ParamField body="aspect_ratio" type="string">
  畫面比例。標準值包括 `16:9`、`9:16`、`4:3`、`3:4` 和 `1:1`，具體支援情況由模型決定。
</ParamField>

<ParamField body="resolution" type="string">
  輸出解析度。可使用 `480p`、`720p` 或 `1080p`；未顯式提供時，部分模型可從模型名稱推斷。
</ParamField>

<ParamField body="image_urls" type="string[]">
  公網可訪問的參考圖片 URL 陣列。
</ParamField>

<ParamField body="audio_urls" type="string[]">
  公網可訪問的參考音訊 URL 陣列。
</ParamField>

<ParamField body="video_urls" type="string[]">
  公網可訪問的參考影片 URL 陣列。
</ParamField>

## 請求示例

<CodeGroup>
```bash cURL
curl https://api.heizhu.lol/v1/videos \
  -H "Authorization: Bearer $BLACKPIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "L-stable-seedance-2-0-933-720p",
    "prompt": "电影感近景，人物在雨夜街道缓慢回头，镜头平稳推进",
    "duration": 1,
    "video_duration": 15,
    "aspect_ratio": "9:16",
    "resolution": "720p",
    "image_urls": ["https://example.com/reference.jpg"]
  }'
```

```javascript JavaScript
const response = await fetch('https://api.heizhu.lol/v1/videos', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BLACKPIG_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'L-stable-seedance-2-0-933-720p',
    prompt: '电影感近景，人物在雨夜街道缓慢回头，镜头平稳推进',
    duration: 1,
    video_duration: 15,
    aspect_ratio: '9:16',
    resolution: '720p',
    image_urls: ['https://example.com/reference.jpg'],
  }),
});

const task = await response.json();
```

```python Python
import os
import requests

response = requests.post(
    "https://api.heizhu.lol/v1/videos",
    headers={"Authorization": f"Bearer {os.environ['BLACKPIG_API_KEY']}"},
    json={
        "model": "L-stable-seedance-2-0-933-720p",
        "prompt": "电影感近景，人物在雨夜街道缓慢回头，镜头平稳推进",
        "duration": 1,
        "video_duration": 15,
        "aspect_ratio": "9:16",
        "resolution": "720p",
        "image_urls": ["https://example.com/reference.jpg"],
    },
    timeout=60,
)
response.raise_for_status()
task = response.json()
```
</CodeGroup>

## 成功響應

<ResponseField name="id" type="string" required>
  平臺任務 ID。後續查詢和獲取結果時必須使用此值。
</ResponseField>

<ResponseField name="object" type="string" required>
  物件型別，固定為 `video`。
</ResponseField>

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

<ResponseField name="status" type="string" required>
  初始狀態通常為 `queued`。
</ResponseField>

<ResponseField name="progress" type="integer" required>
  當前進度百分比。
</ResponseField>

<ResponseField name="created_at" type="integer" required>
  Unix 時間戳。
</ResponseField>

```json
{
  "id": "task_xxxxxxxxxx",
  "object": "video",
  "model": "L-stable-seedance-2-0-933-720p",
  "status": "queued",
  "progress": 0,
  "created_at": 1788480000
}
```

<Warning>
同一次業務操作只應建立一個任務。客戶端超時或查詢失敗不代表任務未建立，請結合服務端響應與業務日誌判斷，避免重複計費。
</Warning>