API REFERENCE · 接口文档

API接入文档

版本 V2.1 · 最后更新 2026-07-27

01使用说明

无痕AI API 由杭州岁羽网络科技有限公司研发与维护,通过 API 形式向客户输出业内领先的无痕视频去水印、去字幕、视频消除、及AI 视频增强(转高清)等技术能力。如需开通 API,或在接入过程中遇到问题,欢迎联系技术支持。

API Key:用于合法访问无痕AI API 的唯一有效凭证,请妥善保管。如遗失或泄漏,请及时禁用并更换新的API KEY。您可以通过API管理工作台,来创建和管理API KEY。
视频存储:API 通过您指定的视频链接下载视频进行处理,处理完成后通过您指定的预签名链接上传,我们不提供存储服务。您需要开通自己的云存储:阿里云OSS、腾讯云COS以及七牛云等均可正常使用。
注意:由于无痕AI的算力部署在国内,如果您的云存储位于海外,跨国数据传输会缓慢且不稳定,推荐您开通国内的云存储服务。如果您无法开通国内的云存储服务,则建议使用海外的阿里云和腾讯云的云存储服务(推荐区域:新加坡、日本)。
经过测试,AWS的S3和Cloudflare的R2几乎不可用。

02请求结构

接口地址与格式

项目说明
接口地址https://api.wuhenai.com/v2/
数据格式application/json
字符编码UTF-8
POST用于任务提交与处理(设置callback、创建任务等)
GET用于获取任务信息、下载资产

03公共参数

公共参数是指在每次请求中必须携带的参数(除特别说明外)。

Header

除了 /user/access_token 接口,所有请求都必须携带 Authorization。

参数名称类型必填示例值说明
Authorizationstring✅Bearer sk_19c...认证 Token,格式为 Bearer <access_token>
Content-Typestring✅application/json请求体格式固定为 JSON

Query

下面 2 个参数需要在每次请求中必须携带,否则接口调用将返回失败。

参数名称类型必填示例值说明
noncestring✅349acd随机字符串,必须唯一,用于防止重放攻击
tlong✅1712497205当前 UTC 时间,从 1970/1/1 秒数

Response

所有接口返回的 JSON 数据均遵循以下结构。

参数名称类型说明
codeint状态码,0 表示成功,非 0 表示失败(详见状态码)
messagestring处理结果提示信息:成功或失败的原因
dataobject返回的业务数据,详情查看具体接口

04User 模块

User 管理负责账号相关的操作,包括获取 token、查询可用积分、查询积分充值与消费记录等。

GET/user/access_token

除本接口外,API 用户的所有请求都必须携带 access_token。使用 API Key 调用此接口即可换取 access_token。access_token 有效期 7 天,过期后接口返回 401 错误,需再次调用本接口更新。

Query 参数

参数名称类型必填示例值说明
api_keystring✅xx45645sghrtr对应账号的 API Key,请向客服获取,通过官方邮件发送,注意保密

Response

参数名称类型示例值说明
codeint0状态码,0 表示成功
messagestringok处理结果提示信息
dataobject
data/expiredint1712497205过期的 UTC 时间
data/access_tokenstringttttaccess token
GET/user/me

通过此接口,获取当前账户的可用积分数。

Response

参数名称类型示例值说明
codeint0状态码,0 表示成功
messagestringok处理结果提示信息
dataobject
data/account_idstring唯一账户 ID
data/account_namestring账户名称
data/balanceint账户的可用积分余额
POST/user/notify_callback

无痕AI API 通过此回调函数,通知任务的处理进度。

Query 参数

参数名称类型必填示例值说明
callback_urlstring✅回调地址

Response

参数名称类型示例值说明
codeint0状态码,0 表示成功
messagestringok处理结果提示信息
dataobject

任务回调 Body

API 会在任务状态变化时向 callback_url 发送回调通知。回调函数的 body 结构如下:

参数名称类型示例值说明
typeint0消息类型
msgstrok处理消息
dataobject
data/task_idstring回调的任务 ID
data/task_typestring当前任务的类型,定义参考查询账单中的对应字段
data/statusstring当前任务的状态,定义参考查询任务状态中的对应字段
data/progressint任务进度:status = queued 时为前面排队任务数;status = processing 时为处理进度百分比 0-100
data/meteringintstatus = success 时:计费依据。视频去水印/字幕、视频消除为视频时长(秒),图片消除为张
data/creditsintstatus = success 时:本次任务扣除的积分数
data/descriptionstringstatus = failed 时:描述错误原因
GET/user/billings

查询近 90 天内的充值与消费账单。超过 90 天的账单,需通过客服人工导出。

Query 参数

参数名称类型必填说明
time_startutc可选账单查询,开始时间
time_stoputc可选账单查询,结束时间
page_indexint可选页码

Response

参数名称类型示例值说明
codeint0状态码,0 表示成功
messagestringok处理结果提示信息
data/total_pagesint总页数
data/itemsarray符合条件的账单列表
data/items/billing_idstringddddd账单 ID
data/items/billing_typestringfree账单类型:free 赠送积分 / buy_credits 购买积分 / consume 消耗积分 / refund 退款(从客户账户扣除积分)
data/items/creditsint-100积分增减情况:- 表示消耗,+ 表示增加
data/items/task_idstringxxxxxx如果 billing_type = consume,则对应一条 task_id
data/items/task_typestringremoveWatermark_vid任务类型:
removeWatermark_vid: 去水印/去字幕
eraseObject_vid: 万能视频消除
upscale_vid: 视频增强
eraseObject_pic: 图片消除
data/items/modelstring处理模型
data/items/methodstring处理模式
data/items/meteringint任务的计费依据
data/items/amountint2000支付金额,单位:元;仅支付类账单有值,其他类型为空或 0
data/items/create_atint1712497205账单创建时间

05Task 模块

任务模块主要负责任务的创建和管理。

POST/video_removal

创建并启动一个视频去水印/去字幕任务。无痕消除视频中通过后期包装添加的字幕、图形水印、LOGO 水印、文字水印、移动水印等。
视频去水印与去字幕为同一接口。在模型选择上,STD在处理效果上占优;PRO模型在处理速度上占优,以1分钟1080P视频全屏处理为例,PRO模型的处理时长约100秒,STD模型约200秒。

Request 参数

参数名称类型必填示例值说明
video_urlstring✅待处理视频的下载 URL,过期时间建议> 12 小时
modelstring可选模型选择:
video_removal_std:默认,标准模型
video_removal_pro:高级模型
methodstring可选视频处理方式:
all_area:默认,全屏自动识别并消除
sel_area:rect 指定区域内识别并消除
rectstruct可选{ "x1":100, "y1":200, "x2":500, "y2":600 }用于设置消除的区域:
x1,y1为左上角坐标,x2,y2为右下角坐标。
method = sel_area 时必须设置,且rect 区域像素面积 width × height 不可超过 480000
method = all_area 时,rect 仍然可以设置,且不受480000的限制
upload_urlstring✅预签名上传 URL,由云存储服务生成。过期时间要求 > 2 小时,推荐设置成 12 小时。
处理完成后算力中心直接向预签名地址上传成品,并通过 callback 通知
upload_headersstring✅{ "Content-Type": "application/octet-stream" }生成预签名链接时由存储服务返回,不要自行构造。若与生成预签名链接时的 headers 不一致,算力中心上传时将导致失败

Response

参数名称类型示例值说明
codeint0状态码,0 表示成功
messagestringok处理结果提示信息
dataobject
data/task_idstring当前任务的 ID
POST/video_eraser

创建并启动一个万能视频消除任务。消除视频中的原生内容,比如行走的人、移动的汽车,同时可以用来消除马赛克等遮挡、修复视频画面。

Request 参数

参数名称类型必填示例值说明
video_urlstring✅待处理视频的下载 URL,过期时间建议> 12 小时
track_modestring✅跟踪模式:
no_tracking: 固定位置不跟踪
auto_tracking:智能识别由 custom_mask 和 time_mask 标记的对象并在整个视频中智能跟踪其移动
time_maskint可选82000custom_mask 所在的时间点,单位毫秒,从视频开始位置计算
track_mode = auto_tracking 时必填
track_mode = no_tracking 时此参数无效
custom_maskstring(base64)✅标记待消除区域的 mask,base64 编码。mask 尺寸需与视频尺寸一致
upload_urlstring✅同 video_removal接口
upload_headersstring✅同 video_removal接口

Response

参数名称类型示例值说明
codeint0状态码,0 表示成功
messagestringok处理结果提示信息
dataobject
data/task_idstring当前任务的 ID
POST/video_upscale

创建并启动一个视频高清任务。将视频分辨率提升到 1080P 或 2K,同时使用 AI 模型有效提升原视频画质。

Request 参数

参数名称类型必填示例值说明
video_urlstring✅待处理视频的下载 URL,过期时间建议> 12 小时
upscale_optionstring✅输出的视频分辨率:
UPS_1080P: 输出 1080P 并提升画质(最小边放大到 1080,最大边等比折算)
UPS_2K: 输出 2K 并提升画质(最小边放大到 1440,最大边等比折算)
upload_urlstring✅同 video_removal接口
upload_headersstring✅同 video_removal接口

Response

参数名称类型示例值说明
codeint0状态码,0 表示成功
messagestringok处理结果提示信息
dataobject
data/task_idstring当前任务的 ID
GET/photo_eraser暂未开放

创建并启动一个图片消除任务。消除图片中的水印、文字以及不想要的画面元素(如戴着的眼镜、脸上的痣等)。

Request 参数

参数名称类型必填示例值说明
source_imgstring✅待处理图片的下载 URL,过期时间建议> 1 小时`
remove_optionstring✅消除目标的预设 ID:
PXC_1000 自定义提示词消除
PXC_1001 消除图中的水印与 LOGO
PXC_1002 消除图中的文字
PXC_1003 消除图中的手写笔记
PXC_1004 消除图中的贴纸与表情
PXC_1005 消除图中的路人
PXC_9000 自定义消除区域
custom_promptstring可选用户自定义消除目标的提示词
remove_option = PXC_1000 时有效
custom_maskstring(base64)可选用户自定义的消除区域 mask
remove_option = PXC_9000 时有效
upload_urlstring✅同 video_removal接口
upload_headersstruct✅同 video_removal接口

Response

参数名称类型示例值说明
codeint0状态码,0 表示成功
messagestringok处理结果提示信息
dataobject
data/task_idstring当前任务的 ID
GET/status

查询指定任务的状态。推荐使用任务回调。

Query 参数

参数名称类型必填说明
task_idstring✅查询的任务 ID

Response

参数名称类型示例值说明
codeint0状态码,0 表示成功
messagestringok处理结果提示信息
data/task_idstring返回状态的任务 ID
data/statusstringprocessing当前任务的状态(详见任务状态)
data/progressint任务进度:
status = queued 时为前面排队任务数
status = processing 时为处理进度百分比 0-100 整数
data/descriptionstringstatus = failed 时描述错误原因

任务状态

任务状态说明
created任务已创建,未启动
queued任务已启动,正在排队等候处理
processing任务正在处理中,进度 10%(下载)+ 80%(处理)+ 10%(上传)
success处理完成,并上传到目标服务器成功
failed任务处理失败
paused任务被暂停(通过调用 cancel 接口)
POST/cancel

取消排队中的任务。如果任务已经开始处理或处理完成,此接口将返回失败。取消的任务不会扣除积分。

Request 参数

参数名称类型必填说明
task_idstring✅需要取消的任务 ID

Response

参数名称类型示例值说明
codeint0状态码,0 表示成功
messagestringok处理结果提示信息
dataobject

06状态码与说明

状态码含义说明
0成功请求处理成功
1001参数错误缺少必填参数、参数格式不正确,或访问了无效路径
3001积分不足当前账号积分余额不足,无法创建任务
4001资源错误常见于工作流配置不存在
4003用户不可用当前用户不存在、已禁用,或状态不可继续使用
4004任务不存在task_id 不存在,或该任务不属于当前用户
4005任务不可取消仅排队中的任务支持取消
401未登录access_token 缺失、无效或已过期
7003API Key 无效或已禁用API Key 不存在、已禁用,或不属于可用状态
7004API Key 已过期API Key 已超过有效期,不能继续换取 access_token

07AI编程

为了让 AI 能稳定、准确地生成可直接运行的接入代码,建议将接口文档以 Markdown 形式作为上下文提供给 AI,并要求其严格按字段与鉴权规则实现。

Markdown 文档

推荐提示词

Prompt
你是一名资深全栈工程师。请帮我在我的项目里集成「无痕AI」视频处理 API(去水印、去字幕、视频增强)。

## 我的需求
{一句话描述:例如"做一个页面,输入视频链接,一键去水印,处理完显示下载链接"}

## 我的技术栈
{例如:Next.js 14 + TypeScript + Tailwind;或 Vite + React;或纯 HTML + 原生 JS}

## API 权威信息(严格遵守,禁止臆测接口或参数)
- OpenAPI 规范(最权威,请优先读取并以它为准):`https://www.wuhenai.com/openapi.yaml`
- 基础地址:`https://api.wuhenai.com/v2`
- 在线文档:`https://www.wuhenai.com/api-docs/`
- 鉴权分两步:
  1. 用 API Key 调用 GET /user/access_token?api_key=<key> 换取 access_token(有效期 7 天,需缓存复用,避免每次重新换取)
  2. 之后所有请求头携带 Authorization: Bearer <access_token>
- 所有接口(含换取 token)都必须带 query 参数:nonce(随机字符串)、t(当前 UTC 秒数时间戳)
- 所有响应统一为 { code, message, data } 结构,code=0 表示成功,非 0 表示失败
- 任务为异步:创建任务(如 POST /video_removal)只返回 data.task_id,需通过回调或轮询获取处理结果
- 上传机制:需自备云存储(阿里云 OSS / 腾讯云 COS)生成预签名上传 URL,作为 upload_url 参数传入;处理完成后结果会 PUT 到该地址
- 字段命名:视频 URL 用 video_url,图片 URL 用 image_url

## 安全红线(必须遵守)
- API Key 绝对不要硬编码在前端代码里,只能放在后端环境变量(如 .env 的 WUHENAI_API_KEY)
- 前端不直接调用无痕AI,而是调用你自己的后端接口(如 Next.js API Route / Serverless Function / Node 服务),由后端代理转发到无痕AI
- 后端代理层负责:换取并缓存 access_token、拼接 nonce 与 t、转发请求

## 交付要求
- 输出完整可运行的代码:前端页面 + 后端代理
- 代码注释用中文,关键步骤(鉴权、轮询、上传)有明确说明

08技术支持

欢迎接入无痕AI API

接入和运行过程中遇到技术问题,请联系在线技术支持

在线技术支持二维码
在线时间:09:00 - 22:00