# Bắt đầu nhanh với URL to Markdown API: trang đầu tiên của bạn trong hai phút

> Bắt đầu nhanh với URL to Markdown API: lấy khóa, đọc trang đầu bằng curl, Python hay Node.js và kiểm tra credit. Từ 0,07 US$/1K trang, không cần KYC.

- URL: https://webreaderapi.com/vi/docs/
- Cập nhật lần cuối: 2026-10-22
- Đơn vị phát hành: WebReaderAPI (https://webreaderapi.com)

Một endpoint, một tham số: gửi một URL đến `/read` và nhận nội dung chính của trang về dưới dạng Markdown. Trang này đưa bạn từ số dư trống đến một lệnh gọi chạy được, rồi chỉ tới mọi thứ khác.

**Câu trả lời nhanh — Làm sao để chuyển một URL sang Markdown bằng API?**

Gửi URL đến `GET https://webreaderapi.com/api/v1/read` với khóa API của bạn trong header `Authorization`. **WebReaderAPI** tải trang, giữ lại nội dung chính và trả về dưới dạng Markdown kèm tiêu đề, tác giả, ngày và số từ. Mỗi trang tốn một credit (hai nếu cần trình duyệt), từ 0,07 US$/1K trang tính đến tháng 10 năm 2026. Không cần KYC; thanh toán bằng crypto.

## API trong một bảng

| Thuộc tính | Giá trị |
| --- | --- |
| Base URL | `https://webreaderapi.com/api/v1` |
| Đọc một trang | `GET` hoặc `POST https://webreaderapi.com/api/v1/read` |
| Nhiều URL hoặc một trang web | `POST https://webreaderapi.com/api/v1/batch` và `POST https://webreaderapi.com/api/v1/crawl`, kết quả từ `GET https://webreaderapi.com/api/v1/jobs/{job_id}` |
| Credit còn lại | `GET https://webreaderapi.com/api/v1/credits` (miễn phí) |
| Xác thực | Gửi khóa API trong header Authorization dưới dạng Bearer token, hoặc trong query parameter api_key |
| Tính phí | 1 credit = đọc 1 trang không cần trình duyệt; 2 credit khi trang cần trình duyệt để render JavaScript. Yêu cầu thất bại, hoặc bị robots.txt của trang web từ chối, không bị tính phí |
| Trình thu thập của chúng tôi | `WebReaderAPI/1.0 (+https://webreaderapi.com/bot/)`, robots.txt token `WebReaderAPI` |
| Pack nhỏ nhất | 10.000 trang cho 3,75 US$; credit không bao giờ hết hạn |

## Làm sao để lấy một khóa API?

Ba bước, không cần điền form. Bước chậm nhất là xác nhận blockchain cho khoản nạp của bạn.

1. **Nạp bằng crypto** — Gửi tối thiểu 25 US$ bằng BTC, USDT, USDC, ETH, SOL, LTC. Đăng nhập bằng số tài khoản; email là tùy chọn.
2. **Mua một gói credit** — 10.000 trang cho 3,75 US$ là đủ để thử mọi tùy chọn trên URL của riêng bạn.
3. **Sao chép khóa của bạn** — Khóa API của bạn sẵn sàng trong dashboard sau khi khoản nạp crypto được xác nhận và bạn đã mua một pack. Lưu nó trong biến môi trường tên là WEBREADER_API_KEY.

## Request đầu tiên trông như thế nào?

Đó là một HTTPS GET thông thường với địa chỉ trang nằm trong tham số `url`. Hãy encode địa chỉ, vì nó chứa các ký tự `:` và `/` của chính nó; curl làm việc đó cho bạn với `--data-urlencode`. Các thiết lập mặc định đã phù hợp với hầu hết bài viết và trang tài liệu: đầu ra Markdown, chỉ nội dung chính, và chỉ dùng trình duyệt headless khi trang cần.

*curl: đọc một trang*

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

*Python: đọc một trang và lưu lại*

```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"},
    timeout=70,
)
resp.raise_for_status()
page = resp.json()
print(page["title"], "-", page["word_count"], "words,", page["credits_used"], "credit(s)")
with open("first-post.md", "w", encoding="utf-8") as f:
    f.write(page["markdown"])

```

*Node.js 18+: đọc một trang*

```javascript
const params = new URLSearchParams({ url: 'https://example.com/blog/first-post' });
const res = await fetch(`https://webreaderapi.com/api/v1/read?${params}`, {
  headers: { Authorization: `Bearer ${process.env.WEBREADER_API_KEY}` },
});
const page = await res.json();
if (!res.ok) throw new Error(`${page.error.code}: ${page.error.message}`);
console.log(page.title, page.word_count, 'words');
console.log(page.markdown.slice(0, 500));

```

## Kết quả trả về là gì?

Một đối tượng JSON với Markdown trong trường `markdown` và metadata của trang bên cạnh: `title`, `description`, `author`, `published_at`, `language`, `site_name` và `word_count`. Hai trường giúp bạn kiểm tra chuyện gì đã xảy ra: `final_url` là địa chỉ sau các lần redirect, và `rendered` cho bạn biết có cần đến trình duyệt headless hay không.

`credits_used` cho thấy chi phí của lần gọi: 1 cho một trang thường, 2 khi `rendered` là `true`, thêm một nếu bạn chọn `country`. Trang [định dạng phản hồi](https://webreaderapi.com/vi/docs/response/) liệt kê mọi trường kèm ví dụ.

## Tôi sẽ dùng những tùy chọn nào nhiều nhất?

Năm tham số đáp ứng hầu hết nhu cầu. Tất cả đều tùy chọn.

| Tham số | Dùng để |
|---|---|
| `format` | Nhận `text` hoặc `html` đã làm sạch thay vì `markdown` |
| `main_content` | Đặt `false` để chuyển toàn bộ trang, kể cả menu |
| `render` | Buộc (`true`) hoặc cấm (`false`) trình duyệt headless; `auto` quyết định |
| `include_links` | Nhận các liên kết của trang thành một danh sách riêng |
| `max_chars` | Cắt các trang dài để vừa ngân sách ngữ cảnh của model |

[Tham chiếu read](https://webreaderapi.com/vi/docs/read/) mô tả mọi tham số, gồm cả `country`, `include_images` và `timeout`.

## Làm sao kiểm tra credit còn lại?

Gọi `GET https://webreaderapi.com/api/v1/credits` với cùng khóa đó. Nó trả về `credits_remaining`, `credits_used_today` và `concurrency_limit` của bạn, và không tốn gì. Hãy chạy nó ở đầu một tác vụ dài để tác vụ dừng gọn gàng thay vì thất bại vì `402 insufficient_credits` giữa chừng.

Credit trả trước không bao giờ hết hạn: số trang chưa dùng vẫn ở trong tài khoản của bạn cho đến khi bạn dùng, nên một pack mua cho dự án này vẫn giữ nguyên giá trị cho dự án tiếp theo.

## Chuyện gì xảy ra nếu một trang web không cho phép robots?

Chúng tôi không đọc trang, và bạn không bị tính phí. Trình thu thập dữ liệu của chúng tôi tự giới thiệu là `WebReaderAPI/1.0 (+https://webreaderapi.com/bot/)` và tuân theo robots.txt của trang web. Một trang bị disallow trả về `403 blocked_by_robots`; một trang web từ chối request theo cách khác trả về `502 target_refused` kèm mã trạng thái của chính trang đó.

Nếu một website từ chối yêu cầu của chúng tôi, chúng tôi trả lại câu trả lời của trang đó: chúng tôi không bao giờ giải CAPTCHA, đăng nhập vào tài khoản, hay tìm cách vượt qua chặn hoặc paywall. [Trang lỗi](https://webreaderapi.com/vi/docs/errors/) giải thích lỗi nào nên thử lại và lỗi nào là lỗi cuối cùng.

## Tôi nên đi đâu tiếp theo?

- [Đọc tham chiếu endpoint](https://webreaderapi.com/vi/docs/read/) — Mọi tham số của /read, kèm ví dụ
- [Batch và crawl](https://webreaderapi.com/vi/docs/crawl/) — Tối đa 100 URL mỗi batch, hoặc cả một trang web
- [Định dạng phản hồi](https://webreaderapi.com/vi/docs/response/) — Mọi trường của câu trả lời
- [Lỗi và robots.txt](https://webreaderapi.com/vi/docs/errors/) — Mã lỗi, nguyên nhân và quy tắc thử lại
- [Python](https://webreaderapi.com/vi/docs/python/) — requests, async httpx, chia chunk cho RAG
- [Node.js](https://webreaderapi.com/vi/docs/node/) — fetch, một pool nhỏ, poll crawl
- [curl và jq](https://webreaderapi.com/vi/docs/curl/) — Công thức cho terminal
- [MCP server](https://webreaderapi.com/vi/docs/mcp/) — Một tool read_url cho Claude và Cursor
- [LangChain và LlamaIndex](https://webreaderapi.com/vi/docs/langchain/) — Loader và tool cho RAG
- [OpenAI function calling](https://webreaderapi.com/vi/docs/openai/) — Schema và vòng lặp cho tool read_url
- [n8n](https://webreaderapi.com/vi/docs/n8n/) — Tool HTTP Request cho AI Agent
- [OpenClaw](https://webreaderapi.com/vi/docs/openclaw/) — Thêm MCP server bên cạnh web_fetch

## Bắt đầu nhanh: câu hỏi thường gặp

### Có SDK nào cần cài không?

Không. WebReaderAPI là một API HTTPS thông thường, nên HTTP client nào cũng dùng được. Tài liệu có mã copy-paste cho Python, Node.js và curl, cùng định nghĩa tool cho MCP, LangChain, LlamaIndex và OpenAI function calling. Không có gì được phát hành dưới dạng package.

### Tôi có thể gửi khóa trong URL thay vì header không?

Được, dưới dạng tham số truy vấn `api_key`. Header `Authorization: Bearer` an toàn hơn, vì URL thường lọt vào log và lịch sử trình duyệt. Tạo nhiều khóa API, ví dụ mỗi agent hoặc dự án một khóa, và thu hồi bất kỳ khóa nào từ dashboard của bạn.

### Một trang thất bại có tốn credit không?

Không. 1 credit = đọc 1 trang không cần trình duyệt; 2 credit khi trang cần trình duyệt để render JavaScript. Yêu cầu thất bại, hoặc bị robots.txt của trang web từ chối, không bị tính phí. Chỉ trang trả về có nội dung mới bị tính phí.

### Tôi có thể dùng thử trước khi mua không?

Không có gói miễn phí. Không có gói miễn phí: pack nhỏ nhất là cách để thử, thanh toán từ mức nạp tối thiểu, và phần tiền chỉ nạp thêm để đạt mức tối thiểu đó có thể được gửi trả theo yêu cầu trong vòng 30 ngày, bằng USDT hoặc USDC, miễn là chưa dùng.

---

WebReaderAPI: WebReaderAPI là web reader API cho AI agent, chuyển mọi trang web công khai thành Markdown sạch, thanh toán bằng crypto không cần tải lên giấy tờ. Credit trả trước từ 0,07 US$/1K trang không bao giờ hết hạn, và robots.txt được tôn trọng. Không cần KYC — không ID, không selfie, không giấy tờ. Thanh toán bằng crypto.