# 한글 양식 채우기 API

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

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

## 인증 — 토큰 받는 법

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

```
x-api-key: gdk_...
```

`Authorization: Bearer gdk_...` 도 된다.

토큰을 받는 길은 둘이다.

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

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

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

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

```json
{ "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 가 가장 잘 맞는다.

```bash
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 로 올릴 수도 있다. 링크를 아는 사람만 볼 수 있다.

```bash
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}` 로 내린다.

## 디자인 시스템

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

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

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

```bash
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"` 이 온다. 그 경우 사용자에게 "이 계정에는 블로그
게시 권한이 없다"고 알리고 다른 기능을 쓰면 된다.

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

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

```bash
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 로 진행을 확인한다.

```bash
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 이 달라져
이미 공유한 링크가 깨진다. 내리려면:

```bash
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가지

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

## 순서

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

### 1. 양식 뜯어보기

```bash
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개로 고정인데 채울 항목은 그보다 많다.

```bash
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. 채우기

```bash
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`(빈 단락에 글자를 넣어 되돌린 인덱스).

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

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

### 한 번에 맡기기

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

```bash
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 형식의 도구 스키마를 그대로 받을 수 있다.