---
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` | 폰트에 대상 언어의 문자 체계 글리프가 없습니다 |