Notion 마크다운 API로 LLM 토큰 비용 20배 절약하는 방법

이 글은 누구를 위한 건가요?

• 노션 자동화를 시도해본 분 — Make, Zapier, n8n 등으로 노션에 데이터를 넣어본 경험이 있다면

• AI로 노션 콘텐츠를 생성하고 싶은 분 — ChatGPT, Claude 등으로 글을 쓰고 노션에 자동 발행하고 싶다면

• Notion API를 직접 다루는 개발자 — LLM 토큰 비용을 최적화하고 싶다면

블록 API, 왜 비용이 많이 들까

{
  "type": "paragraph",
  "paragraph": {
    "rich_text": [
      {"type": "text", "text": {"content": ""}, "annotations": {"bold": false, "italic": false, "strikethrough": false, "underline": false, "code": false, "color": "default"}},
      {"type": "text", "text": {"content": "마크다운"}, "annotations": {"bold": true}},
      {"type": "text", "text": {"content": "으로 작성된 본문입니다."}}
    ]
  }
}

마크다운 API: 게임 체인저

**마크다운**으로 작성된 본문입니다.

실제 curl로 따라해보기

페이지 본문 읽기

curl 'https://api.notion.com/v1/pages/{페이지ID}/markdown' \
  -H 'Authorization: Bearer ntn_여러분의토큰' \
  -H 'Notion-Version: 2026-03-11'

## 섹션 제목
**마크다운**으로 작성된 본문입니다.
- 항목 1
- 항목 2

페이지 본문 쓰기

curl -X PATCH 'https://api.notion.com/v1/pages/{페이지ID}/markdown' \
  -H 'Authorization: Bearer ntn_여러분의토큰' \
  -H 'Notion-Version: 2026-03-11' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "replace_content",
    "replace_content": {
      "new_str": "## 새 섹션\n\n마크다운으로 작성한 본문입니다.\n\n- 항목 1\n- 항목 2"
    }
  }'

실제 토큰 비교

쓰기 (AI → Notion)

읽기 (Notion → AI)

특수 블록도 누락 없이 보존된다

어디에 활용할 수 있을까?

LLM 연동 자동화 실전 예시

// 블록 API: 15줄 이상
await notion.appendBlocks(pageId, [
  { type: 'callout', callout: { icon: { type: 'emoji', emoji: '📌' },
    rich_text: [{ type: 'text', text: { content: '안내 메시지' } }] } },
  { type: 'heading_2', heading_2: {
    rich_text: [{ type: 'text', text: { content: '섹션 제목' } }] } },
  // ... 계속
]);

// 마크다운 API: 마크다운 문자열 하나
await notion.updatePageMarkdown(pageId, \`
<callout icon="📌">안내 메시지</callout>

## 섹션 제목

본문 내용

- 항목 1
- 항목 2
- 항목 3\`);

마크다운 우선 전략 정리

직접 써보기: 노션 자동화 스킬 오픈소스

• 마크다운 API 기반 읽기/쓰기 (확장 태그 지원)

• DB/DS ID 자동 변환

• 벌크 upsert (동시성 15, queryAll 캐시)

• 파일 업로드, 코멘트, 페이지 이동

irm https://raw.githubusercontent.com/1000ssam/skills-for-teachers/main/skills/notion-workspace/install.ps1 | iex