에셋 · PDFgine

에셋 업로드

로고, 서명, 글꼴은 한 번 업로드한 후 ID로 참조합니다. 요청은 multipart 형식이며 파일은 file 필드에 넣고 altText는 선택 사항입니다.

요청

curl -X POST https://api.pdfgine.com/api/v1/assets \
  -H "X-PDFgine-Key: $PDFGINE_KEY" \
  -F "file=@logo.png" \
  -F "altText=회사 로고"

HTTP 201

{
  "assetId": "ast_985f87e2b22d486db2d6d8bacd29288e",
  "fileName": "logo.png",
  "contentType": "image/png",
  "length": 20184,
  "altText": "회사 로고",
  "createdAt": "2026-09-26T15:29:44.8420041+00:00",
  "expiresAt": null,
  "fontEmbedding": null
}

유형은 전송한 Content-Type이 아니라 파일의 첫 바이트에서 판별합니다. 실제 내용이 PDF인 .png는 거부됩니다. PNG, JPEG, WebP, TTF, OTF를 지원하며 파일당 최대 10 MB입니다.

문서에서 사용

템플릿이 이미지를 요구하는 곳에 ID를 보내세요. 같은 필드에 data: URI도 사용할 수 있지만 업로드한 에셋은 전송량이 더 작고 재사용할 수 있습니다.

요청

curl -X POST https://api.pdfgine.com/api/v1/render \
  -H "X-PDFgine-Key: $PDFGINE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "templateCode": "invoice",
        "format": "pdf",
        "data": { "logo": "ast_985f87e2b22d486db2d6d8bacd29288e" }
      }'

임시 에셋, 목록 조회 및 삭제

문서 한 개에만 필요한 이미지는 직접 정리할 필요가 없습니다. expiresInMinutes를 1~10080(7일)로 지정하면 에셋이 자동으로 삭제됩니다.

요청

curl -X POST https://api.pdfgine.com/api/v1/assets \
  -H "X-PDFgine-Key: $PDFGINE_KEY" \
  -F "file=@signature.png" \
  -F "expiresInMinutes=60"

# 목록 조회, 에셋 하나의 콘텐츠 조회 및 삭제
curl https://api.pdfgine.com/api/v1/assets -H "X-PDFgine-Key: $PDFGINE_KEY"
curl https://api.pdfgine.com/api/v1/assets/ast_985f87e2b22d486db2d6d8bacd29288e/content \
  -H "X-PDFgine-Key: $PDFGINE_KEY" -o logo.png
curl -X DELETE https://api.pdfgine.com/api/v1/assets/ast_985f87e2b22d486db2d6d8bacd29288e \
  -H "X-PDFgine-Key: $PDFGINE_KEY"

글꼴 및 포함 허용 범위

글꼴 파일은 자체 fsType 비트로 문서에서 허용되는 사용 방법을 지정합니다. PDFgine은 업로드 시 이를 읽고 fontEmbedding으로 응답하므로 문서를 연 뒤가 아닌 생성 전에 포함 가능 여부를 알 수 있습니다.

`fontEmbedding`	문서에서 허용되는 사용
`installable`	제한 없음. PDF와 Word 모두에 포함됩니다.
`editable`	PDF와 Word 모두에 포함됩니다.
`preview-print`	PDF에는 포함됩니다. Word 문서는 편집할 수 있으므로 Word에는 포함되지 않으며 Word가 글꼴을 대체합니다.
`restricted`	어디에도 포함되지 않습니다. 문서는 계속 생성되며 대신 열람자 기기의 글꼴이 사용됩니다.
`bitmap-only`	비트맵 포함만 허용되지만 문서에서 사용할 수 없으므로 포함되지 않습니다.
`unstated`	파일에 권한이 지정되지 않았습니다. OpenType 사양에 따라 포함 가능한 것으로 처리합니다.

WOFF와 WOFF2는 업로드 시 거부됩니다. Word 문서에 포함할 수 없어 같은 템플릿이 PDF에서는 올바르게, Word에서는 잘못 표시될 수 있으며 문서를 보낸 뒤에야 차이를 알아차릴 수 있기 때문입니다.

기본 제공 글꼴

이 글꼴 모음은 제품에 포함됩니다. style.fontFamily 및 page.defaultFont에 이름을 지정하여 사용하세요. PDF, Word, 편집기에서 같은 서체를 사용합니다. 해당 글꼴에 없는 굵기를 지정해도 거부하지 않고 가장 가까운 서체로 출력합니다.

글꼴 모음	그룹	굵기	지원 문자 체계
`Inter`	`sans`	100, 200, 300, 400, 500, 600, 700, 800, 900	latin, latin-ext, greek, cyrillic, vietnamese
`Roboto`	`sans`	100, 200, 300, 400, 500, 600, 700, 800, 900	latin, latin-ext, greek, cyrillic, vietnamese
`Montserrat`	`sans`	100, 200, 300, 400, 500, 600, 700, 800, 900	latin, latin-ext, cyrillic, vietnamese
`Poppins`	`sans`	100, 200, 300, 400, 500, 600, 700, 800, 900	latin
`DM Sans`	`sans`	100, 200, 300, 400, 500, 600, 700, 800, 900	latin
`Nunito`	`sans`	200, 300, 400, 500, 600, 700, 800, 900	latin, cyrillic, vietnamese
`Manrope`	`sans`	200, 300, 400, 500, 600, 700, 800	latin, greek, cyrillic, vietnamese
`Noto Sans`	`sans`	100, 200, 300, 400, 500, 600, 700, 800, 900	latin, latin-ext, greek, cyrillic, vietnamese
`Plus Jakarta Sans`	`sans`	200, 300, 400, 500, 600, 700, 800	latin, vietnamese
`Work Sans`	`sans`	100, 200, 300, 400, 500, 600, 700, 800, 900	latin, latin-ext, vietnamese
`Roboto Condensed`	`condensed`	100, 200, 300, 400, 500, 600, 700, 800, 900	latin, latin-ext, greek, cyrillic, vietnamese
`Oswald`	`condensed`	200, 300, 400, 500, 600, 700	latin, latin-ext, cyrillic, vietnamese
`Noto Serif`	`serif`	100, 200, 300, 400, 500, 600, 700, 800, 900	latin, latin-ext, greek, cyrillic, vietnamese
`EB Garamond`	`serif`	400, 500, 600, 700, 800	latin, latin-ext, greek, cyrillic, vietnamese
`Newsreader`	`serif`	200, 300, 400, 500, 600, 700, 800	latin, vietnamese
`Literata`	`serif`	200, 300, 400, 500, 600, 700, 800, 900	latin, greek, cyrillic, vietnamese
`Tinos`	`serif`	400, 700	latin, latin-ext, greek, cyrillic, vietnamese
`Rokkitt`	`serif`	100, 200, 300, 400, 500, 600, 700, 800, 900	latin, vietnamese
`Inconsolata`	`mono`	200, 300, 400, 500, 600, 700, 800, 900	latin, vietnamese
`Noto Sans Mono`	`mono`	100, 200, 300, 400, 500, 600, 700, 800, 900	latin, latin-ext, greek, cyrillic, vietnamese
`Arial`	`system`	400, 700
`Georgia`	`system`	400, 700

업로드가 거부되는 경우

모든 거부는 400 응답이며 errors.file에 사유가 포함됩니다. 이 문장에 대처 방법이 들어 있으므로 업로드하는 사용자에게 그대로 표시하세요.

HTTP 400

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "file": ["Word 출력에서 사용할 수 있도록 TTF 또는 OTF 글꼴을 업로드하세요. WOFF 및 WOFF2 파일은 Word 문서에 포함할 수 없습니다."]
  },
  "correlationId": "505aac87e234a7b4669e6203ac7ffcd5"
}

오류 →

자주 발생하는 문제

유형은 파일 이름이 아닌 첫 바이트에서 판별합니다. PDF의 이름을 .png로 바꾸어도 이미지가 되지 않으며 업로드는 거부됩니다.
WOFF와 WOFF2는 의도적으로 거부됩니다. Word에 포함할 수 없어 같은 템플릿이 PDF에서는 올바르게, Word에서는 잘못 표시되므로 TTF 또는 OTF를 업로드하세요.
업로드 응답에는 fontEmbedding이 포함됩니다. 무시하면 문서를 보낸 뒤에야 글꼴이 대체되었음을 알게 됩니다.
data: URI는 모든 요청에 함께 전송됩니다. 모든 문서에 쓰는 로고라면 한 번 업로드하고 ID를 보내세요.
문서 하나에 필요한 이미지는 직접 정리할 필요가 없습니다. expiresInMinutes를 지정하면 자동으로 삭제됩니다.