Skip to main content
项目配音

项目配音

根据你提供的翻译 SRT,为已有项目生成语音并混合输出。VoiceCheap 在此接口不做任何翻译:没有翻译引擎、没有 SmartSync 改写、没有术语表。每条字幕都会在项目转录的对应片段上逐字朗读,然后与原始背景、字幕和可选的口型同步混合,与常规翻译相同。 当译文在别处完成(人工译者、你自己的工具、自动化流程),只需要 VoiceCheap 生成语音时使用。运行是异步的:轮询获取翻译状态,或监听 Webhooks。

前提条件

  • 项目必须存在,并且转录必须完成:用创建项目(仅转录)或开始翻译创建,然后等待 transcriptionStatus: "success"。
  • 你的 SRT 必须覆盖项目转录:每个转录片段至少需要一条字幕,每条字幕都必须落在某个片段上。用导出项目转录导出转录,并逐条翻译以保留时间码。
  • 该请求按同一媒体的翻译计费,并进行相同的额度检查。口型同步模式会照常消耗额外额度。

并发限制

创建项目、翻译和配音都会检查账户的进行中翻译上限(最多 10 个,实际限制可能更低)。只有进行中的翻译或配音任务占用名额;仅转录的项目不占用。达到上限时,API 返回 CONCURRENT_TRANSLATION_LIMIT_REACHED(HTTP 429)。实际限制见 details.limit。 同一项目和目标语言已有任务运行时,第二次运行也会被拒绝(TRANSLATION_ALREADY_IN_PROGRESS,HTTP 409)。

请求

此接口接受 JSON 请求体(Content-Type: application/json)。布尔和数值选项以 JSON 值发送,而不是字符串。

标头

string
必填
您的 VoiceCheap API 密钥。请从 app.voicecheap.ai/page-api 获取。

路径参数

string
必填
创建项目或开始翻译返回的项目标识。

正文参数

string
必填
translatedSrt 的语言,小写,与开始翻译使用同一列表。如果项目还没有该语言的工作,会创建一个,并把该语言加入项目。
string
必填
最终的目标语言 SRT 内容(字幕编号、时间行、文本)。最多 1,000,000 个字符。字幕条按时间戳匹配到转录片段:在片段开始后 50 毫秒内开始的字幕条会分配给该片段,否则分配给重叠最多的片段。同一片段上的多条字幕用空格连接。每条朗读片段的时间、说话人和顺序始终来自项目转录;你的时间码只用于匹配。
string
一个 https 端点,从此接收此项目的Webhook 事件,并覆盖账户上配置的端点。默认值: 先使用项目中已保存的端点,然后是账户的 Webhook 端点。
boolean
在生成的语音下方保留原始背景音频(音乐、环境声)。默认值: true
boolean
在生成的语音下方小声保留原始说话人。默认值: false
number
启用 keepOriginalVoice 时原始语音的音量,范围从 1 到 70。默认值: 30
string
音色策略:cloning(克隆项目中说话人的音色)或 custom(使用目录中的音色或您保存的自定义音色)。默认值: cloning
string
当 voiceMode 为 custom 时必填。请使用 dubbing_voices_list 中的 ID:目录中的音色或经过身份验证的账户保存的自定义音色。团队计费不会授予访问其他成员已保存音色的权限。
string
启用 keepBackgroundMusic 时的人声分离模式:studio 或 realistic。默认值: studio
boolean
把字幕烧录到输出视频中。需要视频项目。默认值: false
string
启用 subtitles 时的字幕文本:translated(你的 SRT)或 original(源转录)。默认值: translated
string
配音准备好后运行口型同步:standard、pro 或 studio。方案、时长和额度规则与开始翻译相同。需要视频项目。默认值: 省略此字段可跳过口型同步。
boolean
为请求的口型同步运行启用当前说话人检测。默认值: false
object
语音克隆微调,JSON 对象包含 stability 和 similarity,取值在 0 到 1 之间。仅在 voiceMode: "cloning" 时可用。各值说明见开始翻译。
array
保留为原始语言的源时间范围,格式为 [{ "startTime": 10.2, "endTime": 12.8 }]。需要视频项目和 keepBackgroundMusic: true,不能与 keepOriginalVoice 同时使用,也不能与转录片段重叠。

响应

boolean
必填
请求成功时始终为 true。
string
必填
可供人阅读的确认信息。
string
必填
正在配音的项目。
string
必填
用于 targetLanguage 的翻译工作。它与状态、详情和转录接口中的 workId 一致。
number
必填
大致处理时间估计(分钟):源媒体每开始一分钟,处理约五分钟。
Response

跟踪运行

配音一开始,项目就会切换到 translation 流程,因此获取翻译状态会跟踪这次新运行:status 从 processing 变为 success(带有 translatedVideoUrl 和 translatedAudioUrl)或 failed(带有 error)。project.translation.completed 和 project.translation.failed Webhook 会带着相同的 targetLanguage 发送。在获取项目详情中,翻译版本会报告 settings.dubbingMode: "dub-only" 和 settings.smartSync: false。 POST 请求被接受后,对齐错误才会异步报告。状态接口返回带有 error.code 和 error.message 的 status: "failed";project.translation.failed Webhook 携带相同的代码和消息。TRANSLATED_SRT_UNMATCHED_CUES 的消息中包含未匹配的字幕条编号,TRANSLATED_SRT_MISSING_SEGMENTS 的消息中包含没有字幕条的片段索引。这些异步响应不包含结构化的 details。修正 SRT 后再次调用接口:失败的版本仍保留在项目历史中,并创建新版本。

检查语速

用导出项目转录把翻译转录导出为 JSON。每个片段都带有 finalSpeedFactor,即生成语音与片段窗口的比值。缩短大约高于 1.3 的字幕条,再用修订后的 SRT 重新配音。

示例流程

典型的自动化(例如 n8n 或 Make 场景)按以下方式串联这些接口:
  1. 使用媒体、targetLanguage 和明确的 originalLanguage 调用 POST /v1/projects(仅转录)。
  2. 轮询 GET /v1/translate/{projectId}/status,直到 transcriptionStatus 为 success,或等待 project.created Webhook。
  3. 使用 { "source": "original", "outputFormat": "srt" } 调用 POST /v1/projects/{projectId}/transcript,翻译字幕条并保留编号和时间码。
  4. 使用翻译后的 SRT 调用 POST /v1/projects/{projectId}/dub。
  5. 轮询状态接口,直到 status 为 success,或等待 project.translation.completed。
  6. 下载 translatedVideoUrl(如果请求了口型同步,则下载 lipSync.videoUrl)。
  7. 输出保存在你这边之后,调用 DELETE /v1/translate/{projectId}。

错误

运行过程中发现的对齐失败(TRANSLATED_SRT_UNMATCHED_CUES、TRANSLATED_SRT_MISSING_SEGMENTS)由状态接口和失败 Webhook 返回,而不是由本次请求返回。