한글 양식 채우기 API

양식 한글 파일(.hwpx)의 서식을 그대로 둔 채 내용만 채운다. 양식의 단락을 건드리지 않고 텍스트만 제자리에서 바꾸므로, 표·글꼴·페이지 설정이 원본 그대로 유지된다.

기본 주소: https://docs.prototypebench.org

인증 — 토큰 받는 법

모든 요청에 토큰을 싣는다.

x-api-key: gdk_...

Authorization: Bearer gdk_... 도 된다.

토큰을 받는 길은 둘이다.

1. 메일로 받기 (브라우저 없이)

에이전트가 사용자의 이메일 주소를 물어 아래를 호출하면, 그 주소로 토큰이 간다. 사용자가 메일에서 토큰을 확인해 알려주면 그때부터 쓸 수 있다.

curl -X POST "https://docs.prototypebench.org/api/auth/request-token" \
  -H "Content-Type: application/json" \
  -d '{"email":"사용자@example.com"}'

응답은 주소가 등록돼 있든 아니든 같다. 어떤 주소가 등록돼 있는지 알아낼 수 없게 하기 위해서다.

{ "ok": true, "message": "해당 주소가 등록된 계정이면 토큰을 보냈습니다. 메일함을 확인하세요." }

메일이 오지 않으면 그 주소에 권한이 없는 것이다. 사용자에게 다른 주소를 묻거나, https://docs.prototypebench.org 에서 가입하도록 안내한다. 같은 주소로는 1분에 한 번만 보낸다.

2. 웹에서 발급

https://docs.prototypebench.org 에 로그인해 프로필 페이지에서 직접 만든다. 발급 직후 한 번만 보인다.

토큰에 대해 알아 둘 것

메일로 받은 토큰은 90일 뒤 만료된다. 웹에서 만든 것은 만료가 없다.
둘 다 프로필 화면에서 폐기할 수 있다.
토큰을 가진 쪽은 그 사용자의 권한으로 행동한다. 대화나 로그에 남기지 말 것.
권한은 토큰 주인에 따라 다르다. 아래 "무엇을 할 수 있나" 참고.

AI 별 연동 방법

어느 쪽이든 이 문서 주소(https://docs.prototypebench.org/api/guide)와 API 키만 있으면 된다.

Claude · Claude Code

대화에 그대로 알려주면 된다. 파일을 다루므로 Claude Code 가 가장 잘 맞는다.

export GDOC_KEY=gdk_...
curl -s https://docs.prototypebench.org/api/guide      # 이 문서
curl -X POST "https://docs.prototypebench.org/api/hwpx/inspect" -H "x-api-key: $GDOC_KEY" -F "template=@양식.hwpx"

ChatGPT (GPTs Actions)

GPT 편집 화면의 Actions 에 스키마 주소를 넣고, 인증을 API Key / Custom header x-api-key 로 설정한다.

https://docs.prototypebench.org/api/tools?format=openai

Gemini

function calling 을 쓴다면 같은 스키마를 function declarations 로 등록한다. 대화에서는 이 문서 주소를 주는 편이 간단하다.

https://docs.prototypebench.org/api/tools?format=openai

Grok

tool use 형식을 지원한다. 아래 주소의 tools 배열을 그대로 넘긴다.

https://docs.prototypebench.org/api/tools

문서·슬라이드를 웹에 게시

한글 양식 외에, AI 가 만든 HTML 을 URL 로 올릴 수도 있다. 링크를 아는 사람만 볼 수 있다.

curl -X POST "https://docs.prototypebench.org/api/pages" -H "x-api-key: $GDOC_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"제목","html":"<!DOCTYPE html>..."}'
# → { "url": "https://docs.prototypebench.org/share/AbC12xYz" }

curl -X POST "https://docs.prototypebench.org/api/presentations" -H "x-api-key: $GDOC_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"덱 제목","slides":["<div>...</div>","<div>...</div>"]}'
# → { "url": "https://docs.prototypebench.org/p/KNr7u3xj" }

내가 올린 것은 DELETE https://docs.prototypebench.org/api/pages/{id} 로 내린다.

디자인 시스템

슬라이드·문서를 만들 때 이 규칙을 프롬프트에 넣으면 서비스와 같은 디자인이 나온다.

curl "https://docs.prototypebench.org/api/design-systems"              # 내장 24종 목록
curl "https://docs.prototypebench.org/api/design-systems?id=banya-ai"  # promptBlock 을 프롬프트에 넣는다

내 브랜드 색으로 직접 만들 수도 있다. 팔레트 7색만 주면 타이포·레이아웃은 기본값으로 채워진다.

curl -X POST "https://docs.prototypebench.org/api/design-systems" -H "x-api-key: $GDOC_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"우리 브랜드","palette":{"background":"#0f1720","surface":"#16212b",
       "primary":"#3ddc97","accent":"#ffd166","text":"#e8f1f5","muted":"#8aa0ad","divider":"#24323d"}}'

무엇을 할 수 있나

기능	누구나(가입자)	관리자만
한글 양식 구조 조회·행 복제·채우기	○
문서·슬라이드 웹 게시	○
디자인 시스템 조회·생성	○
기술 블로그 게시		○

블로그는 개인 기술 블로그라 아무나 쓸 수 없다. 권한이 없는 토큰으로 부르면 403 과 함께 code: "not_admin" 이 온다. 그 경우 사용자에게 "이 계정에는 블로그 게시 권한이 없다"고 알리고 다른 기능을 쓰면 된다.

기술 블로그 게시 (관리자)

마크다운 원고를 보내면 디자인을 입히고 영문으로 번역해 블로그에 올린다.

curl -X POST "https://docs.prototypebench.org/api/blog/publish?mode=custom&chain=false&generateImages=true" \
  -H "x-api-key: $KEY" \
  -H "Content-Type: text/markdown" \
  --data-binary @원고.md

게시까지 3~5분이 걸리므로 접수만 하고 바로 답한다. jobId 로 진행을 확인한다.

curl -H "x-api-key: $KEY" "https://docs.prototypebench.org/api/blog/jobs/{jobId}"
# status: queued → running → succeeded,  result.techBlogUrl 에 주소

옵션	기본	의미
`mode`	`custom`	`custom`=원문을 한 글자도 바꾸지 않고 디자인만 입힌다 · `research`=검색으로 내용을 보강한다
`chain`	`true`	커뮤니티·LinkedIn 까지 연쇄 게시. 블로그에만 올리려면 `false`
`generateImages`	`true`	삽화와 썸네일을 만든다. 끄면 링크 미리보기에 이미지가 없다
`replaceId`	—	기존 글의 id. 같은 URL 을 유지한 채 내용을 교체한다
`callbackUrl`	—	완료 시 결과를 POST 로 받을 https 주소 (폴링 대신)

글을 고칠 때는 새로 올리지 말고 replaceId 를 쓴다. 새로 올리면 URL 이 달라져 이미 공유한 링크가 깨진다. 내리려면:

curl -X DELETE "https://docs.prototypebench.org/api/blog/posts/{id}" -H "x-api-key: $KEY"

원고가 Google Docs 에서 온 것이라면 \*\* 같은 이스케이프와 빈 표 헤더가 섞여 있을 수 있다. 그대로 보내면 글자로 보이므로 보내기 전에 정리한다.

코인

API 호출은 웹에서 쓸 때와 같은 코인을 소모한다. 가입 시 무료 코인이 지급되고, 모자라면 https://docs.prototypebench.org/pricing 에서 충전한다.

호출	코인
inspect	0 (무료)
expand-rows	1
apply	3
fill	80 (LLM 사용)
pages / presentations 게시	2 / 1

inspect 가 무료인 이유는 expand-rows 전후로 여러 번 부르는 것이 올바른 사용 흐름이기 때문이다. 잔액이 모자라면 402 와 함께 부족한 양을 알려준다. 작업이 실패하면 차감분은 자동으로 환원된다.

응답에서 잔액을 확인할 수 있다 — JSON 응답은 coinBalance, 파일 응답은 X-Coin-Balance 헤더.

반드시 지켜야 하는 계약 3가지

단락 개수가 정확히 같아야 한다. apply 에 보내는 배열 길이는 inspect 의 paragraphCount 와 일치해야 하고, 다르면 400 으로 거부된다.
표 밖의 빈 단락은 빈 문자열로 둔다. 표를 감싸는 컨테이너와 빈 줄이며, 글자를 넣으면 레이아웃이 깨진다. 반대로 표 안의 빈 칸은 채우라고 비워둔 자리다. inspect 응답이 둘을 구분해 알려준다.
평문만 넣는다. **굵게**, ##, |표| 같은 표기는 글자 그대로 보인다. 굵기·크기는 양식의 서식이 결정한다.

순서

inspect  →  (행이 모자라면 expand-rows → inspect 다시)  →  apply

1. 양식 뜯어보기

curl -X POST "https://docs.prototypebench.org/api/hwpx/inspect" \
  -H "x-api-key: $KEY" \
  -F "template=@양식.hwpx"

응답에서 볼 것:

paragraphCount — apply 에 보낼 배열 길이
contract — 위 3가지 규칙이 이 양식에 맞춰 구체적인 인덱스와 함께 들어 있다
paragraphs[].kind — text(일반) / cell(표 안) / empty(표 밖 빈 단락, 건드리지 말 것)
paragraphs[].guide — true 면 양식 작성자가 쓴 안내문이다. 그 자리에 무엇을 써야 하는지 알려주므로 안내가 요구하는 내용으로 바꾼다
paragraphs[].table/row/col — 표 안일 때 위치. 행 단위로 값을 맞출 때 쓴다
tables[] — 표별 행·열 수

text 가 제목을 여기에, 본문 자리, ○○○ 처럼 채워 넣으라는 빈칸인지, 항목, 작성일자:, 1. 사업 개요 처럼 유지해야 할 항목명인지는 호출자가 판단한다.

2. 표 행이 모자랄 때

양식의 데이터 행은 보통 2~3개로 고정인데 채울 항목은 그보다 많다.

curl -X POST "https://docs.prototypebench.org/api/hwpx/expand-rows" \
  -H "x-api-key: $KEY" \
  -F "template=@양식.hwpx" \
  -F 'expansions=[{"table":0,"row":2,"count":5}]' \
  -o 확장된_양식.hwpx

행이 늘면 단락 인덱스가 전부 바뀐다. 확장된 파일로 inspect 를 다시 호출해 새 구조를 받는다.

3. 채우기

curl -X POST "https://docs.prototypebench.org/api/hwpx/apply" \
  -H "x-api-key: $KEY" \
  -F "template=@양식.hwpx" \
  -F "paragraphs=@paragraphs.json" \
  -o 결과.hwpx

paragraphs.json 은 문자열 배열이다. 짧으면 -F 'paragraphs=["...","..."]' 로 직접 써도 된다.

응답은 HWPX 바이너리이고 헤더에 결과가 실린다: X-Hwpx-Paragraphs(양식 단락 수), X-Hwpx-Changed(바뀐 수), X-Hwpx-Protected-Empty(빈 단락에 글자를 넣어 되돌린 인덱스).

개수가 어긋나면 이렇게 답한다. 고쳐서 다시 보내면 된다.

{ "ok": false, "error": "단락 개수가 맞지 않습니다. 양식은 42개인데 40개를 보냈습니다.",
  "expected": 42, "received": 40 }

한 번에 맡기기

직접 판단하지 않고 맡기려면:

curl -X POST "https://docs.prototypebench.org/api/hwpx/fill" \
  -H "x-api-key: $KEY" \
  -F "template=@양식.hwpx" -F "markdown=@내용.md" \
  -o 결과.hwpx

호출하는 쪽이 이미 LLM 이라면 inspect + apply 가 더 정확하고 빠르다(안에서 LLM 을 한 번 더 부르지 않는다).

할 수 없는 것

본문 단락을 늘리거나 줄일 수 없다. 양식에 단락이 10개면 결과도 10개다. 항목이 많으면 한 단락 안에 이어 쓴다. 표 행만 expand-rows 로 늘릴 수 있다.
이미지를 새로 넣을 수 없다. 양식에 있던 이미지는 그대로 남는다.
서식을 바꿀 수 없다. 굵기·글꼴·색은 양식이 정한 그대로다.

한도

항목	값
양식 파일	8MB
마크다운	400KB
inspect / expand-rows / apply	1초 내 (LLM 미사용)
fill	3~10초 (LLM 1회)

도구 정의

GET https://docs.prototypebench.org/api/tools 를 부르면 OpenAI / Anthropic 형식의 도구 스키마를 그대로 받을 수 있다.

API 키는 GDoc Fixer 에 로그인한 뒤 프로필 페이지에서 발급합니다. 발급 직후 한 번만 보이니 안전한 곳에 복사해 두세요.

키 발급하러 가기

이 문서의 원본(마크다운): https://docs.prototypebench.org/api/guide
도구 스키마: https://docs.prototypebench.org/api/tools · ?format=openai