口型同步

口型同步任务会把视频或图片人物与音频合成为口型匹配的视频。中国站公开 API 使用异步任务模型：先创建任务，再查询单个任务或任务列表。

该接口适合视频本地化、数字人配音、广告素材替换音轨和图片驱动口型同步等场景。输入资源必须是服务端可访问的公网 URL。

Endpoint

创建任务：

POST /v1/lip-sync/tasks

列出任务：

GET /v1/lip-sync/tasks

查询单个任务：

GET /v1/lip-sync/tasks/{taskId}

完整地址示例：

https://kittaaudio.com/api/v1/lip-sync/tasks

鉴权与请求头

Content-Type: application/json
Authorization: Bearer YOUR_API_TOKEN

创建任务会消耗积分；查询和列表也需要 token，且只能读取当前账户自己的任务。

创建任务请求

视频驱动：

{
  "model": "kitta-lip-sync-v1",
  "inputMode": "video",
  "videoUrl": "https://example.com/video.mp4",
  "audioUrl": "https://example.com/audio.mp3",
  "durationSeconds": 12
}

图片驱动：

{
  "model": "kitta-lip-sync-v1",
  "inputMode": "image",
  "imageUrl": "https://example.com/person.png",
  "audioUrl": "https://example.com/audio.mp3",
  "referenceImageUrl": "https://example.com/reference.png",
  "durationSeconds": 8
}

字段	类型	必填	说明
`model`	string	是	口型同步模型 ID，可用值以 OpenAPI schema 为准
`inputMode`	string	否	`video` 或 `image`，默认 `video`
`videoUrl`	string	条件必填	`inputMode=video` 时传源视频 URL
`imageUrl`	string	条件必填	`inputMode=image` 时传人物图片 URL
`audioUrl`	string	是	驱动口型的音频 URL
`referenceImageUrl`	string	否	图片驱动场景的参考图 URL
`durationSeconds`	number	否	预估音频时长，便于创建阶段估算扣费

videoUrl 和 imageUrl 至少传一个。所有 URL 都必须能被服务端直接访问。

创建任务响应

成功创建返回 202，响应体是任务 DTO：

{
  "id": "row_123",
  "taskId": "lip_task_123",
  "type": "lip_sync",
  "status": "pending",
  "model": "kitta-lip-sync-v1",
  "inputMode": "video",
  "resultVideoUrl": null,
  "errorCode": null,
  "errorMessage": null,
  "creditsCharged": 1200,
  "createdAt": "2026-07-01T08:00:00.000Z",
  "startedAt": null,
  "completedAt": null
}

taskId 是后续查询任务时使用的 ID。任务创建成功不代表视频已经完成。

查询单个任务

curl -X GET "https://kittaaudio.com/api/v1/lip-sync/tasks/lip_task_123" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

成功响应：

{
  "id": "row_123",
  "taskId": "lip_task_123",
  "type": "lip_sync",
  "status": "succeeded",
  "model": "kitta-lip-sync-v1",
  "inputMode": "video",
  "resultVideoUrl": "https://example.com/result.mp4",
  "errorCode": null,
  "errorMessage": null,
  "creditsCharged": 1200,
  "createdAt": "2026-07-01T08:00:00.000Z",
  "startedAt": "2026-07-01T08:00:03.000Z",
  "completedAt": "2026-07-01T08:01:20.000Z"
}

状态包括 pending、processing、succeeded 和 failed。成功任务会包含 resultVideoUrl；失败任务会包含 errorCode 或 errorMessage。

查询任务列表

curl -X GET "https://kittaaudio.com/api/v1/lip-sync/tasks?limit=20&offset=0&status=succeeded" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

查询参数：

参数	类型	说明
`limit`	integer	返回数量，1 到 100，默认 20
`offset`	integer	分页偏移量，默认 0
`status`	string	可选状态过滤：`pending`、`processing`、`succeeded`、`failed`

列表响应：

{
  "data": [
    {
      "taskId": "lip_task_123",
      "type": "lip_sync",
      "status": "succeeded",
      "inputMode": "video",
      "resultVideoUrl": "https://example.com/result.mp4",
      "creditsCharged": 1200
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "hasMore": false
  }
}

curl 创建示例

curl -X POST "https://kittaaudio.com/api/v1/lip-sync/tasks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "model": "kitta-lip-sync-v1",
    "inputMode": "video",
    "videoUrl": "https://example.com/video.mp4",
    "audioUrl": "https://example.com/audio.mp3",
    "durationSeconds": 12
  }'

错误行为

错误响应示例：

{
  "error": {
    "code": "invalid_request",
    "message": "audioUrl and videoUrl or imageUrl are required",
    "requestId": "req_xxx"
  }
}

状态码	场景
`400`	缺少 `model`、缺少 `audioUrl`、没有提供 `videoUrl` 或 `imageUrl`、模型不支持
`401`	API Token 缺失或无效
`403`	当前账户无权访问该模型或任务
`402`	余额不足
`404`	查询的任务不存在或不属于当前账户
`500`	供应商创建失败、任务状态同步失败或数据库异常

如果任务创建后执行失败，任务详情会进入 failed 并携带错误信息。客户端应以详情接口返回的最终状态为准。

计费与积分

口型同步任务 DTO 中的 creditsCharged 是本次扣费字段。传入 durationSeconds 有助于服务端在创建阶段估算费用；最终对账以任务详情和 GET /v1/usage 为准。

列表和详情查询不创建新任务。建议每 3 到 5 秒查询一次任务详情，进入 succeeded 或 failed 后停止轮询。

口型同步

On this page