跳到主要内容
剪狐API 文档
JIANHU / DEVELOPER DOCUMENTATION

API 文档

让视频处理成为你产品的一部分。
从第一次请求,到自动化的视频工作流。

REST · MCP中文接入指南更新于 2026-11-22
文档目录

快速入门

通过一套异步接口完成视频文字擦除、翻译与配音。先在 API 控制台创建密钥,并为 API 钱包充值,再按下面的流程提交第一个任务。

  1. 上传视频

    先创建上传请求,将本地视频上传至返回的地址;也可使用文档支持的 HTTPS 直链导入方式。

  2. 创建任务

    使用上传得到的文件标识创建擦除或翻译任务,按接口要求填写处理参数,并为新业务请求生成幂等键。

  3. 查询进度

    保存返回的任务标识,查询任务状态;如遇失败,先检查错误信息再决定是否重试。

  4. 下载结果

    任务成功后获取并下载处理结果;检查视频内容,及时保存需要保留的文件。

以下 cURL 示例需要 bash、curl、jq 和本地 source.mp4。将占位密钥替换为服务端环境变量中的真实值,不要放到网页代码里。创建任务的幂等键需为每个新业务请求生成一次,重试时复用。

bash
set -euo pipefail
export UNMARKAI_API_KEY='uma_live_REPLACE_WITH_YOUR_KEY'
BASE='https://unmarkai.cn/api/v1'
FILE='source.mp4'
SIZE=$(wc -c < "$FILE" | tr -d ' ')
# 1. 申请直传凭证
curl --fail-with-body -sS "$BASE/uploads" \
  -H "Authorization: Bearer $UNMARKAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d "$(jq -n --argjson size "$SIZE" \
    '{filename:"source.mp4",content_type:"video/mp4",file_size_bytes:$size}')" \
  -o upload.json
# 2. 原样携带全部上传头,完整上传视频字节
UPLOAD_HEADERS=()
while IFS= read -r header; do UPLOAD_HEADERS+=(-H "$header"); done \
  < <(jq -r '.headers | to_entries[] | "\(.key): \(.value)"' upload.json)
curl --fail-with-body -sS -X PUT "$(jq -r .url upload.json)" \
  "${UPLOAD_HEADERS[@]}" --data-binary "@$FILE"
# 3. 上传完成后创建全画面擦除任务
# 新任务请换一个唯一值;失败重试同一请求时保留此值
REQUEST_KEY='replace-with-a-unique-business-request-id'
curl --fail-with-body -sS "$BASE/jobs" \
  -H "Authorization: Bearer $UNMARKAI_API_KEY" \
  -H "Idempotency-Key: $REQUEST_KEY" \
  -H 'Content-Type: application/json' \
  -d "$(jq -n --arg id "$(jq -r .upload_id upload.json)" \
    '{type:"remove_text",input:{upload_id:$id},mode:"all_area"}')" \
  -o job.json
# 4. 每隔数秒查询,最多等待 30 分钟
JOB_ID=$(jq -r .id job.json)
for ((i=0; i<360; i++)); do
  curl --fail-with-body -sS "$BASE/jobs/$JOB_ID" \
    -H "Authorization: Bearer $UNMARKAI_API_KEY" -o result.json || break
  STATUS=$(jq -r .status result.json)
  case "$STATUS" in
    succeeded)
      curl --fail-with-body -sS "$(jq -r .result.url result.json)" -o output.mp4
      break ;;
    failed|canceled) jq '{status,error}' result.json; break ;;
  esac
  sleep 5
done
# 超时后保留 JOB_ID,后续继续查询;不要重复创建任务。

地址与鉴权

REST Base URL:https://unmarkai.cn/api/v1
MCP Endpoint:https://unmarkai.cn/api/mcp

所有 REST 请求使用 Authorization: Bearer uma_live_*。控制台手机号登录会话仅用于管理账户,不可替代 API 密钥。不同地区的 API 密钥及钱包独立。

bash
curl 'https://unmarkai.cn/api/v1/balance' \
  -H "Authorization: Bearer $UNMARKAI_API_KEY"
请求头用途
Authorization必填,Bearer API 密钥。
Content-TypeJSON 请求使用 application/json;视频直传使用凭证返回的头。
Idempotency-Key创建任务及直链导入必填,1–255 字符,详见幂等章节。
X-Request-Id可选,便于请求追踪;响应也返回 X-Request-Id。

创建与取消需要 jobs:write,查询需要 jobs:read,余额需要 balance:read。撤销或过期的密钥无法继续调用。账号默认两个任务执行并发,多把密钥共享账户额度。

上传与直链导入

方法 / 路径请求参数返回
POST /uploadsfilename:文件名;content_type:视频 MIME;file_size_bytes:实际字节数。201,upload_id、method=PUT、url、headers、expires_at。
POST /url-uploadssource_url:可直接下载的公网 HTTPS 视频地址;filename 可选。需 Idempotency-Key。202;幂等重放 200,返回上传资源。
GET /uploads/{upload_id}路径中传入上传 ID。200,upload_id、source_type、status、filename、content_type、file_size_bytes、error。

支持 MP4、MOV、AVI、MKV、WebM、MPEG,对应 MIME 为 video/mp4、video/quicktime、video/x-msvideo、video/x-matroska、video/webm、video/mpeg。最大 2 GiB、60 分钟,仍需服务端媒体核验。

直传凭证有效 1 小时,必须原样携带所有 headers,包括类型、长度及 if-none-match: *;视频数据直接 PUT 到凭证地址,不经过业务 API。凭证不可覆盖写入;重复 PUT 返回 409/412 时先核查上传状态,不要盲目覆盖。未绑定任务的上传记录有效 24 小时。

最多同时保留 100 个有效未绑定上传,滚动 24 小时未消费上传总量最多 20 GiB。申请上传前需具备至少一次最低计费余额。

bash
curl 'https://unmarkai.cn/api/v1/url-uploads' \
  -H "Authorization: Bearer $UNMARKAI_API_KEY" \
  -H 'Idempotency-Key: replace-with-unique-import-id' \
  -H 'Content-Type: application/json' \
  -d '{"source_url":"https://cdn.example.com/source.mp4","filename":"source.mp4"}'

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

直链导入异步执行;等待 status=uploaded 后再创建任务。状态包括 pending、importing、uploaded、failed、expired。直链必须返回稳定的 Content-Length 和受支持的视频 MIME,可包含签名查询参数;不支持网页或平台分享页,也不允许内网地址及 HTTPS 降级。

擦除任务

POST /jobs,提交成功返回 202 与任务资源。任务先核验素材、时长和选区,再冻结足额余额,随后进入队列。

字段说明
type必填,remove_text。
input.upload_id必填,已完整上传的素材 ID。
mode必填,all_area / sel_area / multi_area。
rectall_area 省略或 null;sel_area 为一个矩形;multi_area 为非空矩形数组。
metadata可选,自定义 JSON 对象,序列化后最多 16 KiB。
json
{
  "type": "remove_text",
  "input": {"upload_id": "upl_REPLACE"},
  "mode": "sel_area",
  "rect": {"x1": 100, "y1": 80, "x2": 900, "y2": 220},
  "metadata": {"external_order_id": "your-order-id"}
}

选区为源视频绝对像素坐标,左上角 (x1,y1)、右下角 (x2,y2),必须在画面内且宽高大于零。单框面积不得超过源画面的一半;多框按全画面费率计算。示例坐标需按自己的视频尺寸调整。

翻译与配音

同样调用 POST /jobs,设置 type=video_translation。每个任务对应一种目标语言。任务提交后自动处理,配音与字幕时间轴自动对齐。

json
{
  "type": "video_translation",
  "input": {"upload_id": "upl_REPLACE"},
  "target_language": "en",
  "target_locale": "en-US",
  "source_language": "auto",
  "advanced_quality": false,
  "tts_enabled": true,
  "subtitle_enabled": true,
  "subtitle_mode": "translated",
  "output_resolution": "source"
}
字段默认值 / 用途
target_language必填,目标语言规范码,如 en、ja、es、zh。
source_languageauto,自动识别源语言。
target_locale可选,单目标语言地区,如 en-US;需匹配 target_language。
advanced_qualityfalse;true 使用高级翻译价格。
tts_enabledtrue;false 保留原音轨,仍生成翻译字幕。
subtitle_enabledtrue,烧录字幕;与 tts_enabled 同为 false 时仅交付字幕,result.video 为 null。
voice_strategyclone / sim;默认 clone,克隆原声;sim 自动选择相似音色。
voice_key从 GET /voices 选择的预设音色;使用时不能与 sim 组合。
preserve_background_audio配音时默认 true,不配音时默认 false;配音相关配置需开启 TTS。
reference_text可选,最多 50,000 字符,用于校正源语言识别,不是翻译指令。
subtitle_modetranslated / bilingual,需开启 subtitle_enabled。
subtitle_style可选字幕样式对象;颜色、字号、描边等完整字段见 OpenAPI。
subtitle_layout可选 {top_percent,height_percent},默认 {80,16};高度 8–24,顶部非负,二者合计 ≤100。
output_resolutionsource / 720p / 1080p,默认 source;保留比例,不强行放大小分辨率素材。
metadata自定义对象,序列化后最多 16 KiB。

翻译创建请求最大 512 KiB;其他 JSON 请求通常最多 64 KiB。新翻译不自动擦除原视频字幕。默认克隆普通翻译 ¥0.060/秒、高级翻译 ¥0.120/秒;相似音色、预设音色或关闭配音为 ¥0.040/秒、¥0.080/秒。字幕样式和背景音不额外加价。

查询可用音色

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

使用返回的音色目录选择有效 voice_key;不要自行拼造音色标识。

短剧批量翻译

阅读短剧翻译专用 API 文档(含字体样式与部分集重试指南) ↗ · 下载短剧专用 OpenAPI ↓

面向 1–100 集短剧/漫剧批量出海,调用 POST /api/v1/jobs 并传入 type: "drama_translation" 与按集序排列的 input.episodes。默认强制高质量原声克隆(不开放相似/固定音色,无需传音色参数)、默认开启全剧共享术语与剧情上下文,暂不开放姓名卡(画面文字)翻译。支持可选角色分析(cast_enabled,+¥0.010/秒)、三档去原硬字幕(subtitle_erase,单/多/全区域 +¥0.020 / ¥0.040 / ¥0.060/秒,支持整剧像素选区及单集覆盖)、完整 subtitle_style 字体样式与 subtitle_layout 布局配置(免费),以及原任务内部分集重试(POST /api/v1/jobs/{job_id}/retry)。计费按全剧各集总时长向上取整到整秒,整单最低 15 秒,基础价普通 ¥0.060/秒、高级 ¥0.120/秒,再享账户累计净充值折扣。

json(短剧翻译创建示意)
{
  "type": "drama_translation",
  "input": { "episodes": [{ "upload_id": "upl_ep01" }, { "upload_id": "upl_ep02" }] },
  "source_language": "zh",
  "target_language": "en",
  "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, "outline_width": 4 }
}

视频高清

高清 API 概览、标准价与真实效果 ↗ · 网页视频高清 ↗

中国区通过 POST /api/v1/jobs 创建高清任务,沿用 API Key、上传、查询和 Webhook。单视频支持 1080p、2K、4K,保留比例、帧率和音轨。

{
  "type": "video_upscale",
  "input": {"upload_id": "upl_your_upload"},
  "upscale": {"target": "4k"},
  "metadata": {"order_id": "your_order"}
}

请求头包含 Authorization: Bearer YOUR_API_KEY 和 Idempotency-Key。target 为 1080p、2k 或 4k。输入长短边不能超过目标档位(1920×1080、2560×1440、3840×2160),支持同分辨率增强和竖屏。服务端探测帧率,不接受客户端指定 FPS 或倍率。最多 60 分钟、2 GB;多声道音频建议先转成立体声。

标准价分别为 ¥0.032、¥0.048、¥0.080/秒。平均帧率大于 30 FPS 单价翻倍,再应用账户充值折扣;29.97 不翻倍,59.94 翻倍。计费秒数为 max(15, ceil(实际秒数)),不采用网页的 30 秒档位或 1 秒缓冲。例如 30 秒 4K / 60 FPS 为 ¥7.20,八折 ¥5.76。

余额接口的 amounts.upscale_rates 返回不超过 30 FPS 的账户折后秒价。任务返回 upscale.target、upscale.fps 和 upscale.multiplier,金额读取 currency=CNY 与 amounts。成功后从 result.url 下载;冻结、结算、失败释放、链接有效期及排队取消规则沿用擦除任务。高清目前通过 REST 提交。

查询、取消与下载

接口行为
GET /jobs/{job_id}查询状态、进度、费用、error 与 result。
GET /jobs?limit=20列表默认每页 20 条,limit 为 1–100;支持 status 过滤及 after 游标。
POST /jobs/{job_id}/cancel取消任务;已进入不可取消阶段会拒绝,按响应处理。

列表按创建时间和 ID 倒序,下一页把 next_cursor 原样传给 after。不要将游标当页码或自行解析。任务状态包括 validating、queued、processing、succeeded、failed、canceled。

余额不足时任务可能保留核验结果等待补足;翻译任务通过 blocker.code=insufficient_balance 和 blocker.expires_at 提示。等待余额最多 72 小时,到期失败。付款到账后服务端恢复等待任务,客户端继续查询原任务。

擦除在验证或排队阶段可取消;翻译运行中也可申请取消。以服务端返回为准;已交付部分不重复退款或扣款。客户端等待超时不等于任务失败,不要因此重复提交。

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

curl -X POST 'https://unmarkai.cn/api/v1/jobs/job_REPLACE/cancel' \
  -H "Authorization: Bearer $UNMARKAI_API_KEY" \
  -H 'Content-Type: application/json' -d '{}'

下载结果

擦除成功后下载 result.url;翻译结果位于 result.video、source_subtitles、translated_subtitles 等资源中,各资源包含 url、expires_at。先判断资源是否存在、是否为 null,再下载。API 按完整时长处理。有实付充值或后台额度发放记录的 API 钱包可交付免剪狐水印的成片,账户当前规则可通过 GET /balance 的 watermark_required 查看。

下载链接最长有效 1 小时,且不超过任务终态后的 7 天保留期。链接过期后在保留期内重新查询任务获取新链接;请及时保存结果。Webhook 不包含视频签名链接,收到事件后查询任务。

余额、计费与折扣

调用 GET /balance 获取账户余额、实时价格和档位。通用金额使用 currency 与 amounts;本站币种为 CNY,金额以六位小数字符串表示,禁止将人民币标记为 USD。

json(部分字段示意)
{
  "currency": "CNY",
  "amounts": {
    "available": "200.000000",
    "reserved": "0.000000"
  }
}
功能标准元 / 秒标准元 / 分钟
单框擦除 sel_area0.0201.20
多框 / 全画面擦除0.0402.40
普通翻译(默认克隆)0.0603.60
高级翻译(默认克隆)0.1207.20
普通翻译(sim / 预设音色 / 关闭配音)0.0402.40
高级翻译(sim / 预设音色 / 关闭配音)0.0804.80
短剧普通翻译(默认克隆 + 共享术语)0.0603.60
短剧高级翻译(默认克隆 + 共享术语)0.1207.20
短剧附加:角色分析与跨集统一音色0.0100.60
短剧附加:去字幕单区域(sel_area)0.0201.20
短剧附加:去字幕多区域(multi_area)0.0402.40
短剧附加:去字幕全区域(all_area)0.0603.60
视频高清 1080p(不超过 30 FPS)0.0321.92
视频高清 2K(不超过 30 FPS)0.0482.88
视频高清 4K(不超过 30 FPS)0.0804.80

每视频按秒向上取整,最低计费 15 秒。核验真实时长并冻结足额费用后开始处理;成功交付结算,未交付失败或允许的取消释放费用。例如标准价全画面擦除 10 秒,按 15 秒计 ¥0.60;默认克隆普通翻译 61 秒计 ¥3.66。

微信单次充值 ¥200–10,000,最多两位小数,1 元实付到账 1 元。200 元是最低充值金额,不是单任务起步价。API 钱包独立于网页积分、会员和试用;充值是否开放以控制台状态为准。

近 365 天累计净充值价格折扣
¥0 起标准价
¥1,0009 折
¥5,0008 折
¥10,0007.5 折
¥25,0007 折
¥50,0006.5 折
¥100,0006 折

仅成功支付的净额计入资格,已确认退款从资格中扣除。冻结成功时锁定任务价格;之后充值或资格到期不改变已冻结任务。资格到期不清空余额。上述为当前标准价,实际费用以接口的价格与任务金额为准。

幂等与重试

创建任务和直链导入使用 Idempotency-Key,在 API 账号内有效 24 小时。相同键与相同规范化请求重放同一资源,响应带 Idempotent-Replayed: true;不同请求体复用同一键会冲突。

  • 为每个业务操作生成并保存唯一幂等键;网络断开或响应丢失时,使用原键和原请求体重试。
  • 不要在重试时自动生成新键,否则可能创建多个计费任务。
  • 401/403 先修正鉴权,400/422 先修正参数,402 先处理余额;不要无条件重试。
  • 429 和临时 5xx 使用有上限的指数退避与随机抖动;如响应提供 Retry-After,遵循该值。
  • 优先使用回调。轮询时设置间隔和截止时间,达到截止时间后保留任务 ID 供稍后查询。

错误处理

json(结构示意)
{
  "error": {
    "code": "invalid_request",
    "message": "Request validation failed",
    "request_id": "request-id-from-server"
  }
}
HTTP处理建议
400请求参数不合法;检查字段、选区与语言配置。
401 / 403检查密钥、有效期与所需 scope。
402检查 API 钱包余额与最低计费要求。
404检查资源 ID、所属账户及保留期。
409检查幂等冲突或当前任务状态,不盲目创建新任务。
413 / 415请求体过大或不支持的媒体类型。
422媒体或业务校验失败,查看错误详情。
429请求过于频繁,退避后重试。
500 / 502 / 503临时服务异常;503 service_unavailable 也可能表示服务尚未开放。

使用 error.code 处理业务分支,记录 error.request_id 或 X-Request-Id 便于排查。不要记录 Authorization、完整 API 密钥或素材签名链接。异步失败则读取任务的 error.code / error.message。

事件回调与验签

在控制台配置公网 HTTPS 接收地址,保存一次性显示的签名密钥后,点击「验证接收地址」。验证事件 endpoint.verification 的 data.challenge 需用纯文本或 {"challenge":"原值"} 回显,并返回 2xx。

请求头包含 UnmarkAI-Id、UnmarkAI-Timestamp、UnmarkAI-Signature。签名为 v1= 加 HMAC-SHA256 的小写十六进制结果;原文是时间戳、英文句点和原始请求体字节。先验签,再解析 JSON,按事件 ID 持久化去重。

JavaScript / Node.js
import { createHmac, timingSafeEqual } from 'node:crypto';

// 在你的 HTTP 接收器中调用;rawBody 必须是未重新序列化的 Buffer。
function verifyWebhook(rawBody, headers, secret) {
  const timestamp = headers['unmarkai-timestamp'];
  const signature = headers['unmarkai-signature'];
  if (typeof timestamp !== 'string' || !/^\d+$/.test(timestamp)) return false;
  if (typeof signature !== 'string' || !/^v1=[a-f0-9]{64}$/.test(signature)) return false;
  // 接收端策略:拒绝超过 5 分钟的请求,服务器需保持时钟同步。
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = createHmac('sha256', secret)
    .update(timestamp + '.').update(rawBody).digest();
  const received = Buffer.from(signature.slice(3), 'hex');
  return received.length === expected.length && timingSafeEqual(expected, received);
}
// 验签成功后:JSON.parse(rawBody.toString('utf8'))。
// endpoint.verification → 返回 {challenge: event.data.challenge}。
// 其他事件 → 原子记录事件 ID / 入队,然后返回 2xx。

任务事件包含 type、id、created_at 和 data.job_id / status / progress,完整事件类型见 OpenAPI。事件不包含下载链接。接收后调用 GET /jobs/{job_id} 获取最新状态及结果,避免依赖事件到达顺序。

任意 2xx 表示成功。非 2xx、网络错误、重定向及超时最多共投递 6 次,重试间隔依次为 1 分钟、5 分钟、30 分钟、2 小时、12 小时,单次超时 10 秒。建议先可靠入队再返回,耗时工作异步处理。

每次保存地址都会更换签名密钥、重置验证状态,并停止旧事件自动重试;请同步更新接收端配置并重新验证。控制台可查看记录和手动重投。

Python 与 JavaScript 示例

下面示例从已有 upload_id 创建擦除任务;上传完整流程见快速入门。通过环境变量传入服务端密钥、已完成上传的 ID 和持久化的业务幂等键。示例不自动重试,失败时保留原键,按照错误章节决定是否重试。

Python
# Python 3,使用标准库
import json, os, urllib.request, urllib.error

body = json.dumps({
    "type": "remove_text",
    "input": {"upload_id": os.environ["UNMARKAI_UPLOAD_ID"]},
    "mode": "all_area"
}).encode("utf-8")
request = urllib.request.Request(
    "https://unmarkai.cn/api/v1/jobs", data=body, method="POST",
    headers={
        "Authorization": "Bearer " + os.environ["UNMARKAI_API_KEY"],
        "Idempotency-Key": os.environ["UNMARKAI_REQUEST_KEY"],
        "Content-Type": "application/json"
    }
)
try:
    with urllib.request.urlopen(request, timeout=30) as response:
        job = json.load(response)
        print(job["id"], job["status"])  # 保存 ID,后续查询或接收回调
except urllib.error.HTTPError as error:
    print(error.code, error.read().decode("utf-8"))
    raise
JavaScript / Node.js
// Node.js 20+,服务端运行
const response = await fetch('https://unmarkai.cn/api/v1/jobs', {
  method: 'POST',
  signal: AbortSignal.timeout(30_000),
  headers: {
    Authorization: `Bearer ${process.env.UNMARKAI_API_KEY}`,
    'Idempotency-Key': process.env.UNMARKAI_REQUEST_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    type: 'remove_text',
    input: { upload_id: process.env.UNMARKAI_UPLOAD_ID },
    mode: 'all_area'
  })
});
const body = await response.json();
if (!response.ok) throw new Error(JSON.stringify(body.error));
console.log(body.id, body.status); // 保存 ID,后续查询或接收回调

MCP 接入

在支持远程 HTTP MCP 的客户端中配置服务地址 https://unmarkai.cn/api/mcp 和 Bearer API 密钥。不同客户端的配置字段可能不同,以下为连接信息示意:

json(连接信息示意)
{
  "url": "https://unmarkai.cn/api/mcp",
  "headers": {"Authorization": "Bearer uma_live_REPLACE_WITH_YOUR_KEY"}
}
工具用途
create_upload获取本地文件直传凭证;实际 PUT 需由调用方执行。
create_url_upload从 HTTPS 视频直链异步导入。
get_upload查询上传状态,可设置 wait_seconds 为 0–60。
remove_text创建擦除任务;上传完成后调用。
get_job查询任务,可设置 wait_seconds 为 0–60。
list_jobs按状态和游标查询任务列表。
cancel_job申请取消任务。
get_balance读取余额与价格。
estimate_cost估算费用,最终以实际时长和任务账单为准。

MCP 当前覆盖擦除工作流,翻译通过 REST 提供。MCP 的估价同样读取 currency 与 amounts,不把人民币当作美元。

完整接口契约

下载统一 OpenAPI 契约查看全部字段、嵌套字幕样式、响应类型、事件及错误枚举。选择 server https://unmarkai.cn/api 后,契约中的路径自带 /v1,不要重复拼接。

本站金额以 CNY 和 amounts 为准。