---
title: "맞춤 폰트"
description: "TTF / OTF / WOFF2 폰트를 업로드하고 /v1/image-translate/translate 에서 font=\"user/<id>\" 로 사용하세요."
---

## 개요

대시보드에서 TTF, OTF 또는 WOFF2 폰트를 업로드한 뒤, `/v1/image-translate/translate` 호출에 `font=user/<id>` 를 전달하면 번역된 텍스트를 번들 기본 폰트 대신 그 폰트로 렌더링합니다.

활용 예:
- 자사몰의 브랜드 타이포그래피로 번역된 상품 페이지 통일
- 한국 웹툰을 독자가 익숙한 폰트로 렌더링
- 번들 폰트에 없는 한글·한자 혼용 폰트 사용

## 업로드

로그인 → 사이드바의 **맞춤 폰트** → TTF / OTF / WOFF2 파일을 선택 → 표시 이름 지정 → 업로드. 대시보드가 각 폰트의 `user/<id>` 참조와 렌더링 가능한 스크립트를 보여줍니다.

## 사용자 폰트로 렌더링

`/v1/image-translate/translate` 의 쿼리 파라미터로 `font=user/<id>` 를 전달합니다. body 는 동일하게 원시 이미지 바이트입니다:

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

## 글리프 커버리지 게이트

타깃 언어가 `ko` 인데 한글 글리프가 없는 폰트(예: Latin-only)를 지정하면 렌더링 작업이 시작되기 전에 거절됩니다:

```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."
  }
}
```

| 타깃 언어 | 필요한 스크립트 |
|-----------|-----------------|
| 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"
```

응답의 `userFonts` 배열에서 각 항목의 `ref` 가 `font` 파라미터에 그대로 넣을 값입니다.

## 제한

- 파일 크기: **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` | 타깃 언어의 스크립트 글리프가 폰트에 없음 |