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

> Every apinoa docs page as markdown: https://apinoa.com/llms.txt (all in one file: https://apinoa.com/llms-full.txt; this API family in one file: https://apinoa.com/docs/image-translate/llms.txt)

```http
POST /v1/image-translate/translate
```

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

## 请求

```bash tab="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
```

```js tab="JavaScript"
import { readFile, writeFile } from "node:fs/promises";

const params = new URLSearchParams({ source_language: "zh-CN", target_language: "ko" });
const res = await fetch(`https://gateway.apinoa.com/v1/image-translate/translate?${params}`, {
  method: "POST",
  headers: { "x-api-key": process.env.APINOA_API_KEY, "Content-Type": "image/jpeg" },
  body: await readFile("product.jpg"),
});
await writeFile("translated.jpg", Buffer.from(await res.arrayBuffer()));
```

```python tab="Python"
import os

import requests

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

res = requests.post(
    "https://gateway.apinoa.com/v1/image-translate/translate",
    params={"source_language": "zh-CN", "target_language": "ko"},
    headers={"x-api-key": os.environ["APINOA_API_KEY"], "Content-Type": "image/jpeg"},
    data=image,
    timeout=300,
)
res.raise_for_status()
with open("translated.jpg", "wb") as f:
    f.write(res.content)
```

## 参数

**请求头**

| 请求头 | 必填 | 说明 |
|---|---|---|
| `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](/docs/api-reference/image-translate/supported-fonts) 列出了每种语言的字体。 |
| `font` | string | | [Supported Fonts](/docs/api-reference/image-translate/supported-fonts) 中 `allFonts` 的某个值，或已上传[自定义字体](/docs/api-reference/image-translate/custom-fonts)的 `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 返回区域

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

```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](/docs/errors) 中。失败的调用不计费。

## 价格

每次调用按[价格页面](/pricing)上的图片翻译费率计费。

## 说明

- **限制。** 图片最大 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](/docs/api-reference/image-translate/custom-fonts)。