跳到主要内容
剪狐短剧 API
JIANHU / DRAMA TRANSLATION API

短剧翻译 API 文档

一套面向短剧出海与漫剧批量译制的异步 REST 接口。
单任务提交 1–100 集,默认高质量原声克隆与全剧共享术语,支持可选角色分析、三档去字幕、完整字体样式设置及部分集重试。

REST · POST /api/v1/jobs type = drama_translation 更新于 2026-11-22
文档目录

快速入门

短剧翻译使用独立人民币 API 钱包,API 成片不加剪狐平台水印。先在 API 控制台创建服务端 API Key 并充值,再按以下四步接入整部短剧流水线:

  1. 按集序上传分集

    为第 1 至第 N 集分别调用上传接口直传本地 MP4,或通过公网 HTTPS 直链异步导入,等待全部分集状态为 uploaded。

  2. 创建短剧翻译任务

    向 POST /api/v1/jobs 提交 type=drama_translation,按集序传入 upload_id 列表、目标语言,按需开启角色分析、去字幕选区和字幕字体样式。

  3. 监听进度或部分重试

    通过 Webhook 或轮询 GET /api/v1/jobs/{job_id} 获取整剧与分集进度;如个别分集偶发失败,直接调用 /retry 在原任务内重试该集。

  4. 按集下载成片与字幕

    从 episodes[] 逐集下载译制视频及双语/原译文字幕文件,并可读取本次提取的全剧共享术语表与角色清单。

地址与鉴权

REST Base URL:https://unmarkai.cn/api/v1

所有请求携带 Authorization: Bearer uma_live_*。密钥仅保存在你的服务端环境变量中,切勿暴露到浏览器或客户端。创建任务、直链导入和部分集重试均需携带唯一 Idempotency-Key(1–255 位可见 ASCII 字符,24 小时内有效)。

bash
curl 'https://unmarkai.cn/api/v1/balance' \
  -H "Authorization: Bearer $UNMARKAI_API_KEY"

所需权限 scope:上传、创建、重试、取消任务需 jobs:write;查询上传与任务需 jobs:read;查询余额与短剧折后价需 balance:read。

批量上传分集

单部短剧任务支持 1–100 集。每集支持 MP4、MOV、AVI、MKV、WebM、MPEG,单集上限 2 GiB、60 分钟,分辨率最高 UHD 4K(长边 ≤ 3840、短边 ≤ 2160,横竖屏对称)。

方法 / 路径请求参数返回与行为
POST /uploadsfilename、content_type、file_size_bytes返回 201、upload_id、1 小时有效 url 及必须原样携带的 headers,直接 HTTP PUT 上传字节。
POST /url-uploadssource_url(公网可直下 HTTPS 视频地址)、filename(可选);需 Idempotency-Key返回 202,后台异步拉取并校验;轮询 GET /uploads/{upload_id} 至 status=uploaded。
GET /uploads/{upload_id}路径参数 upload_id查询分集上传状态(pending / importing / uploaded / failed / expired)。

可并发初始化并上传多集。未绑定任务的上传有效期 24 小时(最多同时保留 100 个未绑定上传、滚动 24 小时未消费上限 20 GiB);绑定进短剧任务后不再占用未绑定额度,且任务失败时在 7 天保留期内自动保留原片供部分集重试。

创建短剧翻译任务

调用 POST /api/v1/jobs,设置 type: "drama_translation",请求体最大 512 KiB,提交成功返回 HTTP 202。服务端会先并发探测全部分集真实时长与分辨率,全部校验通过后按全剧总时长冻结费用并进入处理。

json(完整功能示例:5 集短剧 + 角色分析 + 单区域去字幕 + 定制字体样式)
{
  "type": "drama_translation",
  "input": {
    "episodes": [
      { "upload_id": "upl_ep01" },
      { "upload_id": "upl_ep02" },
      { "upload_id": "upl_ep03" },
      { "upload_id": "upl_ep04" },
      { "upload_id": "upl_ep05" }
    ]
  },
  "source_language": "zh",
  "target_language": "en",
  "target_locale": "en-US",
  "advanced_quality": false,
  "cast_enabled": true,
  "subtitle_erase": {
    "enabled": true,
    "mode": "sel_area",
    "rect": { "x1": 60, "y1": 1460, "x2": 1020, "y2": 1740 }
  },
  "preserve_background_audio": true,
  "subtitle_enabled": true,
  "subtitle_mode": "translated",
  "subtitle_style": {
    "preset": "bold",
    "font_id": "montserrat",
    "primary_color": "#FFFFFF",
    "outline_color": "#000000",
    "font_weight": 800,
    "font_scale": 1.0,
    "outline_width": 4,
    "shadow": 0,
    "background_opacity": 0,
    "animation": "none"
  },
  "subtitle_layout": {
    "top_percent": 76,
    "height_percent": 16
  },
  "output_resolution": "source",
  "metadata": {
    "drama_id": "drama_20261122_01"
  }
}
字段必填 / 默认值说明
type必填,固定 drama_translation短剧批量翻译任务类型。
input.episodes必填,1–100 项按集序排列的分集数组,每项为 { "upload_id": "upl_...", "rect"?: ... },upload_id 不可重复。
target_language必填目标语言代码,如 en、es、ja、ko、id、th、pt、fr、ar 等。
target_locale可选目标地区变体(如 en-US、es-MX、pt-BR),须与 target_language 匹配。
source_language可选,默认 auto源语言代码(如 zh),默认自动识别。
advanced_quality可选,默认 falsefalse 为普通翻译(¥0.060/秒),true 为高级翻译(¥0.120/秒)。
cast_enabled可选,默认 false开启角色分析与跨集统一克隆音色,加收 ¥0.010/秒。
subtitle_erase可选,默认关闭开启翻译前置去原硬字幕,单/多/全区域分别加收 ¥0.020 / ¥0.040 / ¥0.060/秒。
preserve_background_audio可选,默认 true保留原视频背景音乐与环境音效,不额外加价。
subtitle_enabled可选,默认 true是否将译文字幕烧录进成片画面;设为 false 时仍交付 SRT 字幕文件,但不可再传字幕样式或布局参数。
subtitle_mode可选,默认 translatedtranslated(仅目标语言)或 bilingual(双语各一行),需 subtitle_enabled=true。
subtitle_style可选字幕字体、颜色、描边、投影、底框与动效设置(不加价),详见字幕与字体样式设置。
subtitle_layout可选,默认 {80, 16}字幕纵向位置 { top_percent, height_percent },详见下方说明。
output_resolution可选,默认 sourcesource / 720p / 1080p,保留画面比例,不强行放大小分辨率素材。
metadata可选自定义 JSON 对象,序列化后最多 16 KiB,原样回显,不参与计费。

接口严格白名单校验:短剧接口强制使用高质量克隆且暂不开放姓名卡(画面)翻译与人工审改;传入 voice_strategy、voice_key、tts_enabled、video_text_translation、manual_review、glossary_review、lip_sync_enabled 等非开放字段均返回 400 invalid_request。

角色分析与跨集音色

短剧翻译默认已开启全剧共享术语(人物姓名、称号、专有名词)与全剧剧情上下文(均免费包含,全自动应用,无需审核)。

在此基础上,如果你希望同一角色在全剧不同集数里始终使用一致的克隆声纹和更精细的台词情绪划分,可开启 "cast_enabled": true:

  • 默认状态:false(关闭)。开启后按整剧总时长加收 ¥0.010/秒(折合 ¥0.60/分钟,享账户累计折扣)。
  • 跨集声纹聚合:全部分集语音识别完成后自动执行跨集角色归并,为每个角色构建独立的高质量克隆参考库,保证第 1 集到第 100 集同角色音色统一。
  • 结果回显:查询任务响应中的 cast 对象会返回识别出的角色总数及角色清单 characters[]。

去原硬字幕与选区

中文短剧成片通常带有烧录硬字幕。开启 subtitle_erase 后,系统会在渲染新字幕之前先擦除原视频字幕区域,避免中英双层字幕叠字。默认不开启(enabled: false)。

模式 mode加价(元 / 秒)折合(元 / 分钟)选区要求与适用场景
sel_area(单区域)+¥0.020+¥1.20传入 1 个矩形 { x1, y1, x2, y2 },面积 ≤ 原画面 50%。适合固定底部对白硬字幕(最常用、性价比最高)。
multi_area(多区域)+¥0.040+¥2.40传入 1–5 个矩形数组,单框面积 ≤ 原画面 50%。适合同时擦除底部字幕 + 顶部集数/角标/水印。
all_area(全区域)+¥0.060+¥3.60省略 rect 或传 null(不可传分集 rect)。适合字幕位置不固定或画面多处动态文字。

像素坐标与单集选区覆盖

坐标采用源视频绝对像素坐标,左上角 (x1, y1)、右下角 (x2, y2),须满足 0 ≤ x1 < x2 ≤ 视频宽、0 ≤ y1 < y2 ≤ 视频高。例如 1080×1920 竖屏短剧底部字幕区域通常位于 x: 60..1020, y: 1460..1740。

大多数短剧全集同分辨率、同字幕位,只需在顶层 subtitle_erase.rect 传一套选区即可;如果个别分集字幕位置或分辨率不同,可在 input.episodes[i].rect 为该集单独覆盖(须与顶层 mode 匹配:sel_area 传单对象,multi_area 传 1–5 项数组):

json(多区域擦除 + 单集覆盖示例)
{
  "input": {
    "episodes": [
      { "upload_id": "upl_ep01" },
      {
        "upload_id": "upl_ep02",
        "rect": [
          { "x1": 50, "y1": 1420, "x2": 1030, "y2": 1720 },
          { "x1": 760, "y1": 60, "x2": 1040, "y2": 150 }
        ]
      }
    ]
  },
  "subtitle_erase": {
    "enabled": true,
    "mode": "multi_area",
    "rect": [
      { "x1": 60, "y1": 1460, "x2": 1020, "y2": 1740 },
      { "x1": 780, "y1": 60, "x2": 1040, "y2": 140 }
    ]
  }
}

如果顶层省略 subtitle_erase.rect,则每一集 input.episodes[i].rect 都必须显式传入;任一集选区越界或单框面积超过该集画面 50% 时,任务会在校验阶段以 invalid_request 失败且不产生扣费。

字幕与字体样式设置

当 subtitle_enabled 为 true(默认)时,可通过 subtitle_style 和 subtitle_layout 精细控制译文字幕的字体、字重、字号缩放、颜色、描边、投影、背景底框、动效和画面纵向位置。自定义字幕样式完全免费,不额外加价。

1. subtitle_style 完整字段说明

字段类型 / 合法取值默认值作用说明
presetclassic | cinema | bold | shadow | box | brandclassic样式预设标识(见下方注意事项与 6 套完整预设 JSON)。
font_idnoto_sans | montserrat | roboto | open_sansnoto_sans字幕字体族(详见下方字体选型建议)。
primary_color#RRGGBB 六位十六进制#FFFFFF主字幕文字颜色(译文主色)。
secondary_color#RRGGBB#E4E4E4副字幕文字颜色(subtitle_mode=bilingual 双语模式下的次行文字)。
highlight_color#RRGGBB#FFE600高亮色(配合 animation: "highlight" 逐词高亮动效生效)。
outline_color#RRGGBB#000000文字描边颜色。
background_color#RRGGBB#000000字幕背景底框颜色(当 background_opacity > 0 时显示底框)。
background_opacitynumber,0 – 10底框不透明度:0 为无底框,0.6–0.8 为常见半透明黑底条,1 为不透明纯色底框。
font_weight400 | 600 | 700 | 800700字重:400 常规、600 半粗、700 粗体、800 特粗(渲染端 600 及以上启用粗体字形)。
font_scalenumber,0.5 – 1.51字号缩放倍率:1 为标准字号;竖屏短剧建议 0.95–1.15;系统仍自动保持单语最多两行、长句分页、不截断文本。
outline_widthnumber,0 – 83描边宽度(像素级权重):0 无描边,2–4 适合绝大多数短剧画面。
shadownumber,0 – 80投影偏移强度:0 无投影,2–4 为柔和投影。
animationnone | bounce | highlight | revealnone字幕动效:none 静态(短剧最稳妥)、bounce 弹跳入场、highlight 逐词高亮、reveal 渐显出现。

2. 字体 font_id 选型与多语种回退

font_id对应字体推荐场景与语种
noto_sansNoto Sans默认推荐:覆盖语种最广,拉丁、西里尔、中文、日文、韩文、泰语、阿拉伯语等均能稳定匹配。
montserratMontserrat欧美竖屏短剧爆款推荐:几何无衬线粗体(配合 font_weight: 800、outline_width: 4),适合英语、西语、葡语、法语。
robotoRoboto现代紧凑无衬线体,适合对白密集、句子较长的英/西/印尼语短剧。
open_sansOpen Sans字形开阔、高可读性,适合搭配半透明底框(box 风格)用于剧情/悬疑类短剧。

说明:当目标语言为中日韩、泰语、阿拉伯语等非拉丁字符时,渲染节点会自动匹配对应语种的系统 Noto 字体家族,不会出现方块乱码。

3. 六套可直接复制的短剧字幕预设 JSON

json(按需挑选其中一套放入请求的 subtitle_style 字段)
// 1. classic —— 经典白字黑描边(全品类通用)
{
  "preset": "classic", "font_id": "noto_sans",
  "primary_color": "#FFFFFF", "secondary_color": "#E4E4E4",
  "highlight_color": "#FFE600", "outline_color": "#000000",
  "background_color": "#000000", "background_opacity": 0,
  "font_weight": 700, "font_scale": 1, "outline_width": 3, "shadow": 0, "animation": "none"
}

// 2. cinema —— 电影感金黄字幕(古装 / 爽剧 / 悬疑)
{
  "preset": "cinema", "font_id": "noto_sans",
  "primary_color": "#FFD84D", "outline_color": "#000000",
  "background_opacity": 0, "font_weight": 600, "font_scale": 1, "outline_width": 2, "shadow": 0, "animation": "none"
}

// 3. bold —— 欧美短剧粗体强描边(ReelShort / DramaBox 风格)
{
  "preset": "bold", "font_id": "montserrat",
  "primary_color": "#FFFFFF", "outline_color": "#000000",
  "background_opacity": 0, "font_weight": 800, "font_scale": 1.05, "outline_width": 4, "shadow": 0, "animation": "none"
}

// 4. shadow —— 柔和投影(现代都市 / 甜宠)
{
  "preset": "shadow", "font_id": "roboto",
  "primary_color": "#FFFFFF", "outline_color": "#000000",
  "background_opacity": 0, "font_weight": 700, "font_scale": 1, "outline_width": 1, "shadow": 3, "animation": "none"
}

// 5. box —— 半透明深底框(画面色彩复杂 / 未去字幕遮挡兜底)
{
  "preset": "box", "font_id": "open_sans",
  "primary_color": "#FFFFFF", "outline_color": "#000000",
  "background_color": "#000000", "background_opacity": 0.7,
  "font_weight": 700, "font_scale": 1, "outline_width": 1, "shadow": 0, "animation": "none"
}

// 6. brand —— 逐词高亮动效(强节奏投流切片 / 漫剧)
{
  "preset": "brand", "font_id": "montserrat",
  "primary_color": "#FFFFFF", "highlight_color": "#FFE600", "outline_color": "#000000",
  "background_opacity": 0, "font_weight": 800, "font_scale": 1.05, "outline_width": 3, "shadow": 0, "animation": "highlight"
}

4. subtitle_layout 位置设置

subtitle_layout 控制字幕带在画面中的纵向安全区,包含两个百分比数值:

  • top_percent:字幕区上边缘距离视频顶部的百分比(0–99,默认 80)。
  • height_percent:字幕区纵向高度占视频总高的百分比(1–100,默认 16),且必须满足 top_percent + height_percent ≤ 100。
  • 9:16 竖屏短剧推荐:若已开启 subtitle_erase 擦除原底部硬字幕,建议设为 {"top_percent": 76, "height_percent": 16},与原字幕视觉落点自然重合,且高于短视频 App 底部交互栏;若未擦除原字幕,可将新字幕上移至 {"top_percent": 66, "height_percent": 14} 避开原字幕。

查询进度与按集下载

调用 GET /api/v1/jobs/{job_id} 查询整剧状态、总进度、各集状态与下载链接。GET /api/v1/jobs 列表接口同样支持分页查询,但为了响应速度,列表接口不包含分集签名下载链接,请使用详情接口获取最新链接。

json(GET /api/v1/jobs/{job_id} 返回示例)
{
  "id": "job_0123456789abcdef0123456789abcdef",
  "type": "drama_translation",
  "status": "succeeded",
  "source_language": "zh",
  "target_language": "en",
  "target_locale": "en-US",
  "advanced_quality": false,
  "cast_enabled": true,
  "shared_glossary_enabled": true,
  "subtitle_erase": {
    "enabled": true,
    "mode": "sel_area",
    "rect": { "x1": 60, "y1": 1460, "x2": 1020, "y2": 1740 }
  },
  "progress": 100,
  "episode_count": 5,
  "completed_episodes": 5,
  "retry_count": 0,
  "duration_ms": 302000,
  "billable_seconds": 302,
  "price_version": "jianhu.api.2026-11-22.drama.v1",
  "tier": "tier_100",
  "multiplier_bps": 10000,
  "currency": "CNY",
  "amounts": {
    "base_rate_per_second": "0.090000",
    "effective_rate_per_second": "0.090000",
    "reserved": "0.000000",
    "charged": "27.180000"
  },
  "episodes": [
    {
      "index": 0,
      "upload_id": "upl_ep01",
      "status": "succeeded",
      "progress": 100,
      "duration_ms": 60400,
      "error": null,
      "result": {
        "video": { "url": "https://...", "expires_at": "2026-11-22T19:30:00.000Z" },
        "source_subtitles": { "url": "https://...", "expires_at": "2026-11-22T19:30:00.000Z" },
        "translated_subtitles": { "url": "https://...", "expires_at": "2026-11-22T19:30:00.000Z" },
        "asr_original_subtitles": { "url": "https://...", "expires_at": "2026-11-22T19:30:00.000Z" }
      }
    }
  ],
  "glossary": {
    "status": "succeeded",
    "entry_count": 14,
    "entries": [
      { "source": "林婉", "target": "Lin Wan", "type": "person" }
    ]
  },
  "cast": {
    "enabled": true,
    "status": "succeeded",
    "character_count": 4,
    "characters": [
      { "id": "char_1", "name": "林婉" }
    ]
  },
  "error": null,
  "blocker": null,
  "metadata": { "drama_id": "drama_20261122_01" },
  "created_at": "2026-11-22T18:00:00.000Z",
  "updated_at": "2026-11-22T18:12:30.000Z",
  "terminal_at": "2026-11-22T18:12:30.000Z"
}

单集一旦完成(即使同任务其他集仍在处理中),即可在 episodes[i].result 中提前下载该集成片。每个签名链接最长有效 1 小时,且不超过任务终态后 7 天保留期;链接过期后在保留期内重新查询即可获取新链接。运行中可通过 POST /api/v1/jobs/{job_id}/cancel 申请取消:已交付分集按其累计时长结算,未交付部分立即释放冻结余额。

原任务内部分集重试

当一部几十集的短剧只有个别分集(或某个聚合节点)因网络波动、配音时长对齐异常等原因失败时,无需重建新任务——直接调用 POST /api/v1/jobs/{job_id}/retry 在原任务内重试失败部分:

bash(重试全部失败集 / 指定重试第 4、5 集)
# 方式 1:省略 episode_indexes,自动重试全部失败分集(或失败的术语/角色节点)
curl -X POST 'https://unmarkai.cn/api/v1/jobs/job_REPLACE/retry' \
  -H "Authorization: Bearer $UNMARKAI_API_KEY" \
  -H 'Idempotency-Key: retry-drama-001-attempt-1' \
  -H 'Content-Type: application/json' \
  -d '{}'

# 方式 2:仅重试指定 0-based 失败分集(例如第 4、5 集)
curl -X POST 'https://unmarkai.cn/api/v1/jobs/job_REPLACE/retry' \
  -H "Authorization: Bearer $UNMARKAI_API_KEY" \
  -H 'Idempotency-Key: retry-drama-001-ep34' \
  -H 'Content-Type: application/json' \
  -d '{"episode_indexes": [3, 4]}'
  • 保留已成功成果与一致性:已成功分集不重跑、不重复扣费;原剧已完成的共享术语、剧情上下文、角色声纹库完整复用,失败分集内已成功的前置步骤(如识别、去字幕、翻译)也会复用,直接从失败阶段恢复。
  • 总时长差额补冻结,原锁定单价不变:重试沿用任务首次冻结时锁定的单价,仅补冻结「(已交付集 + 本次重试集)总时长对应金额 − 已结算金额」的差额;无论重试多少次,全剧完结总扣费严格等于 max(15, ceil(全剧总时长/1000)) × 锁定单价,不会重复触发 15 秒起步价。
  • 可用范围与限制:支持处于 failed(或有分集已失败的 processing)且仍在 7 天保留期内的 drama_translation 任务,单任务最多重试 20 次;余额不足补冻结差额返回 402 insufficient_balance;因原片超 4K、超时长、去字幕选区越界、无有效语音等不可重试输入错误失败的节点返回 409 job_not_retryable;不允许对已成功分集免费重跑。

总时长计费与折扣

短剧翻译按全剧各集真实时长之和统一向上取整到整秒计费,整单最低计费 15 秒。基础价与开启的附加项单价相加后,再统一应用账户的近 365 天累计净充值折扣:ceil(总标准秒价微元 × multiplier_bps / 10000)。

计费项默认状态标准价(元 / 秒)折合(元 / 分钟)
短剧普通翻译(含高质量克隆 + 共享术语 + 剧情上下文 + 背景音 + 字幕样式)默认¥0.060¥3.60
短剧高级翻译(advanced_quality: true)可选¥0.120¥7.20
角色分析与跨集统一音色(cast_enabled: true)关闭+¥0.010+¥0.60
去字幕 · 单区域(sel_area)关闭+¥0.020+¥1.20
去字幕 · 多区域(multi_area)关闭+¥0.040+¥2.40
去字幕 · 全区域(all_area)关闭+¥0.060+¥3.60

算例(5 集短剧,每集 90 秒,总时长 450 秒 = 7.5 分钟):

  • 普通翻译(仅默认项):¥0.060 × 450 = ¥27.00(8 折 ¥21.60)
  • 普通翻译 + 角色分析 + 单区域去字幕:¥0.090 × 450 = ¥40.50(8 折 ¥32.40)
  • 普通翻译 + 角色分析 + 多区域去字幕:¥0.110 × 450 = ¥49.50(8 折 ¥39.60)
  • 普通翻译 + 角色分析 + 全区域去字幕:¥0.130 × 450 = ¥58.50(8 折 ¥46.80)
近 365 天累计净充值折扣系数
¥0 起标准价
¥1,0009 折
¥5,0008 折
¥10,0007.5 折
¥25,0007 折
¥50,0006.5 折
¥100,0006 折

调用 GET /api/v1/balance 可通过 amounts.drama_translation_rates 读取当前账户的实时折后单价(币种固定 currency: "CNY")。

Python 与 Node.js 示例

以下完整示例演示将本地 5 集短剧(ep01.mp4 – ep05.mp4)批量直传、创建带角色分析 + 单区域去字幕 + 自定义字体样式的短剧任务,并轮询至全部交付后逐集下载。

Python 3(标准库,可直接运行)
import json, os, time, urllib.request, uuid
from pathlib import Path

API_KEY = os.environ["UNMARKAI_API_KEY"]
BASE = "https://unmarkai.cn/api/v1"

def api_req(method, path, body=None, idempotency_key=None):
    headers = {"Authorization": f"Bearer {API_KEY}"}
    data = None
    if body is not None:
        headers["Content-Type"] = "application/json"
        data = json.dumps(body).encode("utf-8")
    if idempotency_key:
        headers["Idempotency-Key"] = idempotency_key
    req = urllib.request.Request(BASE + path, data=data, method=method, headers=headers)
    with urllib.request.urlopen(req, timeout=60) as resp:
        return json.load(resp)

# 1. 按集序批量上传 5 集
episode_files = [Path(f"ep0{i}.mp4") for i in range(1, 6)]
episodes = []
for f in episode_files:
    ticket = api_req("POST", "/uploads", {
        "filename": f.name,
        "content_type": "video/mp4",
        "file_size_bytes": f.stat().st_size,
    })
    put_req = urllib.request.Request(
        ticket["url"], data=f.read_bytes(), method="PUT", headers=ticket["headers"]
    )
    with urllib.request.urlopen(put_req, timeout=300):
        pass
    episodes.append({"upload_id": ticket["upload_id"]})

# 2. 创建短剧翻译任务(开启角色分析 + 单区域去字幕 + 欧美粗体字幕样式)
job = api_req("POST", "/jobs", {
    "type": "drama_translation",
    "input": {"episodes": episodes},
    "source_language": "zh",
    "target_language": "en",
    "target_locale": "en-US",
    "advanced_quality": False,
    "cast_enabled": True,
    "subtitle_erase": {
        "enabled": True,
        "mode": "sel_area",
        "rect": {"x1": 60, "y1": 1460, "x2": 1020, "y2": 1740},
    },
    "subtitle_style": {
        "preset": "bold",
        "font_id": "montserrat",
        "primary_color": "#FFFFFF",
        "outline_color": "#000000",
        "font_weight": 800,
        "font_scale": 1.05,
        "outline_width": 4,
        "shadow": 0,
        "background_opacity": 0,
        "animation": "none",
    },
    "subtitle_layout": {"top_percent": 76, "height_percent": 16},
}, idempotency_key=f"drama-{uuid.uuid4()}")
job_id = job["id"]

# 3. 轮询进度(如有偶发失败分集可调用 POST /jobs/{job_id}/retry)
while True:
    cur = api_req("GET", f"/jobs/{job_id}")
    print(cur["status"], f"{cur['progress']}%", f"{cur['completed_episodes']}/{cur['episode_count']}")
    if cur["status"] in ("succeeded", "failed", "canceled"):
        break
    time.sleep(10)

# 4. 逐集下载成片与译文字幕
out_dir = Path("drama_output")
out_dir.mkdir(exist_ok=True)
for ep in cur["episodes"]:
    if ep["status"] == "succeeded" and ep["result"] and ep["result"].get("video"):
        urllib.request.urlretrieve(ep["result"]["video"]["url"], out_dir / f"ep{ep['index']+1:02d}_en.mp4")
        if ep["result"].get("translated_subtitles"):
            urllib.request.urlretrieve(ep["result"]["translated_subtitles"]["url"], out_dir / f"ep{ep['index']+1:02d}_en.srt")
JavaScript / Node.js 20+
import { readFile, stat, writeFile, mkdir } from 'node:fs/promises';
import { randomUUID } from 'node:crypto';

const API_KEY = process.env.UNMARKAI_API_KEY;
const BASE = 'https://unmarkai.cn/api/v1';

async function api(method, path, body, idempotencyKey) {
  const res = await fetch(BASE + path, {
    method,
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}),
      ...(idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : {}),
    },
    body: body !== undefined ? JSON.stringify(body) : undefined,
  });
  const json = await res.json();
  if (!res.ok) throw new Error(JSON.stringify(json.error));
  return json;
}

const files = ['ep01.mp4', 'ep02.mp4', 'ep03.mp4', 'ep04.mp4', 'ep05.mp4'];
const episodes = [];
for (const file of files) {
  const info = await stat(file);
  const ticket = await api('POST', '/uploads', {
    filename: file, content_type: 'video/mp4', file_size_bytes: info.size,
  });
  const put = await fetch(ticket.url, { method: 'PUT', headers: ticket.headers, body: await readFile(file) });
  if (!put.ok) throw new Error(`Upload failed: ${put.status}`);
  episodes.push({ upload_id: ticket.upload_id });
}

const job = await api('POST', '/jobs', {
  type: 'drama_translation',
  input: { episodes },
  source_language: 'zh',
  target_language: 'en',
  target_locale: 'en-US',
  cast_enabled: true,
  subtitle_erase: { enabled: true, mode: 'sel_area', rect: { x1: 60, y1: 1460, x2: 1020, y2: 1740 } },
  subtitle_style: {
    preset: 'cinema', font_id: 'noto_sans', primary_color: '#FFD84D',
    outline_color: '#000000', font_weight: 600, font_scale: 1, outline_width: 2,
    shadow: 0, background_opacity: 0, animation: 'none',
  },
  subtitle_layout: { top_percent: 76, height_percent: 16 },
}, `drama-${randomUUID()}`);

console.log('Created job:', job.id);

事件回调与验签

在 API 控制台配置公网 HTTPS 回调地址并完成 challenge 验证后,短剧任务状态变更(job.created、job.queued、job.processing、job.succeeded、job.failed、job.canceled)会自动推送签名事件。签名规则为 v1=HMAC_SHA256(secret, timestamp + "." + raw_body),详见通用 Webhook 验签代码。回调正文不含视频签名链接,收到事件后请调用 GET /api/v1/jobs/{job_id} 获取分集下载链接。

短剧专用 OpenAPI 契约

下载面向短剧业务的精简 OpenAPI 3.1 规范(仅包含批量上传、短剧翻译任务、部分集重试、余额查询与回调,不含非短剧接口),可直接导入 Postman、Apifox 或用于代码生成。