ComfyPilotComfyPilot
文档 / 开发 / 通过 Comfy Router 使用 Sync 3

通过 Comfy Router 使用 Sync 3

通过 Comfy Router 调用 synclabs/sync-3：端点、请求结构以及 Router 返回的响应。

开发 code 更新于 2026-10-11

查看官方原文

通过 Comfy Router 使用 Sync 3

通过 Comfy Router 调用 synclabs/sync-3：端点、请求结构以及 Router 返回的响应。

synclabs/sync-3 的 API 参考，由 Comfy Router 从 Synclabs 提供。

输入： 视频, 图像, 音频, 文本 · 输出： 视频

快速开始

在你的 Comfy 工作区中创建密钥，并将其导出为 COMFY_API_KEY。Python 和 TypeScript 代码片段使用 Comfy SDK（pip install comfy-sdk 和 npm install @comfyorg/sdk）；cURL 代码片段是通过原生 HTTP 发起的同一调用。

模型 ID： synclabs/sync-3

端点： POST https://api.comfy.org/v2/models/synclabs/sync-3

[tab] 等待结果 ``python Python theme={null} from comfy_sdk import Comfy # 从环境变量中读取 COMFY_API_KEY。 # SDK 会自动创建幂等键，并在自动重试时复用它。 with Comfy() as client: result = client.models.run( "synclabs/sync-3", { "input": [ { "type": "video", "url": "https://example.invalid/synclabs/sync-3/speaker.mp4", }, { "type": "audio", "url": "https://example.invalid/synclabs/sync-3/voiceover.wav", }, ], "options": { "sync_mode": "bounce", }, }, ) print(result) ` `typescript TypeScript theme={null} import { comfy } from "@comfyorg/sdk"; // 从环境变量中读取 COMFY_API_KEY。 // SDK 会自动创建幂等键，并在自动重试时复用它。 const { data } = await comfy.models.run("synclabs/sync-3", { input: [ { type: "video", url: "https://example.invalid/synclabs/sync-3/speaker.mp4", }, { type: "audio", url: "https://example.invalid/synclabs/sync-3/voiceover.wav", }, ], options: { sync_mode: "bounce", }, }); console.log(data); ` `bash cURL theme={null} curl https://api.comfy.org/v2/models/synclabs/sync-3 \ -H "X-API-Key: $COMFY_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d "{\"input\": [{\"type\":\"video\",\"url\":\"https://example.invalid/synclabs/sync-3/speaker.mp4\"},{\"type\":\"audio\",\"url\":\"https://example.invalid/synclabs/sync-3/voiceover.wav\"}], \"options\": {\"sync_mode\":\"bounce\"}}" ``
[tab] 排队并稍后收集 相同的请求体，发送到 POST https://api.comfy.org/v2/models/synclabs/sync-3/requests。一旦运行被接纳，Router 就会返回 201 和 request_id，结果就绪后即可从当前进程或另一个进程收集。队列交付 介绍了状态、取消和收集。 ``python Python theme={null} import asyncio from comfy_sdk import AsyncComfy # 从环境变量中读取 COMFY_API_KEY。 # 每次 submit() 调用都会生成自己的 Idempotency-Key，并在自动重试时复用它。 async def main(): async with AsyncComfy() as client: handle = await client.models.submit( "synclabs/sync-3", { "input": [ { "type": "video", "url": "https://example.invalid/synclabs/sync-3/speaker.mp4", }, { "type": "audio", "url": "https://example.invalid/synclabs/sync-3/voiceover.wav", }, ], "options": { "sync_mode": "bounce", }, }, ) print("request_id:", handle.request_id) # 加上模型 ID，就是另一个进程所需的全部信息 # 轮询直到请求完成，每次等待服务器指定的 Retry-After。 async for update in handle.iter_events(): print(update.status, update.queue_position) # 提供商自己的载荷，与 models.run() 返回的值相同。 # 失败或已取消的请求会在此处抛出类型化的 Router 错误。 result = await handle.get() print(result) asyncio.run(main()) ` `typescript TypeScript theme={null} import { comfy } from "@comfyorg/sdk"; // 从环境变量中读取 COMFY_API_KEY。 // 每次 submit() 调用都会生成自己的 Idempotency-Key，并在自动重试时复用它。 const handle = await comfy.models.submit("synclabs/sync-3", { input: [ { type: "video", url: "https://example.invalid/synclabs/sync-3/speaker.mp4", }, { type: "audio", url: "https://example.invalid/synclabs/sync-3/voiceover.wav", }, ], options: { sync_mode: "bounce", }, }); console.log("requestId:", handle.requestId); // 加上模型 ID，就是另一个进程所需的全部信息 // 轮询直到请求完成，每次等待服务器指定的 Retry-After。 for await (const update of handle.events()) { console.log(update.status, update.queuePosition); } // 与 models.run() 返回的结果相同。失败或已取消的请求会在此处被拒绝。 const result = await handle.get(); console.log(result.data); ` `bash cURL theme={null} # 1. 提交。Router 返回 201，并带有 request_id、status_url、response_url 和 cancel_url。 curl https://api.comfy.org/v2/models/synclabs/sync-3/requests \ -H "X-API-Key: $COMFY_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d "{\"input\": [{\"type\":\"video\",\"url\":\"https://example.invalid/synclabs/sync-3/speaker.mp4\"},{\"type\":\"audio\",\"url\":\"https://example.invalid/synclabs/sync-3/voiceover.wav\"}], \"options\": {\"sync_mode\":\"bounce\"}}" # 2. 轮询直到状态为 COMPLETED，每次响应都等待其指定的 Retry-After 秒数。 REQUEST_ID="<request_id from the 201 body>" curl -i https://api.comfy.org/v2/models/synclabs/sync-3/requests/$REQUEST_ID/status \ -H "X-API-Key: $COMFY_API_KEY" # 3. 收集。返回 200 及模型的原生输出，仍在运行时则返回 202 及状态正文。 curl https://api.comfy.org/v2/models/synclabs/sync-3/requests/$REQUEST_ID \ -H "X-API-Key: $COMFY_API_KEY" ``

Schema

输入

dubParams object

附加到 Sync Labs 生成请求的配音参数

dubParams.numSpeakers integer

来源视频中的说话人数；0 表示启用自动检测

dubParams.providerName string required

用于配音的提供商（例如 elevenlabs）

dubParams.sourceLang string

来源语言代码；默认为 auto

dubParams.targetLang string required

配音的目标语言代码

input object[] required

输入项；恰好一个视觉输入（视频或图像）和一个音频或文本输入

input\[].assetId string

Sync Labs 媒体库中资产的 ID

input\[].provider object

用于 Sync Labs 文本输入的文本转语音提供商配置

input\[].provider.name string required

TTS 提供商名称（例如 elevenlabs）

input\[].provider.script string required

用于生成的脚本

input\[].provider.similarityBoost number

AI 应多大程度贴近原始声音

格式：double

input\[].provider.stability number

声音稳定性；较低的值会带来更宽的情感范围

格式：double

input\[].provider.voiceId string required

Sync 语音 id（从 Studio 克隆的声音）或 ElevenLabs 语音 ID

input\[].refId string

用于将此输入关联到片段定义的引用标识符

input\[].segments\_frames integer[][]

弃用 - 请改用顶层的 segments 数组

input\[].segments\_secs number[][]

弃用 - 请改用顶层的 segments 数组

input\[].type string required

输入类型（video、image、audio 或 text）

input\[].url string

用于生成的媒体的 URL

model string

用于生成的模型名称；仅支持 sync-3。在 Comfy Router 路由 POST /v2/models/synclabs/{model} 上，该字段由路径提供，可以省略。

options object

可用于 Sync Labs 生成的附加选项

options.active\_speaker\_detection object

活跃说话人检测配置

options.active\_speaker\_detection.auto\_detect boolean

是否自动检测并将生成应用于活跃说话人

options.active\_speaker\_detection.bounding\_boxes integer[][]

检测到的人脸逐帧边界框数组 \[x1, y1, x2, y2]

options.active\_speaker\_detection.bounding\_boxes\_url string

包含边界框的 JSON 文件的 URL

options.active\_speaker\_detection.coordinates integer[]

由 frame\_number 标识的来源视频帧中的像素坐标 \[x, y]

options.active\_speaker\_detection.frame\_number integer

与所提供的坐标对应的帧索引，用于手动选择说话人

options.active\_speaker\_detection.v3 boolean

是否使用 ASD v3

options.model\_mode string

模型的编辑区域（lips、face、head）；仅适用于 react-1

options.occlusion\_detection\_enabled boolean

是否在生成期间检测遮挡

options.prompt string

情感提示词；仅适用于 react-1

options.sync\_mode string

如何处理视频与音频之间的时长不匹配（bounce、loop、cut\_off、silence、remap）

options.temperature number

口型同步的表现力程度，0 到 1

格式：double

outputFileName string

已生成输出的基础文件名，不含扩展名

projectId string

可选：将此生成附加到 Sync Labs 项目

segments object[]

将不同音频输入应用到不同视频片段的片段定义

segments\[].audioInput object required

特定片段的音频输入配置

segments\[].audioInput.endTime number

可选，用于裁剪所引用音频的结束时间（秒）

格式：double

segments\[].audioInput.refId string required

用于此片段的音频/文本转语音输入的引用 ID

segments\[].audioInput.startTime number

可选，用于裁剪所引用音频的开始时间（秒）

格式：double

segments\[].endTime number required

片段结束时间（秒）

格式：double

segments\[].optionsOverride object

覆盖特定片段的生成选项

segments\[].optionsOverride.active\_speaker\_detection object

活跃说话人检测配置

segments\[].optionsOverride.active\_speaker\_detection.auto\_detect boolean

是否自动检测并将生成应用于活跃说话人

segments\[].optionsOverride.active\_speaker\_detection.bounding\_boxes integer[][]

检测到的人脸逐帧边界框数组 \[x1, y1, x2, y2]

segments\[].optionsOverride.active\_speaker\_detection.bounding\_boxes\_url string

指向包含边界框的 JSON 文件的 URL

segments\[].optionsOverride.active\_speaker\_detection.coordinates integer[]

由 frame\_number 标识的来源视频帧中的像素坐标 \[x, y]

segments\[].optionsOverride.active\_speaker\_detection.frame\_number integer

与手动选择说话人时提供的坐标相对应的帧索引

segments\[].optionsOverride.active\_speaker\_detection.v3 boolean

是否使用 ASD v3

segments\[].optionsOverride.occlusion\_detection\_enabled boolean

为此片段覆盖遮挡检测设置

segments\[].optionsOverride.sync\_mode string

为此片段覆盖同步模式

segments\[].optionsOverride.temperature number

为此片段覆盖 temperature（0-1）

格式：double

segments\[].startTime number required

片段开始时间，单位为秒

格式：double

webhookUrl string

用于接收生成状态更新的 Webhook URL

根据 Router 在 GET /v2/models/synclabs/sync-3/openapi.json 提供的 schema 生成，该文档也是请求到达提供商之前用于校验调用的同一份文档。

输出

createdAt string

生成内容的创建日期和时间

error string

生成失败时的报错信息

errorCode string

生成失败时的稳定、机器可读的错误代码

id string

生成的唯一标识符

input object[]

用于生成的输入项

input\[].assetId string

Sync Labs 媒体库中资源的 ID

input\[].provider object

Sync Labs 文本输入的文本转语音提供商配置

input\[].provider.name string required

TTS 提供商名称（例如 elevenlabs）

input\[].provider.script string required

用于生成的脚本

input\[].provider.similarityBoost number

AI 应多接近原始声音

格式：double

input\[].provider.stability number

声音稳定性；较低的值会带来更丰富的情感范围

格式：double

input\[].provider.voiceId string required

Sync 声音 ID（从 Studio 克隆的声音）或 ElevenLabs 声音 ID

input\[].refId string

用于将此输入关联到分段定义的引用标识符

input\[].segments\_frames integer[][]

已弃用：请改用顶层的 segments 数组

input\[].segments\_secs number[][]

已弃用：请改用顶层的 segments 数组

input\[].type string required

输入类型（video、image、audio 或 text）

input\[].url string

用于生成的媒体的 URL

model string

用于生成的模型名称

options object

Sync Labs 生成可用的附加选项

options.active\_speaker\_detection object

活跃说话人检测配置

options.active\_speaker\_detection.auto\_detect boolean

是否自动检测并将生成应用到活跃说话人

options.active\_speaker\_detection.bounding\_boxes integer[][]

检测到的人脸逐帧边界框数组 \[x1, y1, x2, y2]

options.active\_speaker\_detection.bounding\_boxes\_url string

包含边界框的 JSON 文件的 URL

options.active\_speaker\_detection.coordinates integer[]

由 frame\_number 标识的源视频帧中的像素坐标 \[x, y]

options.active\_speaker\_detection.frame\_number integer

与所提供的坐标对应的帧索引，用于手动选择说话人

options.active\_speaker\_detection.v3 boolean

是否使用 ASD v3

options.model\_mode string

模型的编辑区域（嘴唇、面部、头部）；仅适用于 react-1

options.occlusion\_detection\_enabled boolean

是否在生成过程中检测遮挡

options.prompt string

情感提示词；仅适用于 react-1

options.sync\_mode string

如何处理视频与音频之间的时长不匹配（bounce、loop、cut\_off、silence、remap）

options.temperature number

口型同步的表现力程度，0 到 1

格式：double

outputDuration number

输出媒体的时长，单位为秒

格式：double

outputFileName string

应用于输出媒体的已清理文件名

outputUrl string

输出媒体的 URL

projectId string

此生成所关联的项目 ID

segmentOutputUrl string

分段输出媒体的 URL

segments object[]

生成的分段

segments\[].audioInput object required

特定分段的音频输入配置

segments\[].audioInput.endTime number

用于裁剪所引用音频的可选结束时间，单位为秒

格式：double

segments\[].audioInput.refId string required

用于此分段的音频/文本转语音输入的引用 ID

segments\[].audioInput.startTime number

用于裁剪所引用音频的可选开始时间，单位为秒

格式：double

segments\[].endTime number required

分段结束时间，单位为秒

格式：double

segments\[].optionsOverride object

覆盖特定分段的生成选项

segments\[].optionsOverride.active\_speaker\_detection object

活跃说话人检测配置

segments\[].optionsOverride.active\_speaker\_detection.auto\_detect boolean

是否自动检测并将生成应用于当前说话人

segments\[].optionsOverride.active\_speaker\_detection.bounding\_boxes integer[][]

检测到的人脸在每一帧的边界框数组 \[x1, y1, x2, y2]

segments\[].optionsOverride.active\_speaker\_detection.bounding\_boxes\_url string

指向包含边界框的 JSON 文件的 URL

segments\[].optionsOverride.active\_speaker\_detection.coordinates integer[]

由 frame\_number 标识的源视频帧中的像素坐标 \[x, y]

segments\[].optionsOverride.active\_speaker\_detection.frame\_number integer

用于手动选择说话人的、与所提供坐标对应的帧索引

segments\[].optionsOverride.active\_speaker\_detection.v3 boolean

是否使用 ASD v3

segments\[].optionsOverride.occlusion\_detection\_enabled boolean

覆盖此片段的遮挡检测设置

segments\[].optionsOverride.sync\_mode string

覆盖此片段的同步模式

segments\[].optionsOverride.temperature number

覆盖此片段的 temperature (0-1)

格式：double

segments\[].startTime number required

片段开始时间，单位为秒

格式：double

status string

生成的状态 (PENDING、PROCESSING、COMPLETED、FAILED、REJECTED)

synthesizedAudioUrl string

由文本 (TTS) 输入合成的音频 URL

webhookUrl string

webhook 端点的 URL

示例

输入

{
  "input": [
    {
      "type": "video",
      "url": "https://example.invalid/synclabs/sync-3/speaker.mp4"
    },
    {
      "type": "audio",
      "url": "https://example.invalid/synclabs/sync-3/voiceover.wav"
    }
  ],
  "options": {
    "sync_mode": "bounce"
  }
}

输出

{
  "createdAt": "2026-01-01T00:00:00.000Z",
  "id": "9a3d0c1e-0000-4000-8000-000000000000",
  "model": "sync-3",
  "outputDuration": 4.25,
  "outputFileName": "lipsync",
  "outputUrl": "https://example.invalid/synclabs/sync-3/output.mp4",
  "status": "COMPLETED"
}

发布前须知

SDK 会生成 Idempotency-Key 并在自动重试中复用它。手动重试时，请复用原始 key。Router 最长可保持连接 10 分钟。

请求失败时，Router 会发送 X-Comfy-Error-Type 响应头说明原因。422 表示 Router 在调用提供商之前就拒绝了输入，413 表示请求体超出了 Router 可接受的大小。已生成的资源请及时下载，因为结果 URL 会过期。

上文任何字段描述中提到的尺寸限制，都是提供商对该字段自身的限定，引自提供商的规范。Router 会对整个请求体另行设置上限，base64 编码的媒体内容也计入其中：参见请求体大小。

本页记录的是通过 Comfy Router 调用的某一个合作伙伴模型。同一个 comfy-sdk / @comfyorg/sdk 包还提供第二个客户端，用于在 Comfy Cloud 上运行完整的 ComfyUI 工作流图：Comfy(api_key=...) / new Comfy({ apiKey })，并带有 client.workflows、client.assets 和 client.jobs。请参阅 Comfy SDKs。

[card] 请求头 身份验证、幂等性、请求 ID、错误分类、重试节奏、消费限额。
[card] 使用 Router API 模型发现、验证错误、重试与计费。
[card] 限制 Router 目前不支持的功能，以及替代方案。