# Read 엔드포인트 레퍼런스: GET 및 POST /read

> Read 엔드포인트 레퍼런스: format과 render부터 country와 max_chars까지, GET 및 POST /read의 모든 파라미터를 예제와 함께 봅니다. US$0.07/1K 페이지부터, KYC 없이.

- URL: https://webreaderapi.com/ko/docs/read/
- 마지막 업데이트: 2026-10-22
- 발행자: WebReaderAPI (https://webreaderapi.com)

`/read`는 공개 페이지 하나를 가져와 본문을 추출하고 Markdown, 일반 텍스트 또는 정리된 HTML로 반환합니다. 이 페이지는 모든 파라미터와 기본값, 비용을 나열합니다.

**빠른 답변 — WebReaderAPI read 엔드포인트는 어떤 파라미터를 받나요?**

**WebReaderAPI**의 `/read` 엔드포인트는 `url` 파라미터 하나가 필요합니다. 선택 파라미터는 출력 형식(`format`), 페이지에서 유지할 범위(`main_content`), 브라우저 실행 여부(`render`), 링크와 이미지, 읽는 국가, 문자 제한, 타임아웃을 정합니다. 일반 페이지는 1 크레딧, 브라우저 사용 시 2 크레딧이며, 2026년 10월 기준 US$0.07/1K 페이지부터 시작합니다. KYC 없이, 암호화폐로 결제하세요.

## /read at a glance

| 속성 | 값 |
| --- | --- |
| 메서드 | 쿼리 파라미터를 붙인 `GET`, 또는 같은 이름을 사용하는 JSON 본문을 붙인 `POST` |
| URL | `https://webreaderapi.com/api/v1/read` |
| 필수 | `url`: http 또는 https 주소, 최대 2,048자 |
| 기본 출력 | 본문의 Markdown |
| 과금 | 1 크레딧 = 브라우저 없이 페이지 1회 읽기, 페이지가 JavaScript를 렌더링하는 데 브라우저가 필요하면 2 크레딧. 실패한 요청이나 사이트의 robots.txt가 거부한 요청은 과금되지 않습니다 |
| 국가 | 페이지를 읽는 국가를 선택하면 10 크레딧이 추가됩니다. 이 경우 해당 국가의 주거용 연결을 통해 페이지를 읽기 때문입니다 |
| PDF | 최대 20 MB, 100페이지까지의 PDF 파일이 Markdown으로 변환되며, 시작된 10페이지 블록당 1 크레딧입니다 |
| 크롤러 식별 | `WebReaderAPI/1.0 (+https://webreaderapi.com/bot/)` |

## 페이지 하나 읽기 (GET)

`GET /api/v1/read`

공개 페이지 하나를 가져와 본문을 페이지 메타데이터와 함께 Markdown으로 반환합니다. 파라미터는 URL 인코딩된 쿼리 문자열로 전달합니다. 예제는 블로그 글을 읽습니다. ID, 날짜, 값은 예시입니다.

인증: `Authorization: Bearer API_KEY` 헤더에 API 키를 넣습니다.

**파라미터**

| 이름 | 위치 | 타입 | 필수 | 설명 |
| --- | --- | --- | --- | --- |
| `url` | query | string | 예 | 읽을 페이지: http 또는 https, 최대 2,048자. 사설, 로컬, 클라우드 메타데이터 주소는 거부됩니다. |
| `format` | query | string | 아니요 | `markdown`(기본값), `text`(마크업 없는 일반 텍스트) 또는 `html`(본문의 정리된 HTML) |
| `main_content` | query | boolean | 아니요 | `true`(기본값)은 기사나 본문만 유지하고, `false`은 메뉴와 푸터를 포함한 전체 페이지를 변환합니다. |
| `render` | query | string | 아니요 | `auto`(기본값)은 원시 HTML의 텍스트가 너무 적을 때만 브라우저를 실행하고, `true`은 항상, `false`는 절대 실행하지 않습니다. 렌더링된 페이지는 2 크레딧입니다. |
| `include_links` | query | boolean | 아니요 | `true`은 `{url, text}`의 `links` 목록을 추가합니다. 기본값 `false`. |
| `include_images` | query | boolean | 아니요 | `true`은 이미지를 Markdown의 `![alt](src)`로 유지합니다. 기본값 `false`. |
| `country` | query | string | 아니요 | 두 글자 국가 코드(ISO 3166-1 alpha-2). 해당 국가의 주소에서 페이지를 읽으며, 10 크레딧 추가(주거용 연결)입니다. |
| `max_chars` | query | integer | 아니요 | 이 문자 수에서 출력을 자릅니다. 1,000에서 500,000까지. 모델의 컨텍스트에 맞추는 데 유용합니다. |
| `timeout` | query | integer | 아니요 | 사이트를 기다리는 시간(초)으로, 5에서 60 사이입니다. 기본값은 30입니다. |
| `api_key` | query | string | 아니요 | `Authorization` 헤더를 보내지 않는 경우 사용할 키입니다. |

**응답** `200`

```json
{
  "url": "https://example.com/blog/first-post",
  "final_url": "https://example.com/blog/first-post",
  "status_code": 200,
  "fetched_at": "2026-10-22T09:41:12Z",
  "rendered": false,
  "credits_used": 1,
  "title": "Our first post",
  "description": "Why we started this blog and what comes next.",
  "language": "en",
  "author": "Jane Doe",
  "published_at": "2026-10-01",
  "site_name": "Example Blog",
  "markdown": "# Our first post\n\nWe started this blog to share what we learn...\n\n## What comes next\n\n- A post every month\n- Notes from our team",
  "word_count": 612
}
```

*curl*

```bash
curl -sG "https://webreaderapi.com/api/v1/read" \
  -H "Authorization: Bearer $WEBREADER_API_KEY" \
  --data-urlencode "url=https://example.com/blog/first-post" \
  -d format=markdown -d max_chars=20000
```

*Python*

```python
import os
import requests

resp = requests.get(
    "https://webreaderapi.com/api/v1/read",
    headers={"Authorization": "Bearer " + os.environ["WEBREADER_API_KEY"]},
    params={"url": "https://example.com/blog/first-post", "max_chars": 20000},
    timeout=70,
)
resp.raise_for_status()
print(resp.json()["markdown"][:300])
```

*Node.js*

```javascript
const params = new URLSearchParams({ url: 'https://example.com/blog/first-post', max_chars: '20000' });
const res = await fetch(`https://webreaderapi.com/api/v1/read?${params}`, {
  headers: { Authorization: `Bearer ${process.env.WEBREADER_API_KEY}` },
});
const page = await res.json();
console.log(page.markdown.slice(0, 300));
```

## 페이지 하나 읽기 (POST)

`POST /api/v1/read`

동일한 endpoint, 동일한 parameter를 JSON body로 보냅니다. URL이 매우 길거나 HTTP 클라이언트가 query string보다 JSON을 더 쉽게 만들 때 POST를 선호하세요. 응답은 GET 형식과 동일합니다.

인증: `Authorization: Bearer API_KEY` 헤더에 API 키를 넣습니다.

**요청 본문**

| 필드 | 타입 | 필수 | 설명 |
| --- | --- | --- | --- |
| `url` | string | 예 | 읽을 페이지입니다. |
| `format`, `main_content`, `render`, `include_links`, `include_images`, `country`, `max_chars`, `timeout` | mixed | 아니요 | 위의 GET 표와 같으며, JSON 타입을 따릅니다: boolean은 `true`/`false`, 숫자는 따옴표 없이 표기합니다. |

*예시: a JavaScript-heavy page, read from Germany, with its links*

```json
{
  "url": "https://example.com/app/pricing",
  "render": "true",
  "country": "de",
  "include_links": true,
  "max_chars": 30000
}
```

**응답** `200`

```json
{
  "url": "https://example.com/app/pricing",
  "final_url": "https://example.com/de/app/pricing",
  "status_code": 200,
  "fetched_at": "2026-10-22T09:44:03Z",
  "rendered": true,
  "credits_used": 3,
  "title": "Pricing",
  "language": "de",
  "markdown": "# Pricing\n\n| Plan | Price |\n|---|---|\n| Basic | ... |",
  "word_count": 214,
  "links": [
    {
      "url": "https://example.com/de/contact",
      "text": "Contact"
    }
  ]
}
```

*curl*

```bash
curl -s "https://webreaderapi.com/api/v1/read" \
  -H "Authorization: Bearer $WEBREADER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/app/pricing", "render": "true", "country": "de", "include_links": true}'
```

*Python*

```python
import os
import requests

resp = requests.post(
    "https://webreaderapi.com/api/v1/read",
    headers={"Authorization": "Bearer " + os.environ["WEBREADER_API_KEY"]},
    json={"url": "https://example.com/app/pricing", "render": "true", "country": "de", "include_links": True},
    timeout=70,
)
print(resp.json()["credits_used"], "credits")
```

*Node.js*

```javascript
const res = await fetch('https://webreaderapi.com/api/v1/read', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.WEBREADER_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ url: 'https://example.com/app/pricing', render: 'true', country: 'de', include_links: true }),
});
console.log((await res.json()).credits_used);
```

## 어떤 output format을 선택해야 하나요?

언어 모델과 RAG에는 `markdown`를 선택하세요: 제목, 목록, 표, 링크가 유지되고 텍스트가 간결하게 남습니다. 단어 수를 세거나 분류, 검색만 하고 마크업이 방해가 될 때는 `text`를 선택하세요. 자체 pipeline이 이미 HTML을 파싱하고 잡음만 제거하고 싶을 때는 `html`를 선택하세요.

메타데이터 field는 세 형식 모두 동일합니다. content field의 이름만 `markdown`, `text` 또는 `html`로 바뀝니다.

## main_content를 false로 설정해야 하는 경우는 언제인가요?

기사 주변 부분이 필요할 때 `false`으로 설정하세요. 예를 들어 사이트의 섹션을 파악하기 위한 내비게이션, 법적 정보나 연락처가 있는 footer, 또는 사양이 사이드바에 있는 제품 페이지 등입니다.

기본값 `true`의 경우, extractor는 주요 콘텐츠 블록을 유지하고 내비게이션, 쿠키 배너, 광고, 공유 버튼, footer를 제거합니다. 대부분의 agent와 RAG pipeline이 원하는 방식이며, 페이지를 HTML 크기의 일부로 줄여주는 경우가 많습니다.

## render=auto는 어떻게 브라우저 사용을 결정하나요?

먼저 raw HTML을 가져오며, 이는 빠르고 1 크레딧이 듭니다. 해당 HTML에 읽을 수 있는 텍스트가 너무 적으면(일반적으로 JavaScript로 페이지를 구성하는 앱), 헤드리스 브라우저에서 페이지를 다시 로드하며 이 호출은 2 크레딧이 듭니다. 응답은 어떤 경로가 실행되었는지 알려줍니다: `rendered`은 `true` 또는 `false`입니다.

사이트가 완전한 HTML을 제공한다는 것을 알고 고정 비용을 원할 때는 `render=false`으로 설정하세요. 단일 페이지 앱의 경우 첫 시도를 건너뛰려면 `render=true`로 설정하세요.

## country와 max_chars는 무엇을 바꾸나요?

`country`은 지정한 국가의 주소에서 동일한 User-Agent로 페이지를 읽습니다. 가격, 언어, 제공 여부가 국가별로 달라지는 페이지에 사용하세요. 주거용 연결로 페이지를 읽기 때문에 10 크레딧이 추가되며, 서비스가 운영되지 않는 국가에서는 사용할 수 없습니다.

`max_chars`은 해당 문자 수 이후 출력을 자릅니다. 가격은 바뀌지 않지만, agent의 context window를 보호합니다: 모델에 전달하는 단일 페이지에는 20,000자가 합리적인 기본값입니다.

## /read는 PDF 파일을 처리할 수 있나요?

네. URL이 PDF를 반환하면 텍스트가 동일한 `markdown` field에 Markdown으로 반환됩니다. 최대 20 MB, 100페이지까지의 PDF 파일이 Markdown으로 변환되며, 시작된 10페이지 블록당 1 크레딧입니다. 텍스트 레이어가 없는 스캔된 PDF는 문자 인식 단계가 없기 때문에 텍스트가 거의 또는 전혀 반환되지 않습니다.

## Read endpoint: 자주 묻는 질문

### /read는 redirect를 따르나요?

네, 최대 5회까지 따릅니다. 응답은 요청한 주소를 `url`에, 실제로 읽은 주소를 `final_url`에 제공합니다. 비공개 또는 로컬 주소로의 redirect는 거부됩니다.

### 로그인이 필요한 페이지를 읽을 수 있나요?

아니요. 사이트가 우리 요청을 거부하면 그 응답을 그대로 반환합니다. 우리는 CAPTCHA를 풀거나, 계정에 로그인하거나, 차단이나 페이월을 우회하려 시도하지 않습니다. 로그인이나 paywall 뒤의 페이지는 사이트의 거부 응답을 반환하며, 이 호출은 무료입니다.

### robots.txt 확인은 매 호출마다 이루어지나요?

네, 최대 24시간 된 사이트의 robots.txt 사본을 기준으로 확인합니다. 허용되지 않은 URL은 `403 blocked_by_robots`을 반환하고 크레딧을 사용하지 않습니다.

### 동시에 몇 개의 페이지를 읽을 수 있나요?

모든 계정에는 동시에 읽는 페이지 수에 대한 한도가 있으며, 대시보드에 표시됩니다. 지원팀이 이를 높일 수 있습니다. 많은 URL의 경우 [batch job](https://webreaderapi.com/ko/docs/crawl/)이 많은 병렬 호출을 실행하는 것보다 간단합니다.

---

WebReaderAPI: WebReaderAPI는 AI 에이전트를 위한 웹 리더 API로, 모든 공개 웹페이지를 깔끔한 Markdown으로 변환하며 신분증 업로드 없이 암호화폐로 결제합니다. US$0.07/1K 페이지부터 시작하는 선불 크레딧은 만료되지 않으며, robots.txt를 준수합니다. KYC 없음 — 신분증도, 셀피도, 서류도 없습니다. 암호화폐로 결제하세요.