虛擬人影像

給一張人像照片與一段音檔，生成對嘴說話的虛擬人影片。 生成為非同步：建立任務拿到 Id，再輪詢狀態取得影片連結。

流程

  1. POST /avatar/create 送出圖片與音檔，取得 Id 與預扣的 Cost
  2. GET /avatar/status/{id} 輪詢，直到狀態變成 Success 或 Fail
  3. 成功後從 VideoUrl 下載影片

影片與任務紀錄只保留 2 天，請在期限內下載保存。 任務失敗時系統會自動退回預扣的配額。

素材限制

項目限制
圖片格式jpg、jpeg、png
圖片比例僅支援 1:1、9:16、16:9
建議解析度1024×1024、1080×1920、1920×1080
音檔格式wav、mp3、m4a
音檔長度5 ～ 120 秒
上傳總大小圖片 + 音檔合計不可超過 30 MB

計費

以音檔長度計費，每秒扣 200 單位，不足一秒以一秒計。 費用在建立任務時預扣，失敗會退回。

建立任務

POST /avatar/create

請求為 multipart/form-data。圖片與音檔可以直接上傳檔案，也可以改給 URL。

Form 欄位

image file 二擇一
直接上傳圖片檔。與 image_url 擇一提供。
image_url string 二擇一
圖片的公開網址。
audio file 二擇一
直接上傳音檔。與 audio_url 擇一提供。
audio_url string 二擇一
音檔的公開網址。
upscale boolean 選填 預設 false
是否在生成後額外做畫質提升。開啟後成品更清晰，但總耗時明顯拉長。

回應

data.Id string
任務識別碼，用於後續查詢狀態。
data.Cost integer
本次預扣的配額總額。
curl --location '{{BASE_URL}}/avatar/create' \
  --header 'x-api-key: your-api-key' \
  --form 'image=@"./portrait.png"' \
  --form 'audio=@"./speech.wav"' \
  --form 'upscale="false"'
                        
curl --location '{{BASE_URL}}/avatar/create' \
  --header 'x-api-key: your-api-key' \
  --form 'image_url="https://example.com/portrait.png"' \
  --form 'audio_url="https://example.com/speech.wav"'
                        
{
  "data": {
    "Id": "66c2c2d8034838ec637ebzd2",
    "Cost": 2400
  }
}

查詢狀態

GET /avatar/status/{id}

狀態值

Running string
處理中（影片生成中或畫質提升中）。
Success string
生成成功，可從 VideoUrl 取得影片。
Fail string
任務失敗，系統會自動退回預扣配額。
curl --location '{{BASE_URL}}/avatar/status/66c2c2d8034838ec637ebzd2' \
  --header 'x-api-key: your-api-key'
                        
import time
import requests

headers = {"x-api-key": "your-api-key"}
task_id = "66c2c2d8034838ec637ebzd2"

while True:
    resp = requests.get(
        f"{{BASE_URL}}/avatar/status/{task_id}",
        headers=headers,
        timeout=30,
    )
    resp.raise_for_status()
    data = resp.json()["data"]

    if data["Status"] == "Success":
        print("video:", data["VideoUrl"])
        break
    if data["Status"] == "Fail":
        raise RuntimeError("生成失敗，配額已退回")

    time.sleep(10)
                        
{
  "data": {
    "Status": "Success",
    "VideoUrl": "https://.../output.mp4"
  }
}

錯誤

400 圖片比例或音檔長度不符限制、檔案過大，或額度不足
401 未提供或無效的 API Key
404 找不到該任務，或資料已過期（超過 2 天）
500 伺服器內部錯誤