口型同步

口型同步作業將來源視訊和音軌組合成同步的結果影片。這個端點是異步的，因為視訊處理可能比正常的 HTTP 請求花費更長的時間。

建立工作

POST /api/open/v1/media/lip-sync/jobs
Authorization: Bearer FISHAUDIO_API_KEY
Content-Type: application/json

＃＃＃要求

{
  "videoUrl": "https://example.com/video.mp4",
  "audioUrl": "https://example.com/audio.mp3"
}

API 服務必須可以存取這兩個 URL。對私人媒體使用短期簽名 URL，並使其有效時間足夠長，以便工作人員下載檔案。

curl https://fishaudio.org/api/open/v1/media/lip-sync/jobs \
  -H "Authorization: Bearer FISHAUDIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"videoUrl":"https://example.com/video.mp4","audioUrl":"https://example.com/audio.mp3"}'

回覆

{
  "success": true,
  "message": "Job created",
  "data": {
    "id": "job_123",
    "status": "queued"
  }
}

在更新使用者可見狀態之前保留作業 ID。如果瀏覽器關閉，您的後端應該仍然能夠輪詢並將最終結果附加到原始項目。

列出職位

GET /api/open/v1/media/lip-sync/jobs?page=1&limit=20&status=completed
Authorization: Bearer FISHAUDIO_API_KEY

支援的濾鏡包括 page、limit 和 status。使用清單進行背景恢復和項目歷史記錄，而不是作為高頻輪詢循環。

找工作

GET /api/open/v1/media/lip-sync/jobs/{jobId}
Authorization: Bearer FISHAUDIO_API_KEY

已完成的作業包括 data 中的結果元資料。失敗的作業包含錯誤代碼或訊息。保持終端狀態在您自己的資料庫中不可變，以便重複輪詢不會重寫歷史結果記錄。

計費和積分

口型同步工作通常會依照接受的工作或完成的處理時間收費。在提交之前驗證視訊長度和音訊長度，並避免在輪詢請求逾時時自動建立第二個作業。

如果使用者可以啟動許多作業，請強制執行您自己的佇列和並發限制。在接受昂貴的批次之前，使用設定檔檢測低餘額。

錯誤

狀態	意義	行動
`400`	無效的媒體 URL、負載或狀態過濾器	修復請求
`401`	API 金鑰無效	刷新憑證
`402`	學分或額度不足	暫停隊列
`404`	此 API 金鑰的作業 ID 未知	檢查帳戶和儲存的 ID
`422`	媒體可存取但無法處理	詢問不同的來源媒體

口型同步

口型同步

建立工作

回覆

列出職位

找工作

計費和積分

錯誤

本頁內容