---
title: "Custom Fonts"
description: "上传你自己的 TTF / OTF / WOFF2 字体，并在 /v1/image-translate/translate 中以 font=\"user/<id>\" 引用。"
---

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

## 概览

在控制台上传你自己的 TTF、OTF 或 WOFF2 字体，然后在任意 `/v1/image-translate/translate` 请求中传入
`font=user/<id>`，即可用你的字体而非内置默认字体渲染译文。

使用场景：
- 让翻译后的商品页面与店铺的品牌字体保持一致
- 用读者熟悉的字体渲染韩国网络漫画
- 使用内置字体集中没有的韩文/汉字混合字体

## 上传

登录后，在控制台侧边栏打开**图像翻译字体**，拖入 TTF / OTF / WOFF2 文件，填写显示名称并上传。控制台会显示每个字体的
`user/<id>` 引用以及它能渲染的文字体系。

## 使用自定义字体渲染

在 `/v1/image-translate/translate` 上以查询参数传入 `font=user/<id>`。请求体仍是原始图片字节：

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

## 字形覆盖检查

如果你请求 `target_language=ko` 却使用仅含拉丁字母的字体，请求会在任何渲染工作开始前被拒绝：

```json
{
  "success": false,
  "error": {
    "code": "FONT_GLYPH_COVERAGE",
    "message": "font does not contain glyphs for hangul (required for target_lang=ko). Upload a font that supports this script."
  }
}
```

该检查将 `target_language` 映射到所需的文字体系：

| `target_language` | 所需文字体系 |
|-----------------|-----------------|
| ko | hangul |
| ja | kana |
| zh, zh-CN, zh-TW | han |
| ru | cyrillic |
| en, fr, de, es, pt, it, vi, id, ms | latin |
| he | hebrew |
| ar | arabic |

如果你的目标语言不在列表中，则不进行检查。

## 列出你的字体

`/v1/image-translate/supported-fonts` 会将你上传的字体与内置字体一并返回。每个字体都带有一个
`glyphCoverage` 映射，表示它能渲染的文字体系——可据此决定为每种目标语言提供哪些字体：

```bash
curl https://gateway.apinoa.com/v1/image-translate/supported-fonts \
  -H "x-api-key: $APINOA_API_KEY"
```

```json
{
  "fontsByLanguage": { ... },
  "defaultByLanguage": { ... },
  "allFonts": [...],
  "userFonts": [
    {
      "id": "fxa9b21c0c8f",
      "ref": "user/fxa9b21c0c8f",
      "displayName": "Pretendard Bold (storefront)",
      "family": "Pretendard",
      "weight": 700,
      "italic": false,
      "format": "ttf",
      "glyphCoverage": { "latin": true, "hangul": true }
    }
  ]
}
```

## 限制

- 文件大小上限：每次上传 **10 MiB**
- 接受的格式：TTF、OTF、WOFF2（TTC/OTC 字体集合会被拒绝——请将各个样式分别上传）
- 每位用户的软上限为 50 个字体——如需更多，请发送邮件至 [hello@apinoa.com](mailto:hello@apinoa.com)

## 删除字体

在**控制台 > 图像翻译字体**中删除字体。仍引用该字体的请求会以 `FONT_NOT_READY` 失败，直到你将其切换为其他字体。

## 错误

以下错误由 `/v1/image-translate/translate` 在收到 `user/<id>` 字体时返回。文件本身的问题——大小、格式、
没有可用字形的字体——会在你上传时于控制台中报告。

| 代码 | 含义 |
|------|---------------|
| `FONT_NOT_FOUND` | `user/<id>` 不存在，或不是你的字体 |
| `FONT_NOT_READY` | 该字体已被删除或被拒绝 |
| `FONT_GLYPH_COVERAGE` | 该字体缺少目标语言文字体系的字形 |