口型同步

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

创建任务

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

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

服务端会先导入两个远程素材，再创建任务和扣减对口型额度。导入失败仍返回标准的 code、message、requestId，并增加安全的定位信息：

{
  "code": "ERR_LIP_SYNC_MEDIA_DOWNLOAD_TIMEOUT",
  "message": "下载对口型素材超时，请重试或换用稳定、快速的公网链接",
  "requestId": "req_123",
  "details": {
    "media_kind": "video",
    "stage": "download",
    "retryable": true
  }
}

仅当 retryable 为 true 时退避重试。素材导入失败不会创建对口型任务，也不会扣减对口型额度。

两个 URL 都必须能被服务端直接访问。私有媒体请使用有效期足够覆盖下载时间的短期签名 URL。

curl https://kittaai.com/api/open/v1/media/lip-sync/jobs \
  -H "Authorization: Bearer KITTA_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": 1100,
    "billing_duration_seconds": 11,
    "video_duration_seconds": 10.04,
    "audio_duration_seconds": 12.56,
    "billing_rule": "shorter_input_rounded_up",
    "quota_remaining": 99880
  }
}

查询任务

GET /api/open/v1/media/lip-sync/jobs/{jobId}
Authorization: Bearer KITTA_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 KITTA_API_KEY

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

计费与重试

视频模式默认按视频、音频两者中较短的时长向上取整计费；例如视频 10.04 秒、音频 12.56 秒，按 11 秒计费。设置 video_extension: true 时会延长视频并改为按音频时长向上取整。创建任务时一次性扣除响应中的 credits_used，成功后不再调整；失败任务全额退款。列表和详情查询不会再次扣费。

视频配音：文字直接生成口型视频

视频配音接口将 TTS 和口型同步合并为一次创建操作。服务端先使用指定音色生成音频，再自动创建异步口型同步任务。

POST /api/open/v1/media/video-dubbing/jobs
Authorization: Bearer KITTA_API_KEY
Idempotency-Key: YOUR_UNIQUE_REQUEST_KEY
Content-Type: application/json

{
  "video_url": "https://example.com/video.mp4",
  "text": "需要生成配音和口型的视频文案",
  "reference_id": "YOUR_VOICE_ID",
  "model_id": "fishaudio-s21pro-flash",
  "speed": 1,
  "language": "zh"
}

video_url、text 和 reference_id 为必填字段。Idempotency-Key 对每个新任务必须唯一；同一次任务发生超时或网络重试时必须继续使用原值。

创建响应中的 data.id 是后续查询使用的 jobId。TTS 已在创建请求中完成，返回后进入口型同步阶段：

GET /api/open/v1/media/video-dubbing/jobs/{jobId}
Authorization: Bearer KITTA_API_KEY

响应中的 credits_used 分别列出 tts、lip_sync 和 total。如果 TTS 已成功但口型任务创建失败，TTS 额度不会退回；接口会返回已生成的 tts_audio_url 和 tts_credits_used，口型阶段未成功预扣的额度不会保留。

错误处理

状态码	含义	建议
`400`	媒体 URL、请求参数或状态过滤无效	修正请求
`401`	API Key 无效	更新凭据
`402`	API 额度不足	暂停任务队列
`404`	当前 API Key 无权访问该任务	检查账户和保存的 ID
`413`	素材超过文件大小限制	压缩或更换 `details` 指定的素材
`415`	素材格式不受支持	转换对应的音频或视频
`422`	素材无法拉取、解码或检查	根据 `details` 检查并更换源素材
`503`	平台素材导入服务暂时不可用	`retryable` 为 `true` 时退避重试
`504`	远程素材下载超时	重试或换用下载更快的公网素材链接