Image Translate Translate

将商品图片中的文字替换为译文，保留字重、颜色、布局和标签背景。

POST /v1/image-translate/translate

以原始字节在请求体中发送图片（不是 JSON，也不是 base64），其他所有参数放在查询字符串中。返回翻译后的 JPEG；若设置 render=false，则以 JSON 返回去除文字后的图片和每个文字区域。

请求

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

参数

请求头

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

查询字符串

参数	类型	必填	说明
`source_language`	string	是	文字的语言：`ch`、`zh`、`zh-CN`、`zh-TW`、`chinese_cht`、`ja`、`japan`、`en` 或 `auto`。`auto` 会跳过语言检查，因此所有有译文的区域都会被渲染。
`target_language`	string (2–8)	是	要翻译成的语言，使用 ISO 639 风格的代码。韩文、简体中文、日文和拉丁字母目标语言的渲染效果最佳；Supported Fonts 列出了每种语言的字体。
`font`	string		Supported Fonts 中 `allFonts` 的某个值，或已上传自定义字体的 `user/<id>`。默认 `Pretendard`。字体缺少的字形会回退到 `Pretendard` 和 `NotoSansSC`。
`font_weight`	string		`auto`、`Thin`、`Light`、`Regular`、`Medium`、`SemiBold`、`Bold`、`ExtraBold` 或 `Black`。默认 `ExtraBold`。`auto` 匹配每个区域的原始字重；其他值则应用于所有区域。
`render`	boolean		`true`（默认）返回成品图片；`false` 以 JSON 返回去除文字后的图片和各区域，供你自行绘制。

响应

`render=true`（默认）：图片

响应体为翻译后的 JPEG（Content-Type: image/jpeg），并带有以下响应头：

响应头	含义
`X-Apinoa-Request-Id`	请求的 id。联系支持时请提供。
`X-Apinoa-Regions-Count`	检测到并替换的文字区域数量。

没有文字的图片会原样返回，并带有 X-Apinoa-Regions-Count: 0。

`render=false`：以 JSON 返回区域

真实响应，仅保留第一个区域：

{
  "success": true,
  "requestId": "240d4c0348574bd7bc12f8e5d8780a87",
  "data": {
    "inpainted_base64": "/9j/4AAQSkZJRgABAQAA…",
    "regions": [
      {
        "index": 0,
        "polygon": [[83, 68], [352, 68], [352, 145], [83, 145]],
        "bbox": { "x": 83, "y": 68, "w": 269, "h": 77 },
        "text": "限时特价",
        "text_kr": "기간 한정 특가",
        "confidence": 0.999354,
        "text_color": { "r": 255, "g": 253, "b": 252 },
        "bg_color": { "r": 211, "g": 40, "b": 43 },
        "bg_std": 0.418889,
        "font_weight": "Regular",
        "is_badge": false
      }
    ],
    "regions_count": 3
  }
}

字段	类型	含义
`inpainted_base64`	string	去除源文字后的图片，base64 编码的 JPEG。
`regions[].index`	integer	区域编号，从 0 开始。
`regions[].polygon`	number[][]	四个角点，使用原图坐标。
`regions[].bbox`	object	边界框 `{x, y, w, h}`，使用原图坐标。
`regions[].text`	string	识别出的文字。
`regions[].text_kr`	string	其译文，使用 `target_language`（字段名是历史遗留）。
`regions[].confidence`	number	识别置信度，0–1。
`regions[].text_color`, `regions[].bg_color`	object	估算的文字颜色和背景颜色，RGB 格式。
`regions[].bg_std`	number	文字背后背景的不均匀程度；接近 0 表示纯色。
`regions[].font_weight`	string	检测到的字重。
`regions[].is_badge`	boolean	对于填充标签上的文字（如价签或促销标签）为 `true`。
`regions_count`	integer	找到的区域数量。

错误

状态码	代码	含义
400	`BAD_REQUEST`	请求体为空，或某个查询参数无效。
401	`UNAUTHORIZED`	缺少 `x-api-key` 请求头，或密钥无效。
402	`INSUFFICIENT_BALANCE`	余额不足以支付本次调用。重试无法解决；请充值。
413	`PAYLOAD_TOO_LARGE`	请求体超过 20 MB。请先缩小图片再发送。
413	`IMAGE_TOO_LARGE`	图片超过 8192 × 8192 px。
415	`UNSUPPORTED_MEDIA_TYPE`	`Content-Type` 不是图片类型。请以 `image/jpeg`、`image/png` 或 `image/webp` 发送原始字节。
422	`INVALID_IMAGE`	这些字节不是可读取的图片。
502	`UPSTREAM_ERROR`	处理暂时不可用。请重试；通常在一分钟内恢复。
503	`SERVICE_UNAVAILABLE`	暂时超出容量。请以退避方式重试。

所有代码都列在 Errors 中。失败的调用不计费。

价格

每次调用按价格页面上的图片翻译费率计费。

说明

限制。 图片最大 8192 × 8192 px，请求体最大 20 MB，格式为 JPEG、PNG 或 WebP。
超时。 大多数调用在 1.5–3 秒内完成；高负载时单次调用可能长达 5 分钟。请将 HTTP 客户端的超时设置为至少 300 秒，以免较慢的响应在你这一端被中断。
自行绘制。 使用 render=false 时，解码 inpainted_base64，并在每个区域的 polygon 内绘制其 text_kr，使用 text_color、bg_color 和 font_weight。
使用自己的字体。 上传字体并传入 font=user/<id>；参见 Custom Fonts。

Translate

本页内容