Custom Fonts

개요

대시보드에서 TTF, OTF, WOFF2 폰트를 업로드한 뒤, /v1/image-translate/translate 요청에 font=user/<id>를 넘기면 번역된 텍스트를 내장 기본 폰트 대신 그 폰트로 그립니다.

활용 예:

• 번역한 상품 페이지에 스토어의 브랜드 타이포그래피를 맞춥니다
• 한국어 웹툰을 독자에게 익숙한 폰트로 그립니다
• 내장 폰트에 없는 한글/한자 혼용 폰트를 씁니다

업로드

로그인한 뒤 대시보드 사이드바에서 이미지 번역 폰트를 열고, TTF / OTF / WOFF2 파일을 끌어다 놓고, 표시 이름을 정해 업로드합니다. 대시보드에 폰트마다 user/<id> 참조값과 그릴 수 있는 문자 체계가 표시됩니다.

맞춤 폰트로 그리기

/v1/image-translate/translate에 쿼리 파라미터로 font=user/<id>를 넘깁니다. 본문은 여전히 원시 이미지 바이트입니다.

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를 요청하면, 렌더링 작업을 시작하기 전에 요청이 거부됩니다.

{
  "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를 필요한 문자 체계에 대응시킵니다.

대상 언어가 표에 없으면 확인을 하지 않습니다.

폰트 목록 보기

/v1/image-translate/supported-fonts는 업로드한 폰트를 내장 폰트와 함께 돌려줍니다. 각 폰트에는 그릴 수 있는 문자 체계를 나타내는 glyphCoverage 맵이 있습니다. 이를 보고 대상 언어마다 어떤 폰트를 제공할지 정하세요.

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

{
  "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으로 메일을 보내세요

폰트 삭제

대시보드 > 이미지 번역 폰트에서 폰트를 삭제합니다. 여전히 그 폰트를 참조하는 요청은 다른 폰트로 바꿀 때까지 FONT_NOT_READY로 실패합니다.

에러

/v1/image-translate/translate에 user/<id> 폰트를 주었을 때 돌아오는 에러입니다. 파일 자체의 문제 — 크기, 형식, 쓸 수 있는 글리프가 없는 폰트 — 는 업로드할 때 대시보드에 표시됩니다.