EN 返回首页

API 文档

可编程译制管线 · beta 按需开通 · 更新于 2026 年 10 月 15 日

API 现状：以下即我们自家工作台正在使用的真实接口，封闭 beta 中对外按需开通。API key 按申请发放——邮件 [email protected] 说明场景与用量即可。Webhook 与按 key 限速在近期内 roadmap，下方明确标注规划中；我们不虚构还没跑通的功能。

快速上手

Base URL https://app.voxtakes.com/api。现阶段使用浏览器会话 Cookie 鉴权；beta key 用户获发 Authorization: Bearer。一次完整译制只要三步：

# 1. 预约上传位，PUT 你的文件到对象存储
curl -X POST https://app.voxtakes.com/api/uploads \
  -H 'content-type: application/json' \
  -d '{"name":"launch.mp4","type":"video/mp4","size":52428800}'

curl -X PUT --upload-file launch.mp4 "<返回的 uploadUrl>"

# 2. 创建任务
curl -X POST https://app.voxtakes.com/api/jobs \
  -H 'content-type: application/json' \
  -d '{"src":{"kind":"upload","key":"users/…/launch.mp4"},
       "langs":["es","de"],
       "delivery":{"subs":true,"dub":true,"clean":true},
       "style":"bold_pop",
       "glossary":[{"term":"ZELOS","keep":true}]}'

# 3. 轮询进度
curl https://app.voxtakes.com/api/jobs/<id>

接口一览

POST/uploads

入参 {name, type, size}（≤500 MB）。返回存储 key 与限时签名 uploadUrl，直接裸 PUT 上传，该请求不带任何凭据。

POST/jobs

创建译制任务，字段：

字段说明
src{kind:"upload", key} 或 {kind:"url", url}（YouTube）。链接拉取属便利路径，上传才是稳定路径——上游平台会对服务端抓取做风控。
langs目标语言数组，取 en es de fr pt ja ko zh（ar 为 beta，需申请）。源语言自动识别。
delivery{subs, dub, clean}——纯字幕、配音、或两者；clean:true 先从画面擦除烧录字幕（一次擦除，全语言共用）。
style字幕预设：clean 简洁 / bold_pop 醒目 / word_highlight 逐词高亮 / bilingual 双语。
glossary可选按任务术语锁定：{term, translations?:{lang→text}, keep?:bool}；keep:true=所有语言原样保留。

响应含 credits_preauth（预扣估算；按实际成片分钟结算）。

GET/jobs/:id

任务状态机。status ∈ queued → running → awaiting_review → done（另有 failed / cancelled）。运行中给出每语言阶段时间线：

clean → asr → translate:<lang> → tts_qc:<lang> → mix:<lang> → bundle

tts_qc 对每一句做“回听转写比对”产出 0–1 质量分；低分句被标记待审而非静默交付。awaiting_review 时 results[lang].lines 逐句暴露时间码、译文、分数与音频。

POST/jobs/:id/redub

单句修改，不动其余：

-d '{"lang":"es","edits":[
       {"line_id":7,"text":"新文本"},
       {"line_id":12,"seed":"重抽一条"},
       {"line_id":20,"voice":"alt_02"}]}'

计费 每重录句 1 额度。新旧两条音轨都保留，可 A/B 后再替换母版。若原任务用了 clean，重配复用已擦除母版——擦除费绝不重复收。

POST/jobs/:id/retry

仅重跑失败/取消的阶段；已通过 QC 的部分永不重渲染、永不重复计费。

GET/jobs/:id/bundle

整包 zip：各语言 MP4 + SRT/VTT + 逐句音频 + 术语命中报告。素材 7 天自动删除，请及时下载。

GET/glossary · POST/glossary

工作区级术语表，跨任务持久（增删改查同上）。

额度与计费

项目消耗
配音成片（每语言）1 额度/成片分钟
纯字幕交付0.4 额度/成片分钟
硬字幕擦除+0.5 额度/成片分钟，按任务只收一次
单句重录1 额度/句；QC 不合格导致的重录免费

Creator 定价下 1 额度 ≈ $0.48。额度不过期；超出按 $0.89/成片分钟。

错误码

状态 · code含义
400 invalid_request参数问题（消息里带字段名）。
401 unauthenticated会话/key 缺失或过期。
402 insufficient_credits额度不足。
403 not_approved账户尚未通过内测审核。
404 not_found任务不存在或素材已过期。
409 job_conflict同一任务有其他变更进行中。
500 / 超时我方问题——按上面的 retry 规则免费重跑。

限制与计划