跳至主要内容
OPEN APILYNSEY DUBBING
联系开通
导航

DEVELOPER DOCUMENTATION / V1

API 文档

从签名到成果下载，按同一套异步资源模型接入五项视频本地化能力。接口路径、方法与成功状态由当前 OpenAPI 规范生成。
请求基地址https://{api_host}/v1

实际 API Host 随企业版接入信息提供。所有签名路径必须包含 /v1。

快速开始

首次联调建议先用一个短视频跑通自动译制，确认签名、幂等、状态查询与文件转存。

  1. 01

    创建密钥

    企业版账户所有者或工作区管理员在“开发者 → API 密钥”创建密钥，选择能力权限、月度 Credit Quota 与 IP 白名单。

  2. 02

    准备素材

    使用可直接读取的公网 HTTPS 地址；本地视频或 SRT 先完成预签名直传。

  3. 03

    签名请求

    服务端生成时间戳和 Nonce，对实际发送的原始请求体计算 HMAC-SHA256。

  4. 04

    保存成果

    创建返回 202 后轮询资源或接收 Webhook；成功后在 expires_at 前转存文件。

POST/v1/auto-localizations
{
  "source": {
    "type": "url",
    "url": "https://media.example.com/episode-01.mp4"
  },
  "source_language": "zh-CN",
  "target_language": "en-US",
  "mode": "full",
  "voice_mode": "auto",
  "subtitle_output": "burned",
  "original_audio": "preserve",
  "resolution": "original"
}

请求签名

API Secret 只能保存在服务端。每个受保护请求必须携带以下四个请求头。

X-Lingxi-KeyAPI Key 公开标识
X-Lingxi-TimestampUnix 秒级时间戳，允许误差 300 秒
X-Lingxi-Nonce单次随机值，同一 Key 下 10 分钟内不可重复
X-Lingxi-SignatureHMAC-SHA256 小写十六进制签名

五行签名原文

HTTP_METHOD
CANONICAL_PATH_AND_QUERY
TIMESTAMP
NONCE
SHA256_HEX(RAW_REQUEST_BODY)

X-Lingxi-Signature = hex(hmac_sha256(api_secret, canonical_request))

素材上传

公网 URL 和已校验上传资源都可作为输入。本机路径、内网地址或依赖登录态的 URL 不能直接使用。

  1. 1

    申请上传预约

  2. 2

    按响应原样直传

  3. 3

    提交上传 ETag

  4. 4

    等待 status=ready

POST /v1/uploads→OBJECT STORAGE→POST /completions→GET /uploads/{id}

异步状态

创建业务资源返回 202 Accepted。202 只代表请求已持久化并进入处理流程，不代表成果已经生成。

queued→processing→
succeededfailedcancelled
queued
已持久化，等待执行
processing
正在处理，可能包含有限重试或接管
succeeded
已产生该资源承诺的最终成果
failed
无法产生该资源承诺的最终成果
cancelled
调用方主动取消，停止启动新步骤

接口参考

下列接口从 OpenAPI 3.1 规范生成，包含素材上传、五项业务能力、历史列表与积分查询。

Credits

2
GET/v1/credits

查询积分与密钥额度

Operation ID
getCredits
成功响应
200
GET/v1/credit-transactions

查询 API 消费流水

Operation ID
listCreditTransactions
成功响应
200

Uploads

4
POST/v1/uploads

申请预签名上传

Operation ID
createUpload
成功响应
201
GET/v1/uploads

查询上传文件列表

Operation ID
listUploads
成功响应
200
GET/v1/uploads/{upload_id}

查询上传和素材准备状态

Operation ID
getUpload
成功响应
200
POST/v1/uploads/{upload_id}/completions

确认直传完成

Operation ID
completeUpload
成功响应
200

Audio Separations

4
POST/v1/audio-separations

创建人声分离

Operation ID
createAudioSeparation
成功响应
202
GET/v1/audio-separations

查询人声分离列表

Operation ID
listAudioSeparations
成功响应
200
GET/v1/audio-separations/{audio_separation_id}

查询人声分离

Operation ID
getAudioSeparation
成功响应
200
DELETE/v1/audio-separations/{audio_separation_id}

取消人声分离

Operation ID
cancelAudioSeparation
成功响应
202

Subtitle Recognitions

4
POST/v1/subtitle-recognitions

创建字幕识别

Operation ID
createSubtitleRecognition
成功响应
202
GET/v1/subtitle-recognitions

查询字幕识别列表

Operation ID
listSubtitleRecognitions
成功响应
200
GET/v1/subtitle-recognitions/{subtitle_recognition_id}

查询字幕识别

Operation ID
getSubtitleRecognition
成功响应
200
DELETE/v1/subtitle-recognitions/{subtitle_recognition_id}

取消字幕识别

Operation ID
cancelSubtitleRecognition
成功响应
202

Subtitle Translations

4
POST/v1/subtitle-translations

创建字幕翻译

Operation ID
createSubtitleTranslation
成功响应
202
GET/v1/subtitle-translations

查询字幕翻译列表

Operation ID
listSubtitleTranslations
成功响应
200
GET/v1/subtitle-translations/{subtitle_translation_id}

查询字幕翻译

Operation ID
getSubtitleTranslation
成功响应
200
DELETE/v1/subtitle-translations/{subtitle_translation_id}

取消字幕翻译

Operation ID
cancelSubtitleTranslation
成功响应
202

Dubbings

4
POST/v1/dubbings

创建 AI 配音

Operation ID
createDubbing
成功响应
202
GET/v1/dubbings

查询 AI 配音列表

Operation ID
listDubbings
成功响应
200
GET/v1/dubbings/{dubbing_id}

查询 AI 配音

Operation ID
getDubbing
成功响应
200
DELETE/v1/dubbings/{dubbing_id}

取消 AI 配音

Operation ID
cancelDubbing
成功响应
202

Auto Localizations

4
POST/v1/auto-localizations

创建自动译制

Operation ID
createAutoLocalization
成功响应
202
GET/v1/auto-localizations

查询自动译制列表

Operation ID
listAutoLocalizations
成功响应
200
GET/v1/auto-localizations/{auto_localization_id}

查询自动译制

Operation ID
getAutoLocalization
成功响应
200
DELETE/v1/auto-localizations/{auto_localization_id}

取消自动译制

Operation ID
cancelAutoLocalization
成功响应
202

Webhook

创建业务资源时传入 callback_url，即可接收 succeeded、failed 或 cancelled 终态事件。Webhook 使用独立 Secret 验签。

WEBHOOK SIGNATURE

TIMESTAMP
EVENT_ID
SHA256_HEX(RAW_REQUEST_BODY)

X-Lingxi-Webhook-Signature

  • 按原始请求体字节验签
  • 按 event_id 幂等
  • 5 秒内返回任意 2xx
  • 接受重复和乱序事件
  • 保留 GET 补偿查询

错误处理

同步非 2xx 响应使用 application/problem+json。根据 code、retryable 与 Retry-After 决定修正请求或有界重试。

PROBLEMapplication/problem+json
{
  "type": "https://lynsey.cn/api/docs/errors/invalid_request",
  "title": "请求参数无效",
  "status": 400,
  "detail": "请求体或资源标识不符合接口约束。",
  "instance": "/v1/auto-localizations",
  "code": "INVALID_REQUEST",
  "request_id": "req_…",
  "retryable": false
}
HTTP / code建议动作
400INVALID_REQUEST检查 JSON、字段、签名头和幂等键。
401AUTHENTICATION_FAILED检查 Key、时间戳、Nonce 与签名。
402INSUFFICIENT_CREDITS补充额度后，以原业务参数重新提交。
403API_ACCESS_NOT_INCLUDED_IN_PLAN确认工作区所有者的企业版套餐仍有效。
403SOURCE_IP_NOT_ALLOWED从白名单出口 IP 发起请求，或调整白名单。
409IDEMPOTENCY_KEY_REUSED不同业务意图必须使用新的幂等键。
429RATE_LIMIT_EXCEEDED读取 Retry-After 后采用有界退避。
429CONCURRENCY_LIMIT_EXCEEDED等待在途媒体任务结束。
429CREDIT_QUOTA_EXCEEDED等待下个自然月或调整该 Key 的 Credit Quota。
503SERVICE_TEMPORARILY_UNAVAILABLE仅在 retryable=true 时按退避策略有界重试。

排障时提供 request_id、公共资源 ID 与发生时间；不要发送 API Secret 或 Webhook Secret。

计费与限制

单价不写死在接口文档中；以下是稳定的计量口径、素材准入和保留规则。

规则

单任务视频数1
视频时长不超过 15 分钟
视频大小小于 1 GiB
视频格式MP4、MOV、AVI、MPEG、MPG、M4V
字幕输入UTF-8 SRT 或最多 10,000 条结构化字幕行
字幕文件小于 10 MiB
资源保留从创建起最多 7 天
结果下载地址默认 24 小时，以 expires_at 为准

计量口径

人声分离源视频时长，按开始的分钟向上取整
字幕识别源视频时长，按开始的分钟向上取整
字幕翻译成功生成的字幕条数
AI 配音目标语言字符数，按开始的 1000 字符向上取整
自动译制源视频时长，按开始的分钟向上取整