---
title: "문서 변환 API"
description: "문서 변환 API는 하나의 POST /v1/convert/{name} 호출로 파일, URL 또는 HTML을 받아 Markdown을 반환하는 HTTPS API입니다."
url: https://markitdown.ai/developers
updated: 2026-09-26
source: markitdown.ai
---

# 문서 변환 API

> 문서 변환 API는 하나의 POST /v1/convert/{name} 호출로 파일, URL 또는 HTML을 받아 Markdown을 반환하는 HTTPS API입니다.

익명 체험은 최대 10MB, 25페이지 파일을 허용하며, IP당 시간당 3회, 하루 10회 변환할 수 있습니다. Lite는 월 $20부터 시작하며 최대 100MB 파일을 지원합니다. Pro는 월 $50, Max는 월 $100입니다.

- 파일, URL, 인라인 텍스트마다 한 번의 POST /v1/convert/{name} 호출
- 60초 안에 응답으로 Markdown을 받거나, 폴링할 변환 작업을 받습니다
- 웹 앱과 동일한 변환 엔진

## 문서 변환 API 작동 방식

키에서 Markdown까지 세 단계. 각 호출은 최대 60초를 기다렸다가 결과로 응답하며, 더 오래 걸리거나 여러 파일을 담은 요청은 연결을 열어 두는 대신 202와 폴링할 변환 작업을 반환합니다.

**요청**

```bash
# Upload a local file; Markdown comes back in the same response
curl -X POST https://api.markitdown.ai/v1/convert/pdf \
  -H "x-api-key: mdai_…" \
  -F file=@nist-cswp-29-csf-2.0.pdf

# Or convert a public web page
curl -X POST https://api.markitdown.ai/v1/convert/url \
  -H "x-api-key: mdai_…" \
  -H "content-type: application/json" \
  -d '{"url":"https://markitdown.ai/blog/why-pdfs-break-llms"}'

# Took longer than the wait window? Long-poll the conversion
curl "https://api.markitdown.ai/v1/conversions/<id>?wait=100" \
  -H "x-api-key: mdai_…"
```

1. API 키 만들기 — 설정 → 개발자에서 키를 만들고(활성 구독 필요) x-api-key 헤더로 보내세요.
2. POST /v1/convert/{name} — 파일, 공개 URL 또는 인라인 텍스트를 해당 형식의 엔드포인트로 보내세요. 호출당 입력 유형은 하나입니다.
3. Markdown 사용 — 응답의 출력을 읽거나, 202를 받았다면 /v1/conversions/{id}를 기다리세요.

## 응답과 웹훅

아래 응답은 검증된 DOCX 파서 출력으로 API 계약을 보여 줍니다. 변환 식별자는 자리 표시자입니다. 끝난 변환은 소모한 크레딧과 함께 Markdown을 반환합니다. 202는 변환을 가리키는 Location 헤더를 담습니다. ?wait=로 폴링하거나, 이벤트를 스트리밍하거나, 완료 시 웹훅이 알려 주게 하세요.

**응답 또는 conversion.completed 웹훅**

```text
{
  "id": "cnv_3f7c…",
  "object": "conversion",
  "name": "word",
  "status": "completed",
  "files": [ { "outputs": [ { "format": "markdown", "content": "## Review Findings\n\nRisk ratings follow the standard High / Medium / Low scale defined in the vendor risk management policy.\n\n| Vendor | Risk Rating | Finding | Owner |\n| --- | --- | --- | --- |\n| CloudScan OCR | Medium | No documented data retention limit on uploaded scans | Security |\n| PayBridge | Low | SOC 2 Type II renewed; no open items | Finance |\n| LingoTrans API | High | Sub-processor list not disclosed on request | Legal |\n| ArchiveNow Storage | Medium | Encryption at rest confirmed; key rotation overdue | Security |\n" } ] } ],
  "usage": { "credits_charged": 1 }
}

POST https://your-app.example.com/webhooks
{
  "type": "conversion.completed",
  "data": { "id": "cnv_3f7c…", "object": "conversion", "status": "completed" }
}
```

`conversion.completed`와 `conversion.failed`를 구독하면 오래 걸리거나 여러 파일을 담은 변환이 끝나는 즉시 폴링 대신 반응할 수 있습니다. 전송은 Standard Webhooks 헤더로 서명됩니다.

## 문서 파싱 API와 Markdown 변환 API

팀은 파일에서 구조를 추출해야 할 때 문서 파싱 API를 찾고, 출력이 프롬프트나 저장소로 들어가야 할 때 Markdown 변환 API를 찾습니다. 두 표현 모두 이 서비스를 가리킵니다. [PDF를 Markdown으로 api](/pdf-to-markdown), [URL을 Markdown으로 api](/url-to-markdown) 같은 형식별 페이지는 그 변환기로 가는 앵커이며, 같은 `/v1/convert/{name}` 엔드포인트를 씁니다.

- 변환 엔드포인트 — 형식마다 하나인 POST /v1/convert/{name} — 파일, URL 또는 텍스트를 받아 Markdown, 텍스트, HTML 또는 페이지별 출력을 반환합니다.
- API 키 — x-api-key 헤더로 보내는 계정별 키를 써서 어떤 서버나 스크립트에도 변환을 넣을 수 있습니다.
- 여러 파일과 웹훅 — 한 번의 변환 호출에 여러 파일을 보내고 하나의 변환 작업을 받으세요. 웹훅이 conversion.completed 또는 conversion.failed마다 알려 줍니다.
- Markdown Render — POST /v1/convert/markdown/html 또는 /markdown/text는 크레딧 비용 없이 Markdown을 다시 HTML이나 일반 텍스트로 변환합니다.

## 팀이 통합하는 지점

- RAG 수집 — 청킹하고 임베딩하기 전에 수집 작업 안에서 문서를 변환하세요.
- AI 에이전트 — 에이전트가 처리 중간에 임의의 파일을 깔끔한 텍스트로 변환하게 하세요.
- 콘텐츠 파이프라인 — Markdown을 CMS, 문서 사이트, 지식 베이스에 자동으로 넣으세요.
- 사내 도구 — 이미 쓰는 사내 제품과 도구에 문서 변환을 더하세요.

## 인증, 사용량, 한도

- API 키는 계정에 속하고 /v1에서만 동작하며 x-api-key 헤더로 전송됩니다. 계정에 활성 Lite, Pro 또는 Max 구독이 필요합니다
- 사용량은 웹 앱과 같은 크레딧을 소모합니다. 일반 페이지와 OCR 페이지는 페이지당 1크레딧입니다
- 요금제별 요청 한도는 Lite 분당 20회, Pro 분당 40회, Max 분당 60회입니다
- 모든 POST /v1/convert/{name} 호출에 Idempotency-Key를 붙여 재시도가 두 번 청구되지 않게 하세요
- 모든 v1 엔드포인트와 요청·응답 필드는 생성된 [API 레퍼런스](/docs/api)에 문서화되어 있습니다. 실패는 해당 [오류 코드 페이지](/docs/errors)로 연결되는 `type` URI와 함께 problem+json을 사용합니다

## 완료 처리

문서 변환 API 클라이언트에서 인라인 완료와 비동기 처리를 모두 다루세요. 성공한 제출은 이미 완료된 결과를 반환할 수 있지만, HTTP 202는 작업이 응답 이후에 계속된다는 뜻입니다. 변환 식별자를 보관하고 출력을 읽기 전에 문서화된 Location 또는 변환 상태 엔드포인트를 사용하세요. HTTP 요청이 성공했다는 이유만으로 첫 출력이라고 가정한 결과를 곧바로 색인하지 마세요. 완료된 변환에도 파일 수준 실패가 들어 있을 수 있으니 여러 원본을 담은 요청에서는 각 파일을 살펴보세요. 반환된 각 결과를 애플리케이션이 보낸 원본과 연결할 충분한 맥락을 저장하세요. 그래야 느린 변환이나 부분 실패가 시스템 안에서 조용히 빈 문서가 되는 일을 막을 수 있습니다.

## 요청 한도와 요금제 한도

문서 변환 API는 요청과 계정 모두에 한도를 적용합니다. 멀티파트 요청은 파일을 최대 100개까지 담을 수 있고 전체 한도는 100MB입니다. URL 요청은 원본을 최대 20개까지 받습니다. 구독은 크레딧, 저장 공간, 파일별 한도, 동시 실행을 따로 제어합니다. Pro 요금제에 맞는 파일이 구독상으로는 허용되면서 단일 멀티파트 요청에는 너무 클 수 있습니다. 그런 경우 문서화된 청크 업로드 흐름을 사용하세요. 더 높은 요금제가 전송 한도를 없앤다고 가정해 거부된 요청을 우회하지 마세요. 오류를 읽고 원본 크기에 맞는 입력 방법을 사용하세요.

## 원본 맥락 보존

자체 원본 식별자를 변환 식별자 옆에 저장해 결과를 그것을 보낸 작업까지 추적할 수 있게 하세요. API의 metadata 필드는 호출자가 제공한 데이터를 운반할 뿐, 페이지 제목, 작성자, 게시 날짜를 추출하겠다는 약속이 아닙니다. 애플리케이션에 그런 데이터가 필요하면 알맞은 별도 단계에서 수집하고 검증하세요. 텍스트를 읽기 전에 출력이 인라인으로 반환되는지 참조된 결과물로 반환되는지 확인하고, 흐름에 감사 추적이 필요하면 원본 문서를 보관하세요. 문서 변환 API는 다음 단계를 위해 내용을 준비할 뿐이며, 그 내용을 원본과 연결하고 얼마나 오래 보관할지 결정하는 것은 여전히 애플리케이션의 몫입니다.

## 출시 전 테스트

문서 변환 API를 프로덕션 흐름에 통합하기 전에 정상적인 작은 파일 하나 이상을 시험하세요. 비동기 완료가 필요한 입력, 지원하지 않거나 손상된 파일, 여러 원본과 뒤섞인 결과가 있는 요청, 클라이언트가 한도 오류로 다뤄야 하는 응답을 포함하세요. 부분 실패 후 자체 재시도 로직이 정상 파일을 다시 보내지 않는지 확인하세요. API 자격 증명은 서버에 저장하고 브라우저 코드나 공개 예제에 넣지 마세요. 검색이나 이후 모델 동작을 평가하기 전에 대표적인 원본 유형의 실제 Markdown을 검토하세요. 전송 오류를 잘 처리하는 클라이언트도 결과 문서가 유용한지 보여 주려면 내용 수준 점검이 필요합니다.

## FAQ

### 문서 변환 API에는 어떻게 인증하나요?

계정에서 API 키를 만들고 `x-api-key` 헤더로 보내세요. 키는 계정 범위로 제한됩니다.

### 실제 변환 흐름은 어떻게 되나요?

파일, 공개 URL 또는 텍스트와 함께 POST /v1/convert/{name}를 보내세요. 문서가 대기 창 안에 끝나면 같은 응답으로 Markdown이 돌아오고, 그렇지 않으면 202와 GET /v1/conversions/{id}?wait=로 기다릴 변환 작업을 받습니다.

### 변환은 동기인가요?

기본적으로 대기 창까지는 동기입니다. POST /v1/convert/{name}가 결과를 기다렸다가 인라인으로 반환하거나, 제때 끝나지 않으면 Location과 함께 202를 반환합니다. Prefer: respond-async를 보내면 대기를 건너뜁니다.

### 어떤 이벤트를 구독할 수 있나요?

아웃바운드 웹훅은 conversion.completed와 conversion.failed를 지원하므로 폴링 대신 변환이 끝나는 즉시 반응할 수 있습니다.

### 어떤 요금제에 API 액세스가 포함되나요?

API 액세스는 유료 요금제에서 제공됩니다. 요금제별 현재 한도와 크레딧은 요금 페이지를 확인하세요.

### API 사용량은 어떻게 과금되나요?

API 변환은 웹 앱과 같은 크레딧 잔액에서 차감됩니다. 일반 페이지와 OCR 페이지는 페이지당 1크레딧입니다.

### pdf to markdown api나 url to markdown api는 어디서 찾나요?

그 표현은 별도 호스트가 아니라 형식 페이지입니다. /pdf-to-markdown의 pdf to markdown api 안내와 /url-to-markdown의 url to markdown api 안내를 확인한 뒤, 여기에 문서화된 같은 업로드·변환 엔드포인트를 호출하세요.

### API 키의 요청 한도는 어떻게 되나요?

요청은 계정 단위로 제한됩니다. Lite 분당 20회, Pro 분당 40회, Max 분당 60회입니다.

## Related

- [Introduction](https://markitdown.ai/docs)
- [PDF to Markdown Converter](https://markitdown.ai/pdf-to-markdown)
- [markitdown.ai pricing for document conversion](https://markitdown.ai/pricing)