FreeLipSync API 开发文档

开始之前

FreeLipSync REST API 支持使用自有音频生成视频对口型、图片说话和音乐视频。你需要注册账号，在智能体控制台创建 API Key，并使用 API 点数。新老账号首次进入智能体控制台读取余额，或首次有效提交生成时，均可一次性获得 30 点体验额度；用完可充值。Free 账号也可充值；订阅会员没有周期赠点，会员等级体现在模型、时长和账号任务限制上。

本文使用 https://freelipsync.com/api/v1。在 staging 测试时，把 FLS_BASE_URL 改为对应环境的站点域名，并使用该环境创建的 Key；该部署需已启用 API 功能。示例准备一张单人正脸图片 face.jpg 和一段较短的驱动音频 speech.mp3。

OpenAPI 接口定义可供工具读取完整字段结构。如果希望通过智能体操作，请看 MCP 接入说明。

认证与第一次请求

在控制台创建密钥，在创建后的弹窗中复制并保存。完整密钥仅显示一次；遗失后需要撤销并重建。将密钥保存在环境变量中，不要放进公开网页代码或提交到代码仓库。所有密钥共用账号余额和限制，增加 Key 不会增加并发。

export FLS_BASE_URL='https://freelipsync.com'
export FLS_API_KEY='YOUR_API_KEY'
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $FLS_API_KEY" \
  "$FLS_BASE_URL/api/v1/capabilities"

REST 使用 API Key。MCP OAuth 授权得到的 access token 只适用于 /mcp，不能用于 REST。成功响应以 data 包装结果，并附带 request_id；失败响应包含 error 和 request_id。资源 ID 是不透明字符串，点数金额使用十进制字符串。

{"data":{"id":"YOUR_ASSET_ID","kind":"image","status":"processing","poll_after_seconds":5,"expires_at":"2026-10-21T00:00:00.000Z"},"request_id":"REQUEST_ID"}

上面仅为素材响应的结构示例，不是 capabilities 请求的响应。开始上传前，读取 capabilities 返回的可用模型、max_audio_seconds、上传字节/MIME 限制及任务限制。

生成流程

1. 查询能力，上传图片或视频，以及驱动音频。
2. 确认直传完成，等待两个素材均为 ready。
3. 使用素材 ID、模式和参数取得报价，检查 total_points 与 expires_at。
4. 使用稳定的幂等键提交报价。此时才接单并预扣点数。
5. 按 poll_after_seconds 查询返回的任务 ID，或接收 Webhook。
6. 完成后通过签名链接下载；处理失败返还原预扣。

素材上传和报价不扣点，也不创建生成任务。任务接单后不可取消；仅处理失败返点。客户端超时不等于生成失败。

本地上传与 URL 导入

本地文件先通过 POST /assets 取得签名 PUT 地址，按返回的 upload.headers 上传原始字节，不要向存储地址发送 API Key。随后以 {} 请求 POST /assets/{id}/confirm，再通过 GET /assets/{id} 等待就绪。awaiting_upload 与 processing 都不能用于报价，failed 是失败终态。轮询间隔以服务端建议为准。

{
  "kind":"image",
  "source":{
    "type":"upload",
    "filename":"face.jpg",
    "content_type":"image/jpeg",
    "size_bytes":123456
  }
}

size_bytes 必须填写真实文件字节数，不能照抄示例数值。图片、视频、音频的 MIME 和大小限制不同，请以 GET /capabilities 为准；仅修改扩展名不能改变文件有效性。

也可导入公网可访问的 HTTPS URL，返回后异步处理，仍需查询素材直到 ready。本地路径、file://、内网地址或需要网页登录 Cookie 的 URL 都不能作为来源。使用签名源链接时，需要给后台抓取留足有效期。

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $FLS_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: image-import-UNIQUE-REQUEST-ID' \
  --data '{"kind":"image","source":{"type":"url","url":"https://YOUR-PUBLIC-HOST/face.jpg"}}' \
  "$FLS_BASE_URL/api/v1/assets"

第三条路径是以 {"kind":"image"} 调用 POST /asset-upload-sessions，把 browser_upload_url 交给用户在网页上传，调用方保留 asset_id 并查询就绪状态。适合无法读取用户本地文件的客户端。上传 ticket 和签名链接属于临时凭据，不要公开到日志或聊天记录。

完整代码示例

在下方 Tab 选择 cURL、Python 或 JavaScript。三套示例执行相同的上传 → 报价 → 提交 → 查询 → 下载流程，先打印报价，确认后才花点。长代码默认收起，可以展开；「复制」始终复制完整程序。

• cURL：需要 Bash、cURL、jq 和 Python 3（用于 UUID），保存为 Bash 脚本执行。
• Python：需要 Python 3 与 requests，先执行 python -m pip install requests。
• JavaScript：需要 Node.js 20+，仅使用内置模块，保存为 quickstart.mjs，执行 node quickstart.mjs。

设置上面的环境变量，把 face.jpg 和 speech.mp3 放在运行目录。在服务端或开发机运行，不要把密钥放进公开网页；签名上传/下载请求均不携带 Key。HTTP 错误会停止执行，重试前先看下方恢复规则，不要用新键从头重跑可能已接单的请求。

# Requires bash, curl and jq. Set these before running:
# export FLS_API_KEY='YOUR_API_KEY'
# export FLS_BASE_URL='https://freelipsync.com'  # or your staging origin
# Place face.jpg and speech.mp3 in this directory.
set -euo pipefail
: "${FLS_API_KEY:?Set FLS_API_KEY first}"
BASE="${FLS_BASE_URL:-https://freelipsync.com}/api/v1"
RUN="$(python3 -c 'import uuid; print(uuid.uuid4())')"
request() {
  curl --fail-with-body --silent --show-error \
    -H "Authorization: Bearer $FLS_API_KEY" "$@"
}
wait_ready() {
  local id="$1" row status
  for ((i=0; i<120; i++)); do
    row="$(request "$BASE/assets/$id")"

模型、参数与计费

所有模式都需要上传驱动音频。首版没有 TTS、克隆声音或取消参数。Image Super / Motion Control 需要 Starter 或 Pro，仅充值不会开通该会员能力。各模式可用性与时长上限，包括模型自身例外，请读取 capabilities。

按服务端核验的有效音频时长向上取整到秒，最低计费 5 秒。例如 5 秒 Image Fast 为 5 点，Image Max 为 10 点，Image Super / Music Video 为 15 点。报价不扣点；提交后预扣报价金额，成功按原预扣结算，处理失败释放原预扣，不在生成后追加价差。购买点数与会员独立，长期有效，不支持现金退款。

{
  "mode":"image_super",
  "face_asset_id":"READY_IMAGE_ID",
  "audio_asset_id":"READY_AUDIO_ID",
  "options":{"motion":{"action":"Smile gently","camera":"Static camera"}}
}

Music Video 使用 mode: "music_video"，搭配下方 MV 参数。version 为 1.0 或 1.1；ratio 为 21:9、16:9、4:3、1:1、3:4 或 9:16；resolution 为 480p 或 720p。默认值分别为 1.0、16:9、480p，实际 schema 以 capabilities 为准。不要把 motion 参数用于其他模式，也不要传网页内部模型别名。

{
  "mode":"music_video",
  "face_asset_id":"READY_IMAGE_ID",
  "audio_asset_id":"READY_AUDIO_ID",
  "options":{"mv":{"version":"1.0","ratio":"16:9","resolution":"480p","style":{"directorial":"A calm performance","artistic":"Warm evening light"}}}
}

接口目录

以下路径均相对 /api/v1，业务请求均需认证。

列表默认 20 条，最多 50 条；下一页原样传回 data.next_cursor。多个运行中任务可使用逗号分隔的 ids 一次查询，避免逐任务轮询。这里列的是 API/MCP 点数任务，不是历史网页任务的通用列表。

幂等、错误与限流

每个独立写操作使用新的 Idempotency-Key，同一个操作的重试必须沿用原键和完全相同的参数。键为 8–128 个可见 ASCII 字符。用户发起新需求才换键，网络重试不换键。示例在提交前打印报价/幂等键，生产应用应先持久保存这对值，再发送请求并保存任务 ID。提交结果不明时不要从头重跑整个示例，否则会创建新键。

报价有效期为 10 分钟。明确未接单的拒绝可以修正请求或重新报价；结果不明则先恢复原提交。对已接单请求的幂等重放会返回原任务，不会再次预扣。同一报价不能换键消费第二次。

REST 与 MCP 共用账号读取/辅助请求桶：Free 30、Starter 30、Pro 60 次/分钟。上传、确认、报价属于辅助请求。遵守 poll_after_seconds 与 Retry-After，取需要等待更久的一个。网页状态读取独立管理；生成频率与视频执行资源在网页、REST、MCP 三个入口间共用。网页与 API/MCP 各自有一组未完成任务名额，每组 Free 1、Starter 3、Pro 10；REST 与 MCP、所有 Key 和 OAuth 连接共用 API/MCP 组，不因增加凭据而增额。工作流例子见为什么用 API/MCP。

下载结果与可选 Webhook

任务状态为 queued、processing、completed、failed。应用超时后保留任务 ID，客户端超时不会取消服务端任务。成功后在有效期内使用 output.download_url；作品仍在保留期时，可重新查询任务或下载接口以取得新链接，重复获取不额外扣点。作品保留策略与账号普通作品一致，不单独设置 API 保留期。付费作品为原画质、无水印，可在拥有素材权利并遵守条款的前提下商用。

服务端集成可在智能体控制台的高级设置中创建 Webhook，提交任务时带上 webhook_endpoint_id。端点需先将 endpoint.verification POST 中的 challenge 原样作为纯文本响应。Webhook 管理使用网页控制台，不开放为公共凭据管理接口。

事件包含 event_id、event_type、occurred_at、generation_id、data；Webhook 不携带下载链接，需查询任务取得新链接。验证 FLS-Webhook-Signature 时，必须使用原始请求体：以端点 secret 对 timestamp + "." + body 计算 HMAC-SHA256，timestamp 来自 FLS-Webhook-Timestamp。用常量时间比较匹配一个 v1 签名，并检查时间窗口以防重放。按 event_id / FLS-Webhook-Id 去重，尽快返回 2xx；重复通知不能再次生成或重复执行业务。首次接入建议先用轮询跑通。

想从智能体中使用？继续看 MCP 接入说明，或回到智能体控制台。