---
title: "自定义字体"
description: "上传 TTF / OTF / WOFF2 字体,在 /v1/image-translate/translate 中通过 font=\"user/<id>\" 引用。"
---

## 概览

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

适用场景:品牌字体一致性、韩国 webtoon 自渲染、内置字体未覆盖的韩中混排。

## 上传

登录控制台 → **自定义字体** 菜单 → 选择 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
```

## 字形覆盖门控

如果目标语言要求某种脚本而字体不支持,请求会在渲染开始前被拒绝,返回 `FONT_GLYPH_COVERAGE`:

| 目标语言 | 需要的脚本 |
|---------|-----------|
| 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` 会同时返回内置字体和你上传的字体,其中 `userFonts` 数组列出你的所有字体及其 `ref`(可直接放进 `font` 参数)。每个字体都带有 `glyphCoverage` 映射,标明它能渲染的脚本 —— 可据此决定为每种目标语言提供哪些字体。

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

## 限制

- 文件 ≤ 10 MiB
- 格式:TTF / OTF / WOFF2(TTC/OTC 集合不支持,请拆分后上传)
- 单用户上限 50 个(更多请联系销售)

## 删除

在 **控制台 > 自定义字体** 中删除字体。仍引用该字体的请求会返回 `FONT_NOT_READY`,直到你改用其他字体。

## 错误代码

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

| 代码 | 触发条件 |
|------|---------|
| `FONT_NOT_FOUND` | `user/<id>` 不存在或不是你的字体 |
| `FONT_NOT_READY` | 字体已被删除或被拒绝 |
| `FONT_GLYPH_COVERAGE` | 字体缺少目标语言所需脚本的字形 |