口型同步

口型同步将源视频和音频合成为同步视频。处理过程为异步任务。

创建任务

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

{
  "video_url": "https://example.com/video.mp4",
  "audio_url": "https://example.com/audio.mp3"
}

两个 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 '{"video_url":"https://example.com/video.mp4","audio_url":"https://example.com/audio.mp3"}'

创建响应

创建成功后立即保存 data.id。该 ID 是后续查询使用的 jobId。

{
  "success": true,
  "message": "Task created successfully",
  "data": {
    "id": "job_123",
    "status": "pending",
    "created_at": "2026-07-20T10:00:00.000Z",
    "credits_used": 120,
    "quota_remaining": 99880
  }
}

查询任务

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

状态包括 pending、processing、completed 和 failed。完成后读取 data.result_url；失败时读取 data.error_message。

任务列表

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

支持 page、limit 和 status。列表适合后台恢复和任务历史，不应作为高频轮询接口。

计费与重试

创建任务时会按音频时长预扣 API 额度。列表和详情查询不会创建任务，也不会再次扣费。轮询超时或网络中断时继续查询原 jobId，不要自动创建第二个任务。

错误处理

状态码	含义	建议
`400`	媒体 URL、请求参数或状态过滤无效	修正请求
`401`	API Key 无效	更新凭据
`402`	API 额度不足	暂停任务队列
`404`	当前 API Key 无权访问该任务	检查账户和保存的 ID
`422`	媒体可访问但无法处理	更换源媒体