图片去水印接口文档
提交图片地址和正向提示词,异步生成去水印结果。支持尺寸、张数、LoRA 与加密输出,完成后查询或回调。
提交一张图片和正向提示词,生成去水印结果。调用方只传 img_url1。提交上游时 img_url2、img_url3 使用同一地址。本接口是异步的。受理后用任务号查询结果;请求里带了回调地址时,任务结束会再 POST 同一份结果。
| 方法与路径 | 产品编码 | 说明 |
|---|---|---|
POST /api/image_remove_watermark | image_remove_watermark | 提交图片去水印任务 |
GET /api/tasks/{request_id} | — | 查询任务。视频去水印、音频字幕、智能字幕和字幕翻译也使用此接口 |
不填回调地址也可以提交,结果用查询接口获取。
| 环境 | 根地址 |
|---|---|
| 测试 | https://test-star-api.aiaibase.com |
| 正式 | https://star-api.aiaibase.com |
路径接在根地址后面。例如测试环境提交图片去水印:
POST https://test-star-api.aiaibase.com/api/image_remove_watermark请求体为 JSON,Content-Type: application/json。单次请求体不超过 1 MB。认证只使用请求头,不需要额外的 Secret:
Authorization: Bearer {API Key}{API Key} 为商户密钥全文。
需要去掉视频画面水印时,使用视频去水印。需要从音轨生成字幕时,使用音频字幕。需要自动选择字幕轨、画面字幕或语音识别时,使用智能字幕。若只需翻译已经分好条的字幕,请使用字幕翻译。
所有响应都是同一结构。判断业务结果以 success 和 error.code 为准。认证失败返回 HTTP 401。其它情况 HTTP 状态都是 200。
| 字段 | 类型 | 说明 |
|---|---|---|
success | bool | 受理成功、处理中、处理成功为 true;失败为 false |
data | object | 成功或处理中的业务数据。失败时不返回 |
message | string | 失败说明。成功时通常不返回 |
error | object | 失败时的错误 |
meta.request_id | string | 平台任务号。后续查询、回调都用这个值 |
meta.timestamp | string | 响应时间,RFC3339,例如 2026-10-20T22:02:29.735909+08:00 |
错误对象:
| 字段 | 类型 | 说明 |
|---|---|---|
error.code | int | 业务错误码 |
error.message | string | 错误说明 |
error.details | array | 参数错误时给出字段。每项含 field、message |
调用方请求号:
- 字段可用
client_request_id,也可用别名request_id。两者都传时以client_request_id为准。task_id是另一个别名,只在前两者都为空时使用。 - 这是调用方自己的单号,和响应里的
meta.request_id不是同一个值。 - 同一密钥下,相同调用方请求号且请求体完全一致时,返回上一次的受理或结果,不会再次受理。
- 同一密钥下,调用方请求号相同但请求体不同,返回 HTTP 200,业务码
4003,说明「资源冲突」。 - 填写了
notice_url、callback_url或notify_url时,必须带调用方请求号。
受理成功只表示任务已收下,结果还没生成。服务端提交上游失败(连不上、超时、通道未配置)会自动重试,间隔约 10 秒、30 秒、60 秒,最多 3 次。这段时间查询仍是 accepted。3 次都失败才把任务标为失败并回调,业务码 3600。上游明确拒绝参数时不重试,直接失败。
服务端瞬时过载、本次没能受理时返回 HTTP 200,业务码 9001。这次不计费。退避 1 到 3 秒后用同一个调用方请求号重试即可,请求体不要改。
提交一张图片和正向提示词,生成去水印结果。调用方只传 img_url1。提交上游时 img_url2、img_url3 使用同一地址。
- 方法:
POST - 路径:
/api/image_remove_watermark - 产品编码:
image_remove_watermark
请求参数
| 字段 | 必填 | 类型 | 说明 |
|---|---|---|---|
img_url1 | 是 | string | 图片地址,http 或 https,上游必须能访问。提交上游时 img_url2、img_url3 使用同一地址 |
positive_prompt | 是 | string | 正向提示词,最多 4000 个字 |
width | 否 | int | 图片宽度,1 到 8192 |
height | 否 | int | 图片高度,1 到 8192 |
batch_size | 否 | int | 生成张数,1 到 32 |
lora_list | 否 | array | LoRA 列表,最多 20 项。每项含 name(字符串)和 strength(数字)。也可传同等内容的 JSON 字符串 |
bid | 否 | string | 业务编号,最多 200 字 |
title | 否 | string | 任务标题,最多 200 字 |
is_encrypt | 否 | bool | 是否加密输出。默认 false。不传时上游仍会收到 false。也可传字符串 true、false |
notice_url | 否 | string | 完成后的回调地址 |
callback_url | 否 | string | notice_url 的别名 |
notify_url | 否 | string | notice_url 的别名。notice_url、callback_url 都为空时才使用 |
client_request_id | 条件 | string | 调用方请求号。填写回调地址时必填 |
request_id | 条件 | string | client_request_id 的别名 |
task_id | 条件 | string | client_request_id 的别名。前两者都为空时才使用 |
成功一次按次计费。参数错误、提交失败和上游失败不计费。单价见首页透明接口定价。
受理返回
HTTP 200。此时任务尚未完成。
| 字段 | 类型 | 说明 |
|---|---|---|
data.status | string | 固定为 accepted |
data.client_request_id | string | 调用方请求号。未传时为空字符串 |
meta.request_id | string | 平台任务号,用于查询 |
{
"success": true,
"data": {
"status": "accepted",
"client_request_id": "img-ep01"
},
"meta": {
"request_id": "42642e01-2e33-4265-b6af-206eed371fff",
"timestamp": "2026-10-20T22:02:29.735909+08:00"
}
}请求示例
curl -X POST 'https://test-star-api.aiaibase.com/api/image_remove_watermark' \
-H 'Authorization: Bearer {API Key}' \
-H 'Content-Type: application/json' \
-d '{
"img_url1": "https://cdn.example.com/a.jpg",
"positive_prompt": "去掉画面水印,保持原图内容",
"width": 1024,
"height": 1024,
"batch_size": 1,
"is_encrypt": false,
"title": "图片去水印",
"client_request_id": "img-ep01",
"notice_url": "https://your.host/hook"
}'图片去水印、视频去水印、音频字幕、智能字幕和字幕翻译共用。只能查询当前密钥自己受理的任务,查不到或密钥不匹配时返回 HTTP 200,业务码 1000。
- 方法:
GET - 路径:
/api/tasks/{request_id} request_id:受理响应里的meta.request_id
处理尚未结束时 HTTP 200,data.status 仍为 accepted,并带 client_request_id。成功后 HTTP 200,data 换成下方去水印结果。失败时 HTTP 仍是 200,success 为 false,原因在 error.code。认证失败除外,那种情况是 HTTP 401。
curl 'https://test-star-api.aiaibase.com/api/tasks/42642e01-2e33-4265-b6af-206eed371fff' \
-H 'Authorization: Bearer {API Key}'处理中:
{
"success": true,
"data": {
"status": "accepted",
"client_request_id": "img-ep01"
},
"meta": {
"request_id": "42642e01-2e33-4265-b6af-206eed371fff",
"timestamp": "2026-10-20T22:02:31.000000+08:00"
}
}查询成功,以及成功回调的 data,来自上游任务对象,并写入 client_request_id、upstream_task_id。不返回 hash_key。
上游任务对象里常见这些字段。图片结果地址以上游实际返回为准,完成前查询接口不会把处理中状态当成成功结果。
| 字段 | 类型 | 说明 |
|---|---|---|
client_request_id | string | 调用方请求号,由本服务写入 |
upstream_task_id | string | 上游任务号,由本服务写入 |
task_id | string | 上游任务号 |
task_type | string | 上游任务类型 |
status | int | 上游状态。2 为完成。0、1、3 仍在处理 |
image_size | string | 上游返回的图片尺寸 |
batch_size | int | 实际生成张数 |
bid | string | 业务编号 |
title | string | 任务标题 |
created_at | string | 上游创建时间 |
updated_at | string | 上游更新时间 |
处理中的上游状态不会出现在成功结果里。查询未完成时 data.status 仍是 accepted。
{
"success": true,
"data": {
"client_request_id": "img-ep01",
"upstream_task_id": "img-ep01",
"task_id": "img-ep01",
"status": 2,
"image_size": "1024x1024",
"batch_size": 1,
"title": "图片去水印"
},
"meta": {
"request_id": "42642e01-2e33-4265-b6af-206eed371fff",
"timestamp": "2026-10-28T22:40:00+08:00"
}
}请求体带 notice_url、callback_url 或 notify_url,且任务进入成功或失败后,本服务向该地址发起 POST。没有回调地址时不会 POST。
| 项 | 值 |
|---|---|
| 方法 | POST |
Content-Type | application/json |
User-Agent | star-openapi |
| 请求体 | 与 GET /api/tasks/{request_id} 的响应 JSON 相同 |
| 成功条件 | 回调地址返回 HTTP 2xx |
| 重试 | 非 2xx 或连接失败时,间隔 30 秒重试,最多 4 次 |
| 超时 | 单次回调等待 10 秒 |
上游提交在自动重试耗尽后失败,或任务超过 24 小时仍未完成,都会记为失败并按上面的规则回调。超过 24 小时的业务码是 3601,说明「字幕任务已超过 24 小时」。
成功回调的请求体就是上一节的成功 JSON。失败回调示例:
{
"success": false,
"message": "上游处理失败",
"error": {
"code": 3600,
"message": "上游处理失败"
},
"meta": {
"request_id": "42642e01-2e33-4265-b6af-206eed371fff",
"timestamp": "2026-10-20T22:04:10.000000+08:00"
}
}接收方按 success 区分成功和失败。成功时读取 data,失败时读取 error.code 与 error.message。用 meta.request_id 或 data.client_request_id 对应自己的业务单。图片结果地址以上游实际返回为准。
下表按业务码从小到大排列。HTTP 状态不参与排序:1102、5003、5301、5304 是 401,其余是 200。
| HTTP | 业务码 | 说明 | 常见原因 |
|---|---|---|---|
| 200 | 1000 | 资源未找到 | 任务号不存在,或不属于当前密钥 |
| 200 | 1001 | 参数错误 | 图片尺寸、提示词或 lora_list 不合法。字段在 error.details |
| 200 | 1004 | 请求实体过大 | 请求体超过 1 MB |
| 200 | 1101 | JSON格式错误 | 请求体不是合法 JSON |
| 401 | 1102 | 缺少必要的请求头 | 没有 Authorization |
| 200 | 1500 | 服务器内部错误 | 未归类的服务端错误 |
| 200 | 1502 | 服务暂不可用 | 通道未配置,或价格未配置 |
| 200 | 3600 | 上游处理失败 | 任务提交或处理失败。说明可能是上游返回的具体原因 |
| 200 | 3601 | 上游处理超时 | 提交超时,或任务超过 24 小时仍未完成 |
| 200 | 4003 | 资源冲突 | 同一调用方请求号对应了不同请求体 |
| 200 | 4102 | 缺少必填项 | 未传 img_url1 或正向提示词,或填了回调地址却没有调用方请求号 |
| 200 | 4107 | 地址不合法 | img_url1 或回调地址不是 http 或 https |
| 401 | 5003 | 认证信息无效 | API Key 错误 |
| 200 | 5103 | 账户已被禁用 | 商户已停用 |
| 200 | 5104 | 账户已被暂停 | 商户已暂停 |
| 200 | 5204 | 资源访问被拒绝 | 密钥没有该接口权限 |
| 401 | 5301 | 令牌已过期 | 密钥已过期 |
| 401 | 5304 | 令牌已被撤销 | 密钥已停用或已重置 |
| 200 | 5705 | 请求过于频繁 | 超过密钥或接口的频率限制 |
| 200 | 9001 | 系统负载过高 | 服务端瞬时过载,本次未受理、不计费。退避 1 到 3 秒后重试 |
| 200 | 9902 | 配额已超出 | 套餐额度用尽,或触发接口用量上限 |
| 200 | 9903 | 余额不足 | 预付商户现金和剩余透支不足以支付本次调用 |
参数错误时,error.details 给出字段和说明。认证失败示例:
{
"success": false,
"message": "认证信息无效",
"error": {
"code": 5003,
"message": "认证信息无效"
},
"meta": {
"request_id": "7c1a0e2d-1111-4222-8333-444455556666",
"timestamp": "2026-10-22T04:40:00+08:00"
}
}