# Sync Lipsync 3 API

> 將任何說話影片的嘴唇重新配合新的音軌。

Sync Labs 的 lipsync-3 會取代影片中人物的嘴部動作，使其符合新的語音軌，適用於 配音、廣告在地化，以及後期修正台詞。音訊與影片長度不同時，可選擇裁切、循環、來回播放、 填入靜音或重新映射。

- Model id: `sync-lipsync/v3`
- Made by: Sync Labs
- Category: Lipsync & Avatars
- Output: video
- Price per minute of your output video: $8.00 / minute of output video (cheapest run $8.00 (8000 API credits))
- Run: `POST https://api.doitong.com/v1/run/sync-lipsync/v3`
- Quote: `POST https://api.doitong.com/v1/quote/sync-lipsync/v3`
- Docs page: https://doitong.com/zh-TW/developers/models/sync-lipsync/v3

## Pricing

Price: **$8.00 / minute of output video**. Price per minute of your output video: the input files are measured before the run (length, resolution, frame rate). The quote measures the same files and is exactly what the run charges.

The full example input below costs $1.334 = 1334 API credits (0.1667 min output video × $8.00).

Prices are the upstream price in USD, paid from the API balance in API credits (1000 API credits = 1 USD). `POST https://api.doitong.com/v1/quote/sync-lipsync/v3` with the same JSON body returns the exact price for that input; the quote is exactly what a run charges. Invalid input is never charged and failed or canceled requests are refunded automatically.

## Input parameters

Send either the canonical name or the native field name (not both). Canonical names are the same across models.

| Parameter | Canonical name | Type | Required | Default | Allowed values / range | Description |
|---|---|---|---|---|---|---|
| `video_url` | `video` | string (video URL) | yes |  |  | 指向輸入影片的 URL。 |
| `audio_url` | `audio` | string (audio URL) | yes |  |  | 輸入音訊位置，以 URL 表示。 |
| `sync_mode` |  | enum (string) | no | `cut_off` | `cut_off`, `loop`, `bounce`, `silence`, `remap` | 處理音訊與影片長度差異的唇形同步模式。 |
| `options` |  | object {sync_mode, model_mode, prompt, temperature, active_speaker_detection, occlusion_detection_enabled} \| null | no |  |  | 在此設定額外的 Sync.so 生成行為；任何提供的 options.sync_mode 優先於頂層 sync_mode 值。 |
| `options.sync_mode` |  | enum (string) \| null | no |  | `cut_off`, `loop`, `bounce`, `silence`, `remap` | 頂層 sync_mode 的覆寫值，指定輸入音訊與影片長度不同時的處理方式。 |
| `options.model_mode` |  | enum (string) \| null | no |  | `lips`, `face`, `head`, `lipsync`, `emotion`, `talking_head` | 編輯區域選擇，主要適用於 react-1，用於指定模型修改的區域。 |
| `options.prompt` |  | enum (string) \| null | no |  | `happy`, `sad`, `angry`, `disgusted`, `surprised`, `neutral` | 主要由 react-1 使用的情緒指引，用於引導生成。 |
| `options.temperature` |  | number \| null | no |  | 0 – 1 | 表現力設定；對原生管理此功能的 sync-3 沒有作用。對使用此設定的模型，0 代表最低唇形同步表現力，1 代表最高。 |
| `options.active_speaker_detection` |  | object {auto_detect, v3, use_v2, frame_number, coordinates, bounding_boxes, bounding_boxes_url, face_image} \| null | no |  |  | 用於識別包含多人的影片中目前說話者的設定。 |
| `options.active_speaker_detection.auto_detect` |  | boolean \| null | no |  |  | 自動識別目前說話者，並對該人物套用生成。 |
| `options.active_speaker_detection.v3` |  | boolean \| null | no |  |  | 使用 v3 說話者偵測功能。 |
| `options.active_speaker_detection.use_v2` |  | boolean \| null | no |  |  | 已棄用的 v2 說話者偵測設定。 |
| `options.active_speaker_detection.frame_number` |  | integer \| null | no |  | ≥ 0 | 用於手動選取說話者座標的影格索引。 |
| `options.active_speaker_detection.coordinates` |  | array of integer \| null | no |  | 2 – 2 items | 以 [x, y] 表示的臉部參考點，指定影格 frame_number 中說話者的位置。 |
| `options.active_speaker_detection.bounding_boxes` |  | array of array of integer \| null | no |  |  | 每個影格偵測到的臉部邊界框，以 [x1, y1, x2, y2] 表示。 |
| `options.active_speaker_detection.bounding_boxes_url` |  | string \| null | no |  |  | 提供每個影格邊界框的 JSON 檔案 URL。 |
| `options.active_speaker_detection.face_image` |  | string \| null | no |  |  | 以 Base64 編碼的臉部圖像，用於手動選取說話者。 |
| `options.occlusion_detection_enabled` |  | boolean \| null | no |  |  | 遮擋偵測開關；由於 sync-3 會自動偵測，因此對其沒有作用；其他情況下，此設定控制生成是否包含遮擋偵測。 |

File parameters (`video`, `audio`) take a public `https://` URL, a `data:` URI up to 10 MB, or the `file_url` of an upload from `POST /files`.

## Example input

Required parameters only:

```json
{
  "video": "https://content.doitong.com/video/showcase/v3/avatar/talking_avatar_loop.mp4",
  "audio": "https://content.doitong.com/audio/showcase/v3/tools/dub_es.mp3"
}
```

A fuller example:

```json
{
  "video": "https://content.doitong.com/video/showcase/v3/avatar/talking_avatar_loop.mp4",
  "audio": "https://content.doitong.com/audio/showcase/v3/tools/dub_es.mp3"
}
```

## Run it

Set `DOITONG_API_KEY` to a key from https://doitong.com/developers/dashboard#keys. `?wait=20` returns the finished request in the same call when it is ready within 20 seconds; otherwise poll `GET /requests/{id}` (it also accepts `?wait=`), or pass `webhook_url`.

### curl

```bash
# Run the model; wait up to 20 s for the finished result in the same call
curl -X POST "https://api.doitong.com/v1/run/sync-lipsync/v3?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video": "https://content.doitong.com/video/showcase/v3/avatar/talking_avatar_loop.mp4",
    "audio": "https://content.doitong.com/audio/showcase/v3/tools/dub_es.mp3"
  }'

# Still "queued" or "running"? Poll with the id from the response:
curl "https://api.doitong.com/v1/requests/REQUEST_ID?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY"
```

### JavaScript

```javascript
const API = "https://api.doitong.com/v1";
const headers = {
  "Authorization": "Bearer " + process.env.DOITONG_API_KEY,
  "Content-Type": "application/json",
};

// Run the model; wait up to 20 s for the finished result in the same call
let res = await fetch(API + "/run/sync-lipsync/v3?wait=20", {
  method: "POST",
  headers,
  body: JSON.stringify({
    "video": "https://content.doitong.com/video/showcase/v3/avatar/talking_avatar_loop.mp4",
    "audio": "https://content.doitong.com/audio/showcase/v3/tools/dub_es.mp3"
  }),
});
let request = await res.json();
if (!res.ok) throw new Error(request.error.code + ": " + request.error.message);

// Not finished yet: long-poll until it is
while (request.status === "queued" || request.status === "running") {
  res = await fetch(API + "/requests/" + request.id + "?wait=20", { headers });
  request = await res.json();
}
if (request.status !== "succeeded") throw new Error(JSON.stringify(request.error));
console.log(request.outputs.map((o) => o.url), request.cost.credits + " API credits ($" + request.cost.usd + ")");
```

### Python

```python
import os
import requests

API = "https://api.doitong.com/v1"
headers = {"Authorization": "Bearer " + os.environ["DOITONG_API_KEY"]}

payload = {
    "video": "https://content.doitong.com/video/showcase/v3/avatar/talking_avatar_loop.mp4",
    "audio": "https://content.doitong.com/audio/showcase/v3/tools/dub_es.mp3",
}

# Run the model; wait up to 20 s for the finished result in the same call
r = requests.post(API + "/run/sync-lipsync/v3", params={"wait": 20}, json=payload, headers=headers)
request = r.json()
if not r.ok:
    raise RuntimeError(request["error"]["code"] + ": " + request["error"]["message"])

# Not finished yet: long-poll until it is
while request["status"] in ("queued", "running"):
    request = requests.get(API + "/requests/" + request["id"], params={"wait": 20}, headers=headers).json()
if request["status"] != "succeeded":
    raise RuntimeError(request["error"])
print([o["url"] for o in request["outputs"]], request["cost"]["credits"], "API credits", "$" + request["cost"]["usd"])
```

### MCP

The MCP server at `https://api.doitong.com/v1/mcp` exposes the tools `search_models`, `get_model`, `quote`, `run`, `get_request`, `cancel_request`, `list_requests`, `create_upload` and `get_account`. A `run` call for this model:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "run",
    "arguments": {
      "model_id": "sync-lipsync/v3",
      "input": {
        "video": "https://content.doitong.com/video/showcase/v3/avatar/talking_avatar_loop.mp4",
        "audio": "https://content.doitong.com/audio/showcase/v3/tools/dub_es.mp3"
      },
      "wait_seconds": 20
    }
  }
}
```

## Response

Every call returns a request object. `status` is one of `queued`, `running`, `succeeded`, `failed`, `canceled`. `outputs` lists the generated files with URLs on our storage (kept forever, or 7 days with `?storage=temporary`; `storage` says which); `output` is the model's own result object with the same URLs.

```json
{
  "id": "req_8k2m4q7x1z9c3v5b6n0p2r4t",
  "object": "request",
  "model": "sync-lipsync/v3",
  "status": "succeeded",
  "created_at": "2026-10-20T12:00:00Z",
  "started_at": "2026-10-20T12:00:02Z",
  "completed_at": "2026-10-20T12:00:09Z",
  "queue_position": null,
  "cost": {
    "credits": 1334,
    "usd": "1.334",
    "charged": 1334,
    "refunded": 0
  },
  "input": {
    "video": "https://content.doitong.com/video/showcase/v3/avatar/talking_avatar_loop.mp4",
    "audio": "https://content.doitong.com/audio/showcase/v3/tools/dub_es.mp3"
  },
  "output": {
    "video": {
      "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.mp4",
      "content_type": "video/mp4",
      "file_name": "0-output.mp4",
      "file_size": 1843200
    }
  },
  "outputs": [
    {
      "type": "video",
      "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.mp4",
      "content_type": "video/mp4",
      "file_size": 1843200,
      "width": 1280,
      "height": 720,
      "duration": 5,
      "stored": true
    }
  ],
  "error": null,
  "metrics": {
    "inference_seconds": 6.8
  },
  "urls": {
    "self": "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t",
    "cancel": "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/cancel"
  }
}
```

### Output fields (`output`)

| Field | Type | Description |
|---|---|---|
| `video` | object {url, content_type, file_name, file_size} | 模型產生的影片。 |

## Related models

- [Sync React-1](https://doitong.com/developers/models/sync-lipsync/react-1.md) (`sync-lipsync/react-1`): $10.00 / minute of output video
- [sync-3 Avatar Image to Video](https://doitong.com/developers/models/sync-lipsync/v3/image-to-video.md) (`sync-lipsync/v3/image-to-video`): $8.00 / minute of input audio
- [Kling AI Avatar 2.0 Pro](https://doitong.com/developers/models/kling-video/ai-avatar/v2/pro.md) (`kling-video/ai-avatar/v2/pro`): $0.115 / second of input audio
- [VEED Fabric 1.0](https://doitong.com/developers/models/veed/fabric-1.0.md) (`veed/fabric-1.0`): from $0.08 / second of input audio
- [Sync Lipsync](https://doitong.com/developers/models/sync-lipsync/v2/pro.md) (`sync-lipsync/v2/pro`): $5.00 / minute of output video
- [Sync Lipsync 2.0](https://doitong.com/developers/models/sync-lipsync/v2.md) (`sync-lipsync/v2`): from $3.00 / minute of output video
- [sync.so -- lipsync 1.9.0-beta](https://doitong.com/developers/models/sync-lipsync.md) (`sync-lipsync`): $0.70 / minute of output video
- [AI Avatar Multi](https://doitong.com/developers/models/ai-avatar/multi.md) (`ai-avatar/multi`): from $0.20 / second of output video

## Links

- HTML page: https://doitong.com/developers/models/sync-lipsync/v3
- All models and guides for AI agents: https://doitong.com/developers/llms.txt
- OpenAPI 3.1 with this model's typed request body: https://doitong.com/developers/openapi.json?model=sync-lipsync/v3
- Errors: https://doitong.com/developers/docs/errors
- Model details as JSON: https://api.doitong.com/v1/models/sync-lipsync/v3