图片去水印接口文档

提交图片地址和正向提示词,异步生成去水印结果。支持尺寸、张数、LoRA 与加密输出,完成后查询或回调。

提交一张图片和正向提示词,生成去水印结果。调用方只传 img_url1。提交上游时 img_url2、img_url3 使用同一地址。本接口是异步的。受理后用任务号查询结果;请求里带了回调地址时,任务结束会再 POST 同一份结果。

方法与路径产品编码说明
POST /api/image_remove_watermarkimage_remove_watermark提交图片去水印任务
GET /api/tasks/{request_id}—查询任务。视频去水印、音频字幕、智能字幕和字幕翻译也使用此接口

不填回调地址也可以提交,结果用查询接口获取。

环境根地址
测试https://test-star-api.aiaibase.com
正式https://star-api.aiaibase.com

路径接在根地址后面。例如测试环境提交图片去水印:

text
POST https://test-star-api.aiaibase.com/api/image_remove_watermark

请求体为 JSON,Content-Type: application/json。单次请求体不超过 1 MB。认证只使用请求头,不需要额外的 Secret:

text
Authorization: Bearer {API Key}

{API Key} 为商户密钥全文。

需要去掉视频画面水印时,使用视频去水印。需要从音轨生成字幕时,使用音频字幕。需要自动选择字幕轨、画面字幕或语音识别时,使用智能字幕。若只需翻译已经分好条的字幕,请使用字幕翻译。

所有响应都是同一结构。判断业务结果以 success 和 error.code 为准。认证失败返回 HTTP 401。其它情况 HTTP 状态都是 200。

字段类型说明
successbool受理成功、处理中、处理成功为 true;失败为 false
dataobject成功或处理中的业务数据。失败时不返回
messagestring失败说明。成功时通常不返回
errorobject失败时的错误
meta.request_idstring平台任务号。后续查询、回调都用这个值
meta.timestampstring响应时间,RFC3339,例如 2026-10-20T22:02:29.735909+08:00

错误对象:

字段类型说明
error.codeint业务错误码
error.messagestring错误说明
error.detailsarray参数错误时给出字段。每项含 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否arrayLoRA 列表,最多 20 项。每项含 name(字符串)和 strength(数字)。也可传同等内容的 JSON 字符串
bid否string业务编号,最多 200 字
title否string任务标题,最多 200 字
is_encrypt否bool是否加密输出。默认 false。不传时上游仍会收到 false。也可传字符串 true、false
notice_url否string完成后的回调地址
callback_url否stringnotice_url 的别名
notify_url否stringnotice_url 的别名。notice_url、callback_url 都为空时才使用
client_request_id条件string调用方请求号。填写回调地址时必填
request_id条件stringclient_request_id 的别名
task_id条件stringclient_request_id 的别名。前两者都为空时才使用

成功一次按次计费。参数错误、提交失败和上游失败不计费。单价见首页透明接口定价。

受理返回

HTTP 200。此时任务尚未完成。

字段类型说明
data.statusstring固定为 accepted
data.client_request_idstring调用方请求号。未传时为空字符串
meta.request_idstring平台任务号,用于查询
json
{
  "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"
  }
}

请求示例

bash
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。

bash
curl 'https://test-star-api.aiaibase.com/api/tasks/42642e01-2e33-4265-b6af-206eed371fff' \
  -H 'Authorization: Bearer {API Key}'

处理中:

json
{
  "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_idstring调用方请求号,由本服务写入
upstream_task_idstring上游任务号,由本服务写入
task_idstring上游任务号
task_typestring上游任务类型
statusint上游状态。2 为完成。0、1、3 仍在处理
image_sizestring上游返回的图片尺寸
batch_sizeint实际生成张数
bidstring业务编号
titlestring任务标题
created_atstring上游创建时间
updated_atstring上游更新时间

处理中的上游状态不会出现在成功结果里。查询未完成时 data.status 仍是 accepted。

json
{
  "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-Typeapplication/json
User-Agentstar-openapi
请求体与 GET /api/tasks/{request_id} 的响应 JSON 相同
成功条件回调地址返回 HTTP 2xx
重试非 2xx 或连接失败时,间隔 30 秒重试,最多 4 次
超时单次回调等待 10 秒

上游提交在自动重试耗尽后失败,或任务超过 24 小时仍未完成,都会记为失败并按上面的规则回调。超过 24 小时的业务码是 3601,说明「字幕任务已超过 24 小时」。

成功回调的请求体就是上一节的成功 JSON。失败回调示例:

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业务码说明常见原因
2001000资源未找到任务号不存在,或不属于当前密钥
2001001参数错误图片尺寸、提示词或 lora_list 不合法。字段在 error.details
2001004请求实体过大请求体超过 1 MB
2001101JSON格式错误请求体不是合法 JSON
4011102缺少必要的请求头没有 Authorization
2001500服务器内部错误未归类的服务端错误
2001502服务暂不可用通道未配置,或价格未配置
2003600上游处理失败任务提交或处理失败。说明可能是上游返回的具体原因
2003601上游处理超时提交超时,或任务超过 24 小时仍未完成
2004003资源冲突同一调用方请求号对应了不同请求体
2004102缺少必填项未传 img_url1 或正向提示词,或填了回调地址却没有调用方请求号
2004107地址不合法img_url1 或回调地址不是 http 或 https
4015003认证信息无效API Key 错误
2005103账户已被禁用商户已停用
2005104账户已被暂停商户已暂停
2005204资源访问被拒绝密钥没有该接口权限
4015301令牌已过期密钥已过期
4015304令牌已被撤销密钥已停用或已重置
2005705请求过于频繁超过密钥或接口的频率限制
2009001系统负载过高服务端瞬时过载,本次未受理、不计费。退避 1 到 3 秒后重试
2009902配额已超出套餐额度用尽,或触发接口用量上限
2009903余额不足预付商户现金和剩余透支不足以支付本次调用

参数错误时,error.details 给出字段和说明。认证失败示例:

json
{
  "success": false,
  "message": "认证信息无效",
  "error": {
    "code": 5003,
    "message": "认证信息无效"
  },
  "meta": {
    "request_id": "7c1a0e2d-1111-4222-8333-444455556666",
    "timestamp": "2026-10-22T04:40:00+08:00"
  }
}