---
title: 快速開始
description: 建立令牌並完成第一個非同步影片任務。
icon: rocket
---

本指南使用 cURL 建立一個影片任務、輪詢任務狀態並下載結果。

## 前置條件

- 一個可正常登入的黑豬AI賬戶
- 足夠支付測試任務的賬戶餘額
- 服務端、終端或 API 除錯工具
- 已瞭解目標模型的支援時長和計費型別

## 1. 建立 API Token

登入 [黑豬AI控制檯](https://api.heizhu.lol/dashboard)，進入令牌管理並建立 Token。將它儲存到環境變數：

```bash
export BLACKPIG_API_KEY="sk-your-api-key"
```

<Warning>
不要在瀏覽器前端、公開程式碼、截圖或聊天記錄中暴露 Token。示例中的 Token 只是佔位符。
</Warning>

## 2. 獲取模型列表

```bash
curl https://api.heizhu.lol/v1/models \
  -H "Authorization: Bearer $BLACKPIG_API_KEY"
```

模型列表只表示當前令牌可見的模型。價格、計費單位、支援時長和模型說明請同時檢視 [模型廣場](https://api.heizhu.lol/pricing)。

## 3. 建立影片任務

以下示例使用按次計費模型，並透過公網 URL 傳入一張參考圖：

```bash
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"
    ]
  }'
```

成功後會返回非同步任務物件。儲存其中的 `id`：

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

## 4. 查詢任務

```bash
curl https://api.heizhu.lol/v1/videos/task_xxxxxxxxxx \
  -H "Authorization: Bearer $BLACKPIG_API_KEY"
```

建議每 5 至 10 秒查詢一次。`queued` 和 `in_progress` 表示任務仍在處理，請勿因此重複建立任務。

## 5. 下載結果

當狀態變為 `completed` 後：

```bash
curl -L https://api.heizhu.lol/v1/videos/task_xxxxxxxxxx/content \
  -H "Authorization: Bearer $BLACKPIG_API_KEY" \
  --output result.mp4
```

<Check>
至此，你已經完成了完整的非同步影片生成流程。生產環境還應加入超時控制、錯誤記錄和指數退避。
</Check>

<CardGroup cols={2}>
  <Card title="瞭解素材要求" icon="images" href="/guides/media-inputs">
    正確傳入圖片、音訊和影片 URL。
  </Card>
  <Card title="處理任務狀態" icon="clock-3" href="/guides/task-lifecycle">
    設計可靠的輪詢和業務狀態流轉。
  </Card>
</CardGroup>