图片翻译

替换商品图片中的文字,同时保留原始视觉风格 — 字重、颜色、版式、徽章背景。

接口

POST /v1/image-translate/translate

将商品图片以原始字节(raw binary) 发送,返回原文已抹除并替换为目标语言的同一图片。字体、字重和渲染模式由调用方通过查询字符串控制。

输入语言 — 中文(简体或繁体)、日文、英文。传 auto 可跳过脚本过滤。
输出语言 — 任意 ISO-639 形式的代码;视觉效果取决于所选 font 是否覆盖该语言的字符。实时可用的字体与源语言代码请见 /supported-fonts。

请求格式

接口仅接受 HTTP body 中的原始图片字节。不再接受 JSON + base64。

头部	必填	说明
`Content-Type`	是	`image/jpeg`、`image/png`、`image/webp` 或 `application/octet-stream`
`x-api-key`	是	API 密钥

其余参数全部通过查询字符串传递:

参数	类型	必填	默认	说明
`source_language`	string	是	—	取自 `ch`、`zh`、`zh-CN`、`zh-TW`、`chinese_cht`、`ja`、`japan`、`en`、`auto`。
`target_language`	string (2–8)	是	—	ISO-639 形式的目标语言代码。
`font`	string	否	`Pretendard`	取自 `/supported-fonts` 的 `allFonts`。含非 ASCII 字符时请 URL 编码。默认为 `Pretendard` —— 现代韩文可变粗细无衬线字体,完整覆盖谚文、CJK 标点(×、（）、《》、· 等)以及 Latin Extended-A。渲染器内置 fallback chain:所选字体缺失的字形(如汉字)会自动按 `Pretendard` → `NotoSansSC` 顺序补齐。
`font_weight`	string	否	`ExtraBold`	取自 `auto`、`Thin`、`Light`、`Regular`、`Medium`、`SemiBold`、`Bold`、`ExtraBold`、`Black`。
`render`	boolean	否	`true`	`true` 返回最终翻译图(二进制)。`false` 返回已抹除文字的图与各区域元数据(JSON)。

响应

`render=true`(默认)— 二进制图片

render=true 时响应 body 是渲染后的 JPEG 字节,Content-Type: image/jpeg。元数据通过响应头返回:

响应头	说明
`X-Apinoa-Request-Id`	请求 ID(故障申报时引用)
`X-Apinoa-Regions-Count`	检测并替换的文字区域数

`render=false` — JSON + 区域信息

{
  "success": true,
  "requestId": "550e8400e29b41d4a716446655440000",
  "data": {
    "inpainted_base64": "<已抹除文字图的 base64>",
    "regions": [
      {
        "polygon": [[10, 20], [210, 20], [210, 60], [10, 60]],
        "bbox": { "x": 10, "y": 20, "w": 200, "h": 40 },
        "text": "免费送货",
        "text_kr": "무료 배송",
        "confidence": 0.98,
        "font_weight": "Bold",
        "is_badge": true
      }
    ],
    "regions_count": 5
  }
}

示例

基础翻译 (cURL)

curl -X POST "https://gateway.apinoa.com/v1/image-translate/translate?source_language=zh-CN&target_language=ko" \
  -H "x-api-key: $APINOA_API_KEY" \
  -H "Content-Type: image/jpeg" \
  --data-binary @product.jpg \
  -o translated.jpg

指定字体 (Python)

import requests

with open("product.jpg", "rb") as f:
    img_bytes = f.read()

r = requests.post(
    "https://gateway.apinoa.com/v1/image-translate/translate",
    headers={"x-api-key": "YOUR_API_KEY", "Content-Type": "image/jpeg"},
    params={
        "source_language": "zh-CN",
        "target_language": "ko",
        "font": "Pretendard",
        "font_weight": "Bold",
    },
    data=img_bytes,
    timeout=300,  # 服务端超时为 5 分钟,详见下方"超时"小节
)
r.raise_for_status()
with open("translated.jpg", "wb") as f:
    f.write(r.content)
print("regions:", r.headers.get("X-Apinoa-Regions-Count"))

限制

项目	值
最大尺寸	8192 × 8192 px
最大请求体	20 MB
图片格式	JPEG、PNG、WebP

错误

代码	HTTP	触发条件
`BAD_REQUEST`	400	空 body 或参数无效
`UNAUTHORIZED`	401	API key 缺失或无效
`UNSUPPORTED_MEDIA_TYPE`	415	`Content-Type` 不是二进制图片类型
`PAYLOAD_TOO_LARGE`	413	body > 20 MB
`INSUFFICIENT_BALANCE`	402	余额不足以支付本次调用,请在控制台 > 余额中充值;重试无法解决
`UPSTREAM_ERROR`	502	后端临时不可用

超时

高负载时,单个请求最长可能需要 5 分钟(300 秒)。请将 HTTP 客户端超时设置为至少 300 秒,以免较慢的响应在本地被提前中断。

延迟	一般情况	最坏情况
正常负载	1.5 – 3 s	< 10 s
高负载	5 – 30 s	5 分钟

绝大多数请求在数秒内完成。5 分钟上限仅在持续突发流量下才有意义。如果您经常接近这一上限,请降低并发或联系支持团队。

价格

每次调用按价格页面上的 image-translate 单价从您的余额中扣费。

本页内容