Menu

快速開始

從零開始,完成你的第一筆圖生影片任務。以下步驟依序進行即可。

1. 註冊帳號並完成 Email 驗證

到 /register 建立帳號,並點擊驗證信裡的連結完成 Email 驗證。沒收到驗證信可到 /reverify 重新發送。後續建立 API Key 需要帳號的 Email 已通過驗證。

2. 確認帳號已有付費或有效試用積分

登入後台後,在頁面上確認帳號已有付費積分餘額,或名下有一筆尚未到期、仍有剩餘額度的試用額度(trial grant)。沒有可用積分時,建立任務會在扣款階段被拒絕,詳見〈積分與計費〉。

3. 建立對應類型的 API Key

到後台的 /app/api-keys 頁面建立 API Key:依你在步驟 2 確認的積分來源,選擇建立「付費」Key(消耗付費餘額)或「試用」Key(綁定某一批試用積分)。Key 會在建立當下顯示明文,請立刻複製保存;之後也可以隨時回到該頁面對 Key 點擊「顯示」重新查看。也不要把 Key 放進瀏覽器前端程式碼或提交進版本控制。

4. 用環境變數保存 base URL 與 API Key

把你站台的 base URL 與剛拿到的 API Key 存成環境變數,之後的範例都會引用它們:

export YUYU_API_BASE_URL="https://your-domain"
export YUYU_API_KEY="sk-live-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

5. 把要轉成影片的圖片轉成 base64 data URI

images 只接受完整的 base64 data URI(data:image/{png|jpeg|webp};base64,...),沒有獨立的上傳端點——把圖片檔案在你的程式裡讀成 base64 字串,自己組成 data URI 即可,例如：

echo "data:image/png;base64,$(base64 -w0 /path/to/photo.png)"

6. 建立一筆 YUYU_M1 影片生成任務

帶上 X-Api-Key、Idempotency-Key(防止重試造成重複建單/扣款)與 Content-Type: application/json,送出最小合法的建單請求。YUYU_M1 的 duration 固定為 5,仍必須明確帶入:

curl -X POST "$YUYU_API_BASE_URL/api/tasks/video-generation" \
  -H "X-Api-Key: $YUYU_API_KEY" \
  -H "Idempotency-Key: quickstart-demo-001" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YUYU_M1",
    "prompt": "一隻貓在陽光灑落的草地上奔跑",
    "images": ["data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."],
    "duration": 5
  }'

成功建立回 201 Created,回應內容是〈任務查詢與取件〉描述的任務物件(節錄):

{
  "public_id": "01K0ZC8QW3E5F1234567890ABC",
  "status": 0,
  "credits": 10
}

7. 保存 public_id

把回應裡的 public_id 存下來(任務的識別碼,之後所有查詢與下載都用這個值,不是可被猜測的流水號)。

8. 輪詢查詢,直到任務進入終態

用 public_id 查詢任務,重複呼叫直到 status 進入終態——終態代表任務不會再變化的最終結果,包含已完成(20)、失敗(30)、已取消(40):

curl -H "X-Api-Key: $YUYU_API_KEY" \
  "$YUYU_API_BASE_URL/api/tasks/01K0ZC8QW3E5F1234567890ABC"

status = 20(已完成)時,回應會帶上 files 陣列,裡面是可直接下載的網址。

9. 從 files[].url 下載結果

不需要自己拼下載路徑,直接取用回應 files 陣列裡現成的 url:

curl -H "X-Api-Key: $YUYU_API_KEY" \
  "$YUYU_API_BASE_URL/api/tasks/01K0ZC8QW3E5F1234567890ABC/files/video" \
  -o output.mp4

到這裡,你已經完成從上傳圖片到取得影片的完整流程。

用 Webhook 取代輪詢(選填)

建單時帶上 callback_url(必須是公開可存取的 https:// 網址),任務進入完成或失敗的終態時,系統會主動通知這個網址,不需要你持續輪詢。收到通知後,務必用你帳號的 webhook_secret 驗證請求帶的 X-Signature,確認通知確實來自 YUYU VIDEO。完整的請求格式、簽名演算法與重送策略見〈回呼(Webhook)〉。

下一步