01使用说明
无痕AI API 由杭州岁羽网络科技有限公司研发与维护，通过 API 形式向客户输出业内领先的无痕视频去水印、去字幕、视频消除、及AI 视频增强（转高清）等技术能力。如需开通 API，或在接入过程中遇到问题，欢迎联系技术支持。
API Key：用于合法访问无痕AI API 的唯一有效凭证，请联系客服创建并妥善保管。如遗失或泄漏，请及时联系技术支持更换，并自行承担由此造成的一切损失。
视频存储：API 通过您指定的视频链接下载视频进行处理，吹完成后通过您指定的预签名链接上传，我们不提供存储服务。您需要开通自己的云存储：阿里云OSS、腾讯云COS以及七牛云等均可正常使用。
注意：由于无痕AI的算力部署在国内，如果您的云存储位于海外，跨国数据传输会及其缓慢且不稳定，推荐您开通国内的云存储服务。如果您无法开通国内的云存储服务，则建议使用海外的阿里云和腾讯云的云存储服务（推荐区域：新加坡、日本）。经过测试，AWS的S3和Cloudflare的R2几乎不可用。
注意：由于无痕AI的算力部署在国内，如果您的云存储位于海外，跨国数据传输会及其缓慢且不稳定，推荐您开通国内的云存储服务。如果您无法开通国内的云存储服务，则建议使用海外的阿里云和腾讯云的云存储服务（推荐区域：新加坡、日本）。经过测试，AWS的S3和Cloudflare的R2几乎不可用。
02请求结构
接口地址与格式
| 项目 | 说明 |
|---|---|
| 接口地址 | https://api.wuhenai.com/v2/ |
| 数据格式 | application/json |
| 字符编码 | UTF-8 |
| POST | 用于任务提交与处理（设置callback、创建任务等） |
| GET | 用于获取任务信息、下载资产 |
03公共参数
公共参数是指在每次请求中必须携带的参数（除特别说明外）。
Header
除了 /user/access_token 接口，所有请求都必须携带 Authorization。
| 参数名称 | 类型 | 必填 | 示例值 | 说明 |
|---|---|---|---|---|
| Authorization | string | ✅ | Bearer sk_19c... | 认证 Token，格式为 Bearer <access_token> |
| Content-Type | string | ✅ | application/json | 请求体格式固定为 JSON |
Query
下面 2 个参数需要在每次请求中必须携带，否则接口调用将返回失败。
| 参数名称 | 类型 | 必填 | 示例值 | 说明 |
|---|---|---|---|---|
| nonce | string | ✅ | 349acd | 随机字符串，必须唯一，用于防止重放攻击 |
| t | long | ✅ | 1712497205 | 当前 UTC 时间，从 1970/1/1 秒数 |
Response
所有接口返回的 JSON 数据均遵循以下结构。
| 参数名称 | 类型 | 说明 |
|---|---|---|
| code | int | 状态码，0 表示成功，非 0 表示失败（详见状态码） |
| message | string | 处理结果提示信息：成功或失败的原因 |
| data | object | 返回的业务数据，详情查看具体接口 |
04User 模块
User 管理负责账号相关的操作，包括获取 token、查询可用积分、查询积分充值与消费记录等。
GET/user/access_token
除本接口外，API 用户的所有请求都必须携带 access_token。使用 API Key 调用此接口即可换取 access_token。access_token 有效期 7 天，过期后接口返回 401 错误，需再次调用本接口更新。
Query 参数
| 参数名称 | 类型 | 必填 | 示例值 | 说明 |
|---|---|---|---|---|
| api_key | string | ✅ | xx45645sghrtr | 对应账号的 API Key，请向客服获取，通过官方邮件发送，注意保密 |
Response
| 参数名称 | 类型 | 示例值 | 说明 |
|---|---|---|---|
| code | int | 0 | 状态码，0 表示成功 |
| message | string | ok | 处理结果提示信息 |
| data | object | ||
| data/expired | int | 1712497205 | 过期的 UTC 时间 |
| data/access_token | string | tttt | access token |
GET/user/me
通过此接口，获取当前账户的可用积分数。
Response
| 参数名称 | 类型 | 示例值 | 说明 |
|---|---|---|---|
| code | int | 0 | 状态码，0 表示成功 |
| message | string | ok | 处理结果提示信息 |
| data | object | ||
| data/account_id | string | 唯一账户 ID | |
| data/account_name | string | 账户名称 | |
| data/balance | int | 账户的可用积分余额 |
POST/user/notify_callback
无痕AI API 通过此回调函数，通知任务的处理进度。
Query 参数
| 参数名称 | 类型 | 必填 | 示例值 | 说明 |
|---|---|---|---|---|
| callback_url | string | ✅ | 回调地址 |
Response
| 参数名称 | 类型 | 示例值 | 说明 |
|---|---|---|---|
| code | int | 0 | 状态码，0 表示成功 |
| message | string | ok | 处理结果提示信息 |
| data | object |
任务回调 Body
API 会在任务状态变化时向 callback_url 发送回调通知。回调函数的 body 结构如下：
| 参数名称 | 类型 | 示例值 | 说明 |
|---|---|---|---|
| type | int | 0 | 消息类型 |
| msg | str | ok | 处理消息 |
| data | object | ||
| data/task_id | string | 回调的任务 ID | |
| data/task_type | string | 当前任务的类型 | |
| data/status | string | 当前任务的状态（详见状态表格） | |
| data/progress | int | 任务进度：status = queued 时为前面排队任务数；status = processing 时为处理进度百分比 0-100 | |
| data/metering | int | status = success 时：计费依据。视频去水印/字幕、视频消除为视频时长（秒），图片消除为张 | |
| data/credits | int | status = success 时：本次任务扣除的积分数 | |
| data/description | string | status = failed 时：描述错误原因 |
GET/user/billings
查询近 90 天内的充值与消费账单。超过 90 天的账单，需通过客服人工导出。
Query 参数
| 参数名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| time_start | utc | 可选 | 账单查询，开始时间 |
| time_stop | utc | 可选 | 账单查询，结束时间 |
| page_index | int | 可选 | 页码 |
Response
| 参数名称 | 类型 | 示例值 | 说明 |
|---|---|---|---|
| code | int | 0 | 状态码，0 表示成功 |
| message | string | ok | 处理结果提示信息 |
| data/total_pages | int | 总页数 | |
| data/items | array | 符合条件的账单列表 | |
| data/items/billing_id | string | ddddd | 账单 ID |
| data/items/billing_type | string | free | 账单类型：free 赠送积分 / buy_credits 购买积分 / consume 消耗积分 / refund 退款（从客户账户扣除积分） |
| data/items/credits | int | -100 | 积分增减情况：- 表示消耗，+ 表示增加 |
| data/items/task_id | string | xxxxxx | 如果 billing_type = consume，则对应一条 task_id |
| data/items/task_type | string | removeWatermark_vid | 任务类型：removeWatermark_vid 去水印/去字幕 / eraseObject_vid 视频消除 / eraseObject_pic 图片消除 |
| data/items/model | string | 处理模型 | |
| data/items/method | string | 处理模式 | |
| data/items/metering | int | 任务的计费依据 | |
| data/items/amount | int | 2000 | 支付金额，单位：元；仅支付类账单有值，其他类型为空或 0 |
| data/items/create_at | int | 1712497205 | 账单创建时间 |
05Task 模块
任务模块主要负责任务的创建和管理。
POST/video_removal
创建并启动一个视频去水印/去字幕任务。无痕消除视频中通过后期包装添加的字幕、图形水印、LOGO 水印、文字水印、移动水印等。
Request 参数
| 参数名称 | 类型 | 必填 | 示例值 | 说明 |
|---|---|---|---|---|
| video_url | string | ✅ | 待处理视频的下载 URL，过期时间建议> 12 小时 | |
| model | string | 可选 | 模型选择：video_removal_std：默认，标准模型 video_removal_pro：高级模型 | |
| method | string | 可选 | 视频处理方式：all_area：默认，全屏自动识别并消除sel_area：rect 指定区域内识别并消除 | |
| rect | struct | 可选 | { "x1":100, "y1":200, "x2":500, "y2":600 } | 用于设置消除的区域：x1,y1为左上角坐标，x2,y2为右下角坐标。method = sel_area 时必须设置，且rect 区域像素面积 width × height 不可超过 480000method = all_area 时，rect 仍然可以设置，且不受480000的限制 |
| upload_url | string | ✅ | 预签名上传 URL，由云存储服务生成。过期时间要求 > 2 小时，推荐设置成 12 小时。 处理完成后算力中心直接向预签名地址上传成品，并通过 callback 通知 | |
| upload_headers | string | ✅ | { "Content-Type": "application/octet-stream" } | 生成预签名链接时由存储服务返回，不要自行构造。若与生成预签名链接时的 headers 不一致，算力中心上传时将导致失败 |
Response
| 参数名称 | 类型 | 示例值 | 说明 |
|---|---|---|---|
| code | int | 0 | 状态码，0 表示成功 |
| message | string | ok | 处理结果提示信息 |
| data | object | ||
| data/task_id | string | 当前任务的 ID |
POST/video_eraser
创建并启动一个万能视频消除任务。消除视频中的原生内容，比如行走的人、移动的汽车，同时可以用来消除马赛克等遮挡、修复视频画面。
Request 参数
| 参数名称 | 类型 | 必填 | 示例值 | 说明 |
|---|---|---|---|---|
| video_url | string | ✅ | 待处理视频的下载 URL，过期时间建议> 12 小时 | |
| track_mode | string | ✅ | 跟踪模式：no_tracking： 固定位置不跟踪 auto_tracking：智能识别由 custom_mask 和 time_mask 标记的对象并在整个视频中智能跟踪其移动 | |
| time_mask | int | 可选 | 82000 | custom_mask 所在的时间点，单位毫秒，从视频开始位置计算 track_mode = auto_tracking 时必填track_mode = no_tracking 时此参数无效 |
| custom_mask | string(base64) | ✅ | 标记待消除区域的 mask，base64 编码。mask 尺寸需与视频尺寸一致 | |
| upload_url | string | ✅ | 同 video_removal接口 | |
| upload_headers | string | ✅ | 同 video_removal接口 |
Response
| 参数名称 | 类型 | 示例值 | 说明 |
|---|---|---|---|
| code | int | 0 | 状态码，0 表示成功 |
| message | string | ok | 处理结果提示信息 |
| data | object | ||
| data/task_id | string | 当前任务的 ID |
POST/video_upscale
创建并启动一个视频高清任务。将视频分辨率提升到 1080P 或 2K，同时使用 AI 模型有效提升原视频画质。
Request 参数
| 参数名称 | 类型 | 必填 | 示例值 | 说明 |
|---|---|---|---|---|
| video_url | string | ✅ | 待处理视频的下载 URL，过期时间建议> 12 小时 | |
| upscale_option | string | ✅ | 输出的视频分辨率：UPS_1080P: 输出 1080P 并提升画质（最小边放大到 1080，最大边等比折算） UPS_2K: 输出 2K 并提升画质（最小边放大到 1440，最大边等比折算） | |
| upload_url | string | ✅ | 同 video_removal接口 | |
| upload_headers | string | ✅ | 同 video_removal接口 |
Response
| 参数名称 | 类型 | 示例值 | 说明 |
|---|---|---|---|
| code | int | 0 | 状态码，0 表示成功 |
| message | string | ok | 处理结果提示信息 |
| data | object | ||
| data/task_id | string | 当前任务的 ID |
GET/photo_eraser暂未开放
创建并启动一个图片消除任务。消除图片中的水印、文字以及不想要的画面元素（如戴着的眼镜、脸上的痣等）。
Request 参数
| 参数名称 | 类型 | 必填 | 示例值 | 说明 |
|---|---|---|---|---|
| source_img | string | ✅ | 待处理图片的下载 URL，过期时间建议> 1 小时` | |
| remove_option | string | ✅ | 消除目标的预设 ID：PXC_1000 自定义提示词消除 PXC_1001 消除图中的水印与 LOGO PXC_1002 消除图中的文字 PXC_1003 消除图中的手写笔记 PXC_1004 消除图中的贴纸与表情 PXC_1005 消除图中的路人PXC_9000 自定义消除区域 | |
| custom_prompt | string | 可选 | 用户自定义消除目标的提示词 remove_option = PXC_1000 时有效 | |
| custom_mask | string(base64) | 可选 | 用户自定义的消除区域 mask remove_option = PXC_9000 时有效 | |
| upload_url | string | ✅ | 同 video_removal接口 | |
| upload_headers | struct | ✅ | 同 video_removal接口 |
Response
| 参数名称 | 类型 | 示例值 | 说明 |
|---|---|---|---|
| code | int | 0 | 状态码，0 表示成功 |
| message | string | ok | 处理结果提示信息 |
| data | object | ||
| data/task_id | string | 当前任务的 ID |
GET/status
查询指定任务的状态。推荐使用任务回调。
Query 参数
| 参数名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| task_id | string | ✅ | 查询的任务 ID |
Response
| 参数名称 | 类型 | 示例值 | 说明 |
|---|---|---|---|
| code | int | 0 | 状态码，0 表示成功 |
| message | string | ok | 处理结果提示信息 |
| data/task_id | string | 返回状态的任务 ID | |
| data/status | string | processing | 当前任务的状态（详见任务状态） |
| data/progress | int | 任务进度： status = queued 时为前面排队任务数status = processing 时为处理进度百分比 0-100 整数 | |
| data/description | string | status = failed 时描述错误原因 |
任务状态
| 任务状态 | 说明 |
|---|---|
| created | 任务已创建，未启动 |
| queued | 任务已启动，正在排队等候处理 |
| processing | 任务正在处理中，进度 10%（下载）+ 80%（处理）+ 10%（上传） |
| success | 处理完成，并上传到目标服务器成功 |
| failed | 任务处理失败 |
| paused | 任务被暂停（通过调用 cancel 接口） |
POST/cancel
取消排队中的任务。如果任务已经开始处理或处理完成，此接口将返回失败。取消的任务不会扣除积分。
Request 参数
| 参数名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| task_id | string | ✅ | 需要取消的任务 ID |
Response
| 参数名称 | 类型 | 示例值 | 说明 |
|---|---|---|---|
| code | int | 0 | 状态码，0 表示成功 |
| message | string | ok | 处理结果提示信息 |
| data | object |
06状态码与说明
| 状态码 | 含义 | 说明 |
|---|---|---|
| 0 | 成功 | 请求处理成功 |
| 1001 | 参数错误 | 缺少必填参数、参数格式不正确，或访问了无效路径 |
| 3001 | 积分不足 | 当前账号积分余额不足，无法创建任务 |
| 4001 | 资源错误 | 常见于工作流配置不存在 |
| 4003 | 用户不可用 | 当前用户不存在、已禁用，或状态不可继续使用 |
| 4004 | 任务不存在 | task_id 不存在，或该任务不属于当前用户 |
| 4005 | 任务不可取消 | 仅排队中的任务支持取消 |
| 401 | 未登录 | access_token 缺失、无效或已过期 |
| 7003 | API Key 无效或已禁用 | API Key 不存在、已禁用，或不属于可用状态 |
| 7004 | API Key 已过期 | API Key 已超过有效期，不能继续换取 access_token |
07AI编程
为了让 AI 能稳定、准确地生成可直接运行的接入代码，建议将接口文档以 Markdown 形式作为上下文提供给 AI，并要求其严格按字段与鉴权规则实现。
Markdown 文档
推荐提示词
Prompt
你是资深后端工程师。请通读并仅依据《api_2_1.md》生成可运行代码。 要求： 1) 先调用 GET /user/access_token（query: api_key）获取 access_token； 2) 后续请求必须携带 Header: Authorization: Bearer <access_token>； 3) 所有接口必须携带 Query: nonce 与 t（UTC 秒）； 4) 严格按文档字段与类型构造请求/解析响应，并对 code!=0 给出可读错误信息； 5) 输出一份完整示例：创建任务（任选 /video_removal 或 /video_upscale）-> 轮询/查询任务状态 -> 打印结果。 请输出：代码 + 必要的运行说明（如何配置 api_key、如何生成 nonce 与 t）。
08技术支持
欢迎接入无痕AI API
接入和运行过程中遇到技术问题，请联系在线技术支持
