自定义水印图片下载 API 接口文档

传入一组 OSS 图片 URL 与自定义水印参数（文字内容、颜色、位置、字号），同步返回带水印的签名下载 URL，顺序与入参严格一致。

POST/image/v2/download/watermarkapplication/json

请求体

urlsarray[string]必填

图片 OSS URL 列表，1~50 个。必须为当前团队 OSS Bucket 上的图片，不支持外部 CDN 或第三方 URL

textstring必填

水印文字内容，1~35 个字符（含中文）

colorstring可选默认#ffffff

水印文字颜色，十六进制 6 位格式（带 #），如 #ffffff。不支持 3 位简写或无 #

positionstring可选默认br

水印位置。tl（左上）/ tr（右上）/ center（居中）/ bl（左下）/ br（右下）

sizenumber可选默认40

水印文字字号，范围 10~200

参数使用建议

color 不传时默认 #ffffff（白色），position 不传时默认 br（右下），size 不传时默认 40。
color 仅支持 #ffffff 标准 6 位格式，传入 #fff（3 位）或 ffffff（无 #）会报参数格式错误。
urls 单次最多 50 个，数组顺序与响应 data[] 中的下载 URL 顺序一一对应。
urls 中的图片必须属于当前团队的 OSS Bucket，任一 URL 归属校验不通过则整批拒绝。

请求示例

示例 1：全参数

JSON

{
  "urls": [
    "https://oss-cn-shanghai.aliyuncs.com/bucket/product-001.png",
    "https://oss-cn-shanghai.aliyuncs.com/bucket/product-002.png"
  ],
  "text": "品牌专供",
  "color": "#ffffff",
  "position": "br",
  "size": 40
}

示例 2：最小参数（仅必填项，其余使用默认值）

JSON

{
  "urls": [
    "https://oss-cn-shanghai.aliyuncs.com/bucket/sample.png"
  ],
  "text": "样品图"
}

响应参数

traceIdstring

链路 ID

codestring

状态码，200 为成功，其他为失败

msgstring

成功 / 错误描述

msgKeystring

错误描述编码，状态码不等于 200 时存在

dataarray[string]

数组元素

[]string

带水印与 OSS 签名的临时下载 URL，顺序与入参 urls[] 一一对应

响应示例

JSON

{
  "traceId": "f6e0fe4f360f78445c2c5d52f2414dea",
  "code": "200",
  "msg": "成功",
  "data": [
    "https://oss-cn-shanghai.aliyuncs.com/bucket/product-001.png?Expires=1721800000&OSSAccessKeyId=xxx&Signature=yyy&x-oss-process=%2Fwatermark%2Ctext_5rWL6K-V%2Cg_se%2Cx_10%2Cy_10%2Csize_40%2Ccolor_FFFFFF%2Ct_100",
    "https://oss-cn-shanghai.aliyuncs.com/bucket/product-002.png?Expires=1721800000&OSSAccessKeyId=xxx&Signature=zzz&x-oss-process=%2Fwatermark%2Ctext_5rWL6K-V%2Cg_se%2Cx_10%2Cy_10%2Csize_40%2Ccolor_FFFFFF%2Ct_100"
  ]
}

⚠️ 返回的 URL 为临时签名链接，有效期与 OSS 策略一致，过期后需重新调用接口获取。

常见问题

报参数错误：优先检查 text 是否为空或超过 35 字符，urls 是否为空或超过 50 个，color 是否符合 #ffffff 标准 6 位格式。
报 URL 解析失败：urls 中某条 URL 不属于当前团队 OSS Bucket，或格式无法提取 OSS key，请确认图片地址正确且归属当前团队。
报图片归属校验失败：OSS key 对应的文件不属于当前团队，请确认图片是通过本团队的应用上传。
水印中文乱码：内部使用 UTF-8 编码 + Base64（URL-safe 无填充），请确认调用方正确解析 UTF-8。
URL 签名过期：返回的 downloadUrl 为临时签名链接，有效期过后需重新调用接口获取新链接，请勿长期缓存。