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

## 接口

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

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

- **输入语言** — 中文(简体或繁体)、日文、英文。传 `auto` 可跳过脚本过滤。
- **输出语言** — 任意 ISO-639 形式的代码;视觉效果取决于所选 `font` 是否覆盖该语言的字符。实时可用的字体与源语言代码请见 [`/supported-fonts`](./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`](./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 + 区域信息

```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)

```bash
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)

```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 分钟上限仅在持续突发流量下才有意义。如果您经常接近这一上限,请降低并发或联系支持团队。

## 价格

每次调用按[价格页面](/pricing)上的 image-translate 单价从您的余额中扣费。