页面加载中
开发者接入指南

开放 API 接入前需要了解什么

接口请求前缀为 https://www.550wai.cn。先准备账户极速积分并在 API-KEY 管理页生成主密钥或子密钥,再按所需能力调用接口。完整密钥仅在生成或重置成功时显示一次。

所有接口使用 HTTP POST。普通参数使用 application/x-www-form-urlencoded,文件上传使用 multipart/form-data;请求 body 携带 userNo 与 apiKey。不要把真实密钥写入公开示例。

异步任务先提交并保留响应中的 taskId,再通过任务详情查询状态和结果;也可按对应接口文档配置 Webhook。任务已受理但响应不明时,先核查已有任务,避免重复提交。

视频去字幕、分享链接去水印与图片去水印使用极速积分,费用规则随能力不同。下方完整文档提供参数表、状态说明和 cURL、Python、JavaScript、Java 示例。

常见问题

主 API-KEY 与子 API-KEY 有什么区别?

主密钥具有账号下全部 Open API 任务的查询和操作权限。子密钥可配置额度与有效期,任务查询、查看和删除范围限于自己提交的任务。两者均可调用公开处理能力,具体限制见下方完整文档。

查询接口应该使用什么请求方式?

现有 Open API 查询接口同样使用 HTTP POST,在请求 body 中携带 userNo、apiKey 和对应参数。不要因为接口名称包含 query 就改为 GET。

任务提交后如何拿到结果?

异步任务响应中的 taskId 用于关联后续查询。等待成功终态后按响应读取结果;失败、处理中或响应不明不能当作成功,也不应盲目重新提交。

页面里会直接显示我的完整密钥吗?

本页的公开说明和静态 HTML 不包含账户密钥。完整主密钥或子密钥仅在已登录的管理流程生成或重置成功时显示一次,列表使用脱敏值。

能力概要

三项媒体处理能力均通过统一的 userNo + apiKey 鉴权,可独立接入,也可组合成自动化工作流。

01异步任务

视频去字幕

提交视频地址,智能擦除硬字幕、文字与画面水印;支持静音预处理和任务结果查询。

输入
视频 URL 与基础参数
计费
按时长与分辨率
查看去字幕接入文档
02同步返回

视频去水印

提交短视频分享链接,解析并返回可用的视频、封面及文案信息,适合内容采集工作流。

输入
短视频分享链接
计费
成功 1 积分
查看视频去水印文档
03同步 / 异步

图片去水印

上传单张图片,智能清理图片水印、文字与 Logo 并修复背景,可按需要同步等待或异步查询。

输入
图片文件
计费
成功 10 积分
查看图片去水印文档
统一鉴权所有接口均使用 userNo + apiKey;主 API-KEY 拥有账号全量权限,子 API-KEY 仅能访问自己提交的任务。查看快速开始

目录

使用步骤

  1. 1
    充值极速积分
    购买积分套餐。不同能力采用按任务或按处理量计费,具体规则见「积分与计费」。
  2. 2
    获取 API-KEY
    在 API-KEY 管理页生成主 API-KEY,或按成员和业务创建独立子 API-KEY。完整 API-KEY 仅在生成成功时展示一次。
  3. 3
    参考文档对接接口
    根据能力选择同步调用或任务模式,并按接口响应获取处理结果。

Base URL

所有接口请求前缀:

https://www.550wai.cn

通用约定

请求方式

所有接口统一使用 HTTP POST。普通参数接口使用 application/x-www-form-urlencoded;文件上传接口使用 multipart/form-data。

鉴权参数

所有接口在请求 body 中必须携带:

  • userNo:用户编号(主账号)
  • apiKey:主 API-KEY沿用 sk-550w-... 格式;子 API-KEY使用版本化的 sk-550w-sub-v1_... 格式

主 API-KEY与子 API-KEY

  • 主 API-KEY:兼容原有调用协议,拥有账号下全部 Open API任务的查询和操作权限;重置后旧主 API-KEY立即失效。
  • 子 API-KEY:每个账号最多保留 100 个未删除子 API-KEY,未删除的子 API-KEY 名称不可重复,删除后可重新使用该名称;只能查询、查看和删除自己提交的任务,但可调用本文全部三类处理能力。
  • 额度:子 API-KEY 可配置每日及累计积分上限;留空表示不限制。达到限额后拒绝新的消费请求;已受理异步任务的实际补扣允许本次超额完成,退款会恢复相应额度。
  • 有效期与状态:子 API-KEY到期、禁用或删除后不能鉴权。过期时间可修改或取消;删除不可恢复,历史任务和统计归属仍保留。
  • 密钥安全:列表仅返回脱敏 Key。完整主/子 API-KEY 仅在生成或重置成功时展示一次,请由调用方安全保存。

权限与幂等

任务归属由鉴权使用的 Key决定,不接受请求参数覆盖。主 API-KEY保持原有幂等作用域;子 API-KEY的幂等作用域包含自身 Key ID,因此不同子 API-KEY 可以使用相同的幂等值而互不冲突。

统一响应结构

接口响应统一为 JSON,包含公共字段和业务字段:

json

{
  "code": 200,
  "message": "success",
  // ... 业务字段(依接口而定)
}
  • code:状态码,200 表示成功,负数表示错误
  • message:提示信息或错误原因。海外账号(clientType=overseas)返回英文提示;状态码和字段名不随语言变化,调用方应始终以 code、status 和 failCode 做程序判断
  • 其余字段由每个接口单独定义

全局错误码

code含义说明
200成功正常业务响应
-100鉴权或额度不足userNo/apiKey 缺失或不匹配,或接口执行前积分不足;以 message 为准
-200参数不合法必填字段缺失、格式错误、超出允许范围
-300业务拒绝积分不足、任务不存在或任务提交失败;若系统无法读取视频,message 会明确提示检查视频链接的公开访问与有效期
-401账号临时封禁首次有效违规封禁 1 小时,第二次有效违规封禁 24 小时;封禁有效期内的新命中不累计、不续期、不升级
-402账号永久封禁第三次有效违规永久封禁;有效违规是指命中时账号不处于封禁有效期
-500服务内部异常请稍后重试,若持续出现请联系我方
-600视频格式不支持视频编码、位深、色彩空间或音频编码不符合要求,详见「视频格式要求」

任务状态机

去字幕任务在生命周期内经历以下状态流转:

waiting→processing→success或failed
  • waiting:任务已入队,等待分配算力
  • processing:正在处理中
  • success:处理完成,可通过 resultUrl 下载结果视频
  • failed:处理失败;失败原因见 failReason,积分是否已退还请以refundStatus 为准(1 表示已退还)

接口详情

POST/open/uploadVideo(可选)

建议用户自备文件上传和存储服务,本接口为便捷方案。

上传视频文件并获取视频 URL 和封面 URL。适用于无自有存储服务的场景, 对接方也可自行将视频上传至自有存储(COS 或 VOD 均可),将视频 URL 直接传入 submitTask。

Content-Type:multipart/form-data(区别于其他接口的 application/x-www-form-urlencoded)

请求参数

字段名类型是否必填说明
userNostring是用户编号
apiKeystring是调用密钥
filefile是视频文件,最大 1GB,支持 mp4、mov 格式

业务限制

  • 文件大小上限:1GB
  • 支持的视频格式:mp4、mov
  • 分辨率上限:横竖屏统一按边长判断,最大边不超过 1920 像素且最小边不超过 1080 像素
  • 时长上限:600 秒(10 分钟)
  • 位深上限:8bit(不支持 10bit 及以上)
  • 不支持 HDR 格式视频

响应字段

字段名类型说明
codenumber状态码,200 表示成功
messagestring提示信息
videoUrlstring视频访问 URL
coverUrlstring封面图访问 URL
widthnumber视频宽度(像素)
heightnumber视频高度(像素)
durationnumber视频时长(秒,向上取整)

接口特有错误

code含义说明
-100鉴权失败userNo 或 apiKey 不正确
-200参数不合法文件为空、格式不支持、大小超过 1GB、分辨率最大边超过 1920 或最小边超过 1080、时长超过 10 分钟、位深超过 8bit、HDR 格式、无法解析视频文件。分辨率错误会在 message 中返回实际宽高和允许范围
-500服务内部异常文件保存或封面截取失败,建议稍后重试

POST/open/submitTask

受理一个去字幕任务并预扣积分。接口成功返回后,系统在后台核验视频可达性、真实时长、 分辨率和格式,核验通过后自动进入处理阶段;调用方继续使用 taskId 查询状态即可。

公开状态始终为 waiting / processing / success / failed。后台核验期间为 waiting; 核验失败时转为 failed,并按平台退款规则结算;请以任务的 refundStatus 判断是否实际退款。实测费用低于预扣时不退差额; 高于预扣且差额达到计费校正阈值时补扣,最多扣至账户余额为 0,不影响任务继续处理。

各准备阶段均有独立截止时间:后台排队5分钟、VOD源解析30秒、媒体核验120秒、 可选静音准备4分钟、任务调度3分钟、等待首次有效处理状态10分钟。 任一阶段超时后任务直接失败并退款,不再继续执行后续阶段;正式处理阶段仍按视频时长执行既有超时策略。

请求参数

字段名类型是否必填说明
userNostring是用户编号
apiKeystring是调用密钥
videoUrlstring是视频文件 URL,必须以 http:// 或 https:// 开头,长度 ≤ 2048
widthnumber是视频宽度(像素);与 height 共同满足最大边 ≤ 1920、最小边 ≤ 1080
heightnumber是视频高度(像素);与 width 共同满足最大边 ≤ 1920、最小边 ≤ 1080
durationnumber是视频时长(秒),范围 [1, 600]
x1number是字幕区域左上角 X 坐标(像素),≥ 0。全屏模式传 0
y1number是字幕区域左上角 Y 坐标(像素),≥ 0。全屏模式传 0
x2number是字幕区域右下角 X 坐标(像素),需满足 x2 > x1 且 x2 ≤ width。全屏模式传 0
y2number是字幕区域右下角 Y 坐标(像素),需满足 y2 > y1 且 y2 ≤ height。全屏模式传 0
modestring否处理模式:"normal"(默认)或 "protect"(画面保护模式,仅去除选框外部分的文字,选框内的文字保留不处理)
fileNamestring否视频文件名,trim 后非空时优先使用,否则从 videoUrl 提取
coverUrlstring否视频封面图 URL,以 http:// 或 https:// 开头,长度 ≤ 2048。未传或为空时系统使用自动生成的封面
callbackUrlstring否Webhook 回调地址,必须是可公开访问的 http(s) URL,长度 ≤ 2048。任务进入最终态后系统主动 POST;格式不合法或指向内网时按未传处理并记录审计日志
removeAudioboolean否是否在正式处理前擦除视频声音。未传或为空时默认 false;非空值仅接受 true/false。媒体核验或预处理失败时任务转为 failed,并按平台退款规则结算
Idempotency-Key / idempotencyKeystring否(推荐)安全重试标识,长度不超过 128,优先读取 Idempotency-Key 请求头,也可传同名表单参数;相同用户、相同 Key 且参数一致时返回首次 taskId,不会重复创建或扣费。复用相同 Key 但参数不同会返回 -200

响应字段

字段名类型说明
codenumber状态码,参见全局错误码表
messagestring提示信息
taskIdstring任务唯一标识,用于后续查询
statusstring固定为 "waiting",表示任务已持久化受理,不代表媒体核验或后续处理已经成功

接口特有错误

code含义说明
-200参数不合法videoUrl/width/height/duration/坐标任一缺失或格式错误;请求参数分辨率最大边超过 1920 或最小边超过 1080;时长超过 10 分钟;或幂等键非法/同一 Key 用于不同参数。真实媒体核验失败会在受理后通过任务最终态返回
-300业务拒绝积分不足,或任务无法可靠落库受理
-401账号临时封禁首次有效违规封禁 1 小时,第二次有效违规封禁 24 小时;封禁期内不累计、不续期、不升级
-402账号永久封禁第三次有效违规后永久禁止提交任务

Webhook 回调说明

若提交时传入了合法的 callbackUrl,当任务首次变为 success 或 failed 时, 系统将向该地址发送一次 HTTP POST 请求(JSON 格式),无需轮询即可获知任务结果。

  • 请求方式:POST
  • Content-Type:application/json
  • 超时:连接 5s / 读取 10s
  • HTTP 非 2xx 或临时网络异常会按 1 分钟、5 分钟、30 分钟、2 小时退避重试,首次投递在内最多尝试 5 次
  • 不安全、不可公开访问的回调地址不会重试;调用方仍应保留 taskDetail 轮询作为兜底
  • 回调地址需返回 HTTP 2xx 状态码表示接收成功

回调 Body 字段:

字段名类型说明
eventstring事件类型,固定为 "task.completed"
taskIdstring任务唯一标识
statusstring任务最终状态:success 或 failed
costnumber本任务记录的计费积分
refundStatusnumber积分退还状态:0 未记录退还,1 已退还;请以该字段判断退款结果
resultUrlstring仅 status=success 时存在,去字幕后的视频地址
failCodestring仅 status=failed 时存在的稳定失败标识
failReasonstring仅 status=failed 时存在,失败原因
timestampnumber回调发送时间(Unix 毫秒时间戳)

失败且积分已退还的回调示例:

json

{
  "event": "task.completed",
  "taskId": "t_2024xxxxxx",
  "status": "failed",
  "cost": 39,
  "refundStatus": 1,
  "failReason": "视频处理失败,请重新导出后提交(积分已退还)",
  "timestamp": 1717200000000
}

视频格式要求

任务受理后、进入处理前,系统会尽力完成视频访问、真实元数据、格式与分辨率核验。 只有明确检测到不符合要求时才拦截;检测超时或暂时无法可靠取得宽高/时长时会继续处理,随后以 VOD 元数据为准完成校正。

检测项要求不支持的情况
视频编码支持 H.264 (AVC)、H.265 (HEVC)AV1 编码
视频位深仅支持 8Bit10Bit 及以上
色彩空间仅支持 SDRHDR(PQ / HLG 传递函数)
音频编码支持 AAC、MP3 等有损编码PCM 无损编码(pcm_s16le、pcm_s24le 等)

说明:

  • 若视频包含旋转元数据(rotation metadata),系统不会拦截,但处理结果可能出现方向异常。建议上传前使用剪映或 FFmpeg 重新编码以消除旋转信息。
  • 明确无法访问视频时任务失败;仅元数据探测超时或暂时无法可靠识别格式、宽高时不会误拦截。
  • 传入 vodId 的任务同样适用上述格式检测规则。

异步核验失败标识

failCode含义
VIDEO_UNREACHABLE系统无法公开访问视频链接
VIDEO_METADATA_UNAVAILABLE120 秒核验预算内无法取得可信视频信息
VIDEO_RESOLUTION_UNSUPPORTED实测分辨率超出支持范围
VIDEO_DURATION_UNSUPPORTED实测时长超过 10 分钟
VIDEO_SELECTION_INVALID框选坐标与实测视频尺寸不匹配
VIDEO_CODEC_UNSUPPORTED视频编码不支持(如 AV1)
VIDEO_BIT_DEPTH_UNSUPPORTED视频位深不支持(如 10Bit)
VIDEO_HDR_UNSUPPORTEDHDR / PQ / HLG 不支持
VIDEO_AUDIO_UNSUPPORTED音频编码不支持;removeAudio=true 时不受 PCM 限制
VIDEO_CONTAINER_UNSUPPORTED分片 MP4 等容器格式不支持
VIDEO_FORMAT_UNSUPPORTED视频存在其他无法兼容的格式特征
VIDEO_PREPARE_FAILED视频下载、校验或声音擦除失败
VIDEO_LINK_DOWNLOAD_FAILED系统无法读取视频链接;请确认链接可公开访问、未过期且不依赖登录或 Cookie
BILLING_RECONCILE_FAILED实测信息与预扣费用校正失败,任务终止并按平台退款规则结算
PREPARE_STATE_CONFLICT任务准备状态发生冲突,任务终止并按平台退款规则结算
VIDEO_SOURCE_DOWNLOAD_FAILEDVOD 无法拉取源视频,请检查链接有效性和访问权限
VIDEO_PROCESSING_TIMEOUT视频拉取或处理超过时限
VIDEO_FORMAT_NONSTANDARD处理结果确认源视频格式不兼容
CONTENT_RESTRICTED媒体内容不符合平台规范,文件已处置
STAGE_TIMEOUT_*对应准备阶段超过内部安全时限;调用方应按未知后缀兼容处理

异步格式失败示例:

json

{
  "code": 200,
  "message": "success",
  "taskId": "t_2024xxxxxx",
  "status": "failed",
  "failCode": "VIDEO_CODEC_UNSUPPORTED",
  "failReason": "视频编码不支持:当前为 AV1 编码,仅支持 H.264/H.265 编码(积分已退还)",
  "refundStatus": 1
}

POST/open/taskDetail

查询单个任务的详细信息,包括当前状态和结果下载地址(若已完成)。

请求参数

字段名类型是否必填说明
userNostring是用户编号
apiKeystring是调用密钥
taskIdstring是提交任务时返回的 taskId,长度 1–64
subUserIdstring否提交时使用的子用户 ID;传入后会严格校验子用户归属,最长 128 字符

响应字段

字段名类型说明
codenumber状态码
messagestring提示信息
taskIdstring任务 ID
statusstring任务状态:waiting / processing / success / failed
widthnumber任务实际计费的宽度(像素)
heightnumber任务实际计费的高度(像素)
durationnumber任务实际计费的时长(秒)
x1number字幕区域左上角 X 坐标
y1number字幕区域左上角 Y 坐标
x2number字幕区域右下角 X 坐标
y2number字幕区域右下角 Y 坐标
modestring处理模式
costnumber本任务实际扣除积分
createTimenumber任务创建时间(Unix 毫秒)
updateTimenumber任务最后更新时间(Unix 毫秒)
resultUrlstring仅当 status=success 时返回,去字幕后的视频地址;自生成起 24 小时内有效
failCodestring仅当 status=failed 时返回的稳定失败标识;程序判断请使用此字段,不要解析 failReason
failReasonstring失败任务的失败原因,为系统返回的固定文案(如"视频格式不标准,请重新导出后提交");非失败任务或无失败原因时为空字符串 ""
refundStatusnumber积分退还状态:0 未记录退还,1 已退还;请以该字段判断,已退还时 failReason 同时包含简短提示

失败任务请读取 failReason 展示原因,并以 refundStatus 判断积分是否已退还; 不建议通过解析提示文案判断退款结果。

失败且积分已退还的响应示例:

json

{
  "code": 200,
  "message": "success",
  "taskId": "t_2024xxxxxx",
  "status": "failed",
  "cost": 39,
  "failReason": "视频处理失败,请重新导出后提交(积分已退还)",
  "refundStatus": 1
}

接口特有错误

code含义说明
-200参数不合法taskId 缺失、为空或长度超过 64
-300业务拒绝任务不存在或无权访问

POST/open/taskList

分页查询未删除任务,按创建时间倒序返回。状态契约保持为 waiting / processing / success / failed。

请求参数

字段名类型是否必填说明
userNostring是用户编号
apiKeystring是调用密钥
pagenumber否页码(从 0 开始),默认 0。小于 0 自动归一化为 0
sizenumber否每页条数,默认 20,有效范围 [1, 100]
subUserIdstring否按提交任务时使用的子用户 ID 过滤,最长 128 字符

响应字段

字段名类型说明
codenumber状态码
messagestring提示信息
totalnumber当前未删除任务总数
pagenumber规范化后的页码
sizenumber规范化后的每页条数
listarray未删除任务条目数组,可能为空

list 条目字段

list 条目为单个任务的概要信息,字段含义与 taskDetail 对应字段一致。失败任务可通过failReason 获取原因,并以 refundStatus 判断积分是否已退还。

字段名类型说明
taskIdstring任务 ID
statusstring任务状态:waiting / processing / success / failed
fileNamestring文件名,可能为空
coverUrlstring视频封面 URL,可能为空
widthnumber视频宽度
heightnumber视频高度
durationnumber视频时长(秒)
costnumber已扣除积分
modestring处理模式
x1number字幕区域坐标
y1number字幕区域坐标
x2number字幕区域坐标
y2number字幕区域坐标
createTimenumber任务创建时间(Unix 毫秒)
updateTimenumber任务更新时间(Unix 毫秒)
expiredTimenumber结果过期时间(Unix 毫秒)
resultUrlstring仅在 status=success 时存在,去字幕后的视频地址;自生成起 24 小时内有效
failCodestring仅在 status=failed 时存在的稳定失败标识
failReasonstring失败任务的失败原因,为系统返回的固定文案(如"视频格式不标准,请重新导出后提交");非失败任务或无失败原因时为空字符串 ""
refundStatusnumber积分退还状态:0 未记录退还,1 已退还;请以该字段判断,已退还时 failReason 同时包含简短提示

接口特有错误

code含义说明
-100鉴权失败userNo 或 apiKey 不正确

POST/open/deleteTask

软删除当前 API 用户所属的单个视频任务并立即返回;上传源视频、处理结果及重试媒资随后在后台异步清理。删除后 taskDetail 和 taskList 均不再返回该任务;已扣积分不因主动删除退还。

请求参数

字段名类型是否必填说明
userNostring是用户编号
apiKeystring是调用密钥
taskIdstring是提交任务时返回的 taskId,长度 1–64
subUserIdstring否提交时传入了 subUserId 时建议同时传入,用于严格校验子用户归属

响应字段

字段名类型说明
codenumber状态码,200 表示删除请求已接受
messagestring提示信息

接口特有错误

code含义说明
-100鉴权失败userNo 或 apiKey 不正确
-200参数不合法taskId 或 subUserId 格式不正确
-300任务不存在任务不存在、已删除或不属于当前用户
-500服务内部异常任务删除发生内部异常,请稍后重试

POST/open/removeVideoWatermark

解析短视频分享链接并返回去水印结果。 每次成功处理扣除 1 积分,失败不扣积分。

请求参数

字段名类型是否必填说明
userNostring是用户编号
apiKeystring是调用密钥
videoUrlstring是短视频平台分享链接,长度 ≤ 2048
operationIdstring否(子 API-KEY推荐)8–64 位调用方操作标识,仅允许字母、数字、点、下划线、冒号和连字符。子 API-KEY 下同时作为幂等标识;相同 operationId 与相同 videoUrl 返回首次结果,不重复扣费,若 videoUrl 不同返回 -200

响应字段

字段名类型说明
codenumber200 表示解析成功
messagestring提示信息
data.typenumber媒体类型,视频固定为 0
data.videostring去水印视频地址
data.coverstring视频封面地址(若有)
data.textstring视频文案(若有)

请求示例

bash

curl -X POST 'https://www.550wai.cn/open/removeVideoWatermark' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'userNo=YOUR_USER_NO' \
  --data-urlencode 'apiKey=sk-550w-YOUR_API_KEY' \
  --data-urlencode 'videoUrl=https://example.com/share/video' \
  --data-urlencode 'operationId=watermark-order-20260916-001'

接口特有错误

code含义说明
-100鉴权失败userNo 或 apiKey 不正确
-200参数不合法videoUrl 缺失或格式错误
-300业务失败积分不足、暂不支持该平台链接的解析或视频去水印失败;具体原因见 message,失败不扣积分
-500服务内部异常处理失败,未扣积分

POST/open/removeImageWatermark

上传一张图片并去除水印。默认等待处理结果;也可异步提交后通过任务查询接口获取结果。 每次成功处理扣除 10 积分,校验失败、处理失败或服务异常不扣积分。

请求格式

multipart/form-data

请求参数

字段名类型是否必填说明
userNostring是用户编号
apiKeystring是调用密钥
filefile是待处理图片,最大 50 MB;支持 JPG、PNG、BMP、WebP、AVIF、TIFF、SVG
syncboolean否是否等待处理结果,默认 true;传 false 时立即返回 processing,可通过任务查询接口获取结果
operationIdstring否调用方自定义的操作标识,便于业务追踪

响应字段

字段名类型说明
codenumber状态码,200 表示请求成功
messagestring提示信息
errorCodestring失败时可能返回的稳定错误标识
creditsAfternumber成功扣费后的剩余积分;任务处理中时不返回
task.taskIdstring任务唯一标识
task.statusstring任务状态:processing / success / failed / expired
task.costnumber任务计费积分,图片去水印固定为 10
task.resultUrlstringstatus=success 且结果未过期时返回;resultUrl 自生成起 24 小时内有效
task.failCodestringstatus=failed 时返回失败标识
task.failReasonstringstatus=failed 时返回失败原因
task.createTimenumber任务创建时间(Unix 毫秒)
task.expiredTimenumber文件与结果过期时间(Unix 毫秒,结果通常在生成后 24 小时失效)

请求示例

bash

curl -X POST 'https://www.550wai.cn/open/removeImageWatermark' \
  -F 'userNo=YOUR_USER_NO' \
  -F 'apiKey=sk-550w-YOUR_API_KEY' \
  -F 'file=@/path/to/image.jpg' \
  -F 'sync=true'

接口特有错误

code含义说明
-100鉴权或积分不足userNo/apiKey 不正确,或账户积分不足;不创建处理任务、不扣积分
-200参数不合法图片为空、格式不支持、超过大小限制,或 sync/taskId 参数不合法
-300业务失败服务繁忙、任务不存在或无权访问;未成功处理不扣积分
-500服务内部异常处理失败,未成功处理不扣积分

POST/open/imageWatermarkTaskDetail

查询当前账号提交的图片去水印任务状态与结果。响应字段与提交接口一致。

请求参数

字段名类型是否必填说明
userNostring是用户编号
apiKeystring是调用密钥
taskIdstring是图片去水印提交接口返回的任务标识

响应字段

字段名类型说明
codenumber状态码,200 表示请求成功
messagestring提示信息
errorCodestring失败时可能返回的稳定错误标识
creditsAfternumber成功扣费后的剩余积分;任务处理中时不返回
task.taskIdstring任务唯一标识
task.statusstring任务状态:processing / success / failed / expired
task.costnumber任务计费积分,图片去水印固定为 10
task.resultUrlstringstatus=success 且结果未过期时返回;resultUrl 自生成起 24 小时内有效
task.failCodestringstatus=failed 时返回失败标识
task.failReasonstringstatus=failed 时返回失败原因
task.createTimenumber任务创建时间(Unix 毫秒)
task.expiredTimenumber文件与结果过期时间(Unix 毫秒,结果通常在生成后 24 小时失效)

接口特有错误

code含义说明
-100鉴权或积分不足userNo/apiKey 不正确,或账户积分不足;不创建处理任务、不扣积分
-200参数不合法图片为空、格式不支持、超过大小限制,或 sync/taskId 参数不合法
-300业务失败服务繁忙、任务不存在或无权访问;未成功处理不扣积分
-500服务内部异常处理失败,未成功处理不扣积分

POST/open/queryCredits

查询当前账号可供各项 Open API 能力使用的积分余额。

请求参数

字段名类型是否必填说明
userNostring是用户编号
apiKeystring是调用密钥

响应字段

字段名类型说明
codenumber状态码
messagestring提示信息
userNostring账户编号
creditsnumber当前剩余积分(非负整数)

积分与计费

Open API 的各项能力共用账户积分余额。不同能力采用不同计费方式; API 与网页端使用同一账户积分。充值后积分可同时用于网页端处理和 Open API 调用,无需分别购买或转移。仅在接口明确的成功节点扣费,未成功处理不扣积分,异步任务的扣费状态以最终任务结果为准。

固定计费能力

  • 视频去水印:成功一次扣 1 积分
  • 图片去水印:成功一张扣 10 积分

极速去字幕计费

极速去字幕按视频时长和分辨率计费, 以分辨率阈值 921600 像素(宽 × 高)为界:

分辨率档位积分倍率示例
width × height ≤ 921600 像素(约 720P 及以下)1.3 积分 / 秒720P(1280×720 = 921600)30 秒 ≈ 39 积分
width × height > 921600 像素(高于 720P,最高 1080P)1.6 积分 / 秒1080P(1920×1080)30 秒 ≈ 48 积分
  • 实际扣费公式:积分 = ceil(duration × 倍率)(向上取整)
  • 任务失败时,通过 taskDetail、taskList 或 Webhook 的 refundStatus 确认积分退还结果;1 表示已退还
  • 分辨率要求:最大边 ≤ 1920、最小边 ≤ 1080(横屏和竖屏采用同一规则);最长时长 10 分钟

计费示例

  • 720P 视频(1280×720),时长 60 秒:ceil(60 × 1.3) = 78 积分
  • 1080P 视频(1920×1080),时长 60 秒:ceil(60 × 1.6) = 96 积分
  • 540P 视频(960×540),时长 120 秒:ceil(120 × 1.3) = 156 积分

付费套餐

API 调用消耗账户积分,可通过以下套餐充值。积分永久有效,用完即止。

1,500 积分
¥20
轻量体验
适合接口联调与低频调用
21,000 积分
¥200
专业套餐
适合高频调用与较大处理量

接入示例

视频去字幕 / 去水印

  1. 准备视频:使用公网 URL,或调用 /open/uploadVideo 上传本地视频并取得 URL、宽高和时长。
  2. 提交任务:调用 /open/submitTask,传入视频信息、处理区域和模式;重试时复用同一个幂等键。
  3. 等待结果:保存 taskId,每 30 秒调用 /open/taskDetail,或通过 callbackUrl 接收最终状态。
  4. 处理完成:success 时及时下载 resultUrl;failed 时读取 failCode 和 refundStatus。

短视频分享链接去水印

  1. 取得分享链接:复制短视频平台的公开分享链接。
  2. 发起解析:调用 /open/removeVideoWatermark,传入 userNo、apiKey 和 videoUrl。
  3. 读取结果:该接口同步返回;code=200 时从 data.video 获取无水印视频地址,并可读取 data.cover 和 data.text。
  4. 处理失败:根据数字型 code 和 message 处理错误;该场景不返回 taskId,无需轮询任务状态。

图片去水印

  1. 上传图片:调用 /open/removeImageWatermark,以 multipart/form-data 提交文件。
  2. 选择模式:sync=true 直接等待结果;sync=false 创建异步任务。
  3. 取得结果:异步模式保存 taskId,调用 /open/imageWatermarkTaskDetail 查询至最终状态。

账户与任务管理

  1. 每次请求携带 userNo 和 apiKey。
  2. 调用 /open/queryCredits 查询可用积分。
  3. 调用 /open/taskList 分页查看当前账号的任务与状态。

示例代码

下面以 submitTask 为例,展示各语言的完整请求构造与响应解析。

cURL

bash

curl -X POST 'https://www.550wai.cn/open/submitTask' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Idempotency-Key: REPLACE_WITH_A_UUID' \
  --data-urlencode 'userNo=YOUR_USER_NO' \
  --data-urlencode 'apiKey=sk-550w-YOUR_API_KEY' \
  --data-urlencode 'videoUrl=https://example.com/video.mp4' \
  --data-urlencode 'width=1280' \
  --data-urlencode 'height=720' \
  --data-urlencode 'duration=30' \
  --data-urlencode 'x1=0' \
  --data-urlencode 'y1=600' \
  --data-urlencode 'x2=1280' \
  --data-urlencode 'y2=720' \
  --data-urlencode 'mode=normal'

# 响应示例
# {
#   "code": 200,
#   "message": "success",
#   "taskId": "t_2024xxxxxx",
#   "status": "waiting"
# }

Python

python

import requests
import uuid

BASE_URL = "https://www.550wai.cn"
USER_NO = "YOUR_USER_NO"
API_KEY = "sk-550w-YOUR_API_KEY"

def submit_task(video_url, width, height, duration, box, mode="normal"):
    """提交去字幕任务"""
    x1, y1, x2, y2 = box
    payload = {
        "userNo": USER_NO,
        "apiKey": API_KEY,
        "videoUrl": video_url,
        "width": width,
        "height": height,
        "duration": duration,
        "x1": x1, "y1": y1, "x2": x2, "y2": y2,
        "mode": mode,
    }
    resp = requests.post(
        f"{BASE_URL}/open/submitTask",
        data=payload,
        headers={
            "Content-Type": "application/x-www-form-urlencoded",
            "Idempotency-Key": str(uuid.uuid4()),
        },
        timeout=10,
    )
    data = resp.json()
    if data.get("code") != 200:
        raise RuntimeError(f"submitTask failed: {data.get('code')} {data.get('message')}")
    return data["taskId"], data["status"]


def query_task_detail(task_id):
    """查询任务详情"""
    resp = requests.post(
        f"{BASE_URL}/open/taskDetail",
        data={"userNo": USER_NO, "apiKey": API_KEY, "taskId": task_id},
        timeout=10,
    )
    return resp.json()


def query_credits():
    """查询剩余积分"""
    resp = requests.post(
        f"{BASE_URL}/open/queryCredits",
        data={"userNo": USER_NO, "apiKey": API_KEY},
        timeout=10,
    )
    return resp.json()


if __name__ == "__main__":
    task_id, status = submit_task(
        video_url="https://example.com/video.mp4",
        width=1280, height=720, duration=30,
        box=(0, 600, 1280, 720),
        mode="normal",
    )
    print(f"taskId={task_id}, status={status}")

JavaScript (Node.js / 浏览器)

javascript

// Node.js / 浏览器均可使用(需 fetch 支持)
const BASE_URL = "https://www.550wai.cn";
const USER_NO = "YOUR_USER_NO";
const API_KEY = "sk-550w-YOUR_API_KEY";

async function submitTask(videoUrl, width, height, duration, box, mode = "normal", idempotencyKey = crypto.randomUUID()) {
  const [x1, y1, x2, y2] = box;
  const params = new URLSearchParams({
    userNo: USER_NO,
    apiKey: API_KEY,
    videoUrl,
    width: String(width),
    height: String(height),
    duration: String(duration),
    x1: String(x1), y1: String(y1),
    x2: String(x2), y2: String(y2),
    mode,
  });

  const resp = await fetch(`${BASE_URL}/open/submitTask`, {
    method: "POST",
    headers: {
      "Content-Type": "application/x-www-form-urlencoded",
      "Idempotency-Key": idempotencyKey,
    },
    body: params.toString(),
  });
  const data = await resp.json();
  if (data.code !== 200) {
    throw new Error(`submitTask failed: ${data.code} ${data.message}`);
  }
  return { taskId: data.taskId, status: data.status };
}

async function queryTaskDetail(taskId) {
  const params = new URLSearchParams({ userNo: USER_NO, apiKey: API_KEY, taskId });
  const resp = await fetch(`${BASE_URL}/open/taskDetail`, {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: params.toString(),
  });
  return resp.json();
}

async function queryCredits() {
  const params = new URLSearchParams({ userNo: USER_NO, apiKey: API_KEY });
  const resp = await fetch(`${BASE_URL}/open/queryCredits`, {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: params.toString(),
  });
  return resp.json();
}

// 使用示例
(async () => {
  const { taskId, status } = await submitTask(
    "https://example.com/video.mp4",
    1280, 720, 30,
    [0, 600, 1280, 720],
    "normal"
  );
  console.log("taskId:", taskId, "status:", status);
})();

Java (HttpClient, JDK 11+)

java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
import java.util.Map;
import java.util.stream.Collectors;

public class SubtitleRemovalApi {

    private static final String BASE_URL = "https://www.550wai.cn";
    private static final String USER_NO = "YOUR_USER_NO";
    private static final String API_KEY = "sk-550w-YOUR_API_KEY";

    private static final HttpClient client = HttpClient.newHttpClient();

    /**
     * 提交去字幕任务
     */
    public static String submitTask(String videoUrl, int width, int height,
                                     int duration, int x1, int y1, int x2, int y2,
                                     String mode) throws Exception {
        Map<String, String> params = Map.of(
            "userNo", USER_NO,
            "apiKey", API_KEY,
            "videoUrl", videoUrl,
            "width", String.valueOf(width),
            "height", String.valueOf(height),
            "duration", String.valueOf(duration),
            "x1", String.valueOf(x1),
            "y1", String.valueOf(y1),
            "x2", String.valueOf(x2),
            "y2", String.valueOf(y2),
            "mode", mode
        );

        String body = params.entrySet().stream()
            .map(e -> URLEncoder.encode(e.getKey(), StandardCharsets.UTF_8)
                 + "=" + URLEncoder.encode(e.getValue(), StandardCharsets.UTF_8))
            .collect(Collectors.joining("&"));

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(BASE_URL + "/open/submitTask"))
            .header("Content-Type", "application/x-www-form-urlencoded")
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();

        HttpResponse<String> response = client.send(request,
            HttpResponse.BodyHandlers.ofString());
        return response.body();
        // 解析 JSON 获取 taskId 和 status
    }

    /**
     * 查询任务详情
     */
    public static String queryTaskDetail(String taskId) throws Exception {
        String body = "userNo=" + URLEncoder.encode(USER_NO, StandardCharsets.UTF_8)
            + "&apiKey=" + URLEncoder.encode(API_KEY, StandardCharsets.UTF_8)
            + "&taskId=" + URLEncoder.encode(taskId, StandardCharsets.UTF_8);

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(BASE_URL + "/open/taskDetail"))
            .header("Content-Type", "application/x-www-form-urlencoded")
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();

        HttpResponse<String> response = client.send(request,
            HttpResponse.BodyHandlers.ofString());
        return response.body();
    }

    public static void main(String[] args) throws Exception {
        String result = submitTask(
            "https://example.com/video.mp4",
            1280, 720, 30, 0, 600, 1280, 720, "normal"
        );
        System.out.println("submitTask response: " + result);
    }
}