# Bắt đầu nhanh với web search API: lần tìm kiếm đầu tiên trong hai phút

> Bắt đầu nhanh với web search API: lấy khóa API, chạy tìm kiếm đầu tiên bằng curl, Python hoặc Node.js, xem kết quả Markdown, không cần KYC, thanh toán crypto.

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

Một endpoint làm tất cả: gửi câu hỏi đến `/search` và nhận về kết quả đã xếp hạng, với những trang đầu đã được đọc và làm sạch thành Markdown. Trang này đi từ số dư trống đến một lần gọi chạy được, rồi chỉ đến mọi trang khác của tài liệu.

**Trả lời nhanh — Làm sao để chạy lần tìm kiếm đầu tiên với web search API cho AI agent?**

Gửi câu hỏi của bạn đến `POST https://llmwebsearch.com/api/v1/search` với khóa API làm Bearer token. **LLMWebSearch** chạy một lần tìm kiếm web trực tiếp và trả về tối đa 20 kết quả đã xếp hạng, với 3 trang đầu được đọc và trả về dưới dạng Markdown. Một credit trả cho toàn bộ lần gọi đó, từ 1,20 US$/1K lượt tìm kiếm tính đến tháng 10 năm 2026. Không cần KYC; thanh toán bằng crypto.

## API trên một thẻ

| Thuộc tính | Giá trị |
| --- | --- |
| Base URL | `https://llmwebsearch.com/api/v1` |
| Tìm kiếm | `POST` hoặc `GET https://llmwebsearch.com/api/v1/search` |
| Đọc các URL bạn đã có | `POST https://llmwebsearch.com/api/v1/extract` |
| Credit còn lại | `GET https://llmwebsearch.com/api/v1/credits`, miễn phí |
| Xác thực | Truyền khóa API của bạn dưới dạng Bearer token trong header Authorization, hoặc dưới dạng tham số truy vấn api_key |
| Thanh toán | Một credit trả cho một lượt tìm kiếm: tối đa 20 kết quả được xếp hạng, với nội dung của 3 trang đầu được đọc và trả về dưới dạng Markdown. Đọc từ 4 đến 10 trang thì tính 2 credit. Lượt gọi kết thúc bằng lỗi không tốn gì |
| Trình đọc trang của chúng tôi | `LLMWebSearch/1.0 (+https://llmwebsearch.com/bot/)`, token robots.txt `LLMWebSearch` |
| Pack nhỏ nhất | 5.000 lượt tìm kiếm cho 9,25 US$; credit không bao giờ hết hạn |

## Làm thế nào để tôi lấy khóa API?

Không có biểu mẫu đăng ký. Chờ blockchain xác nhận khoản nạp của bạn là bước lâu nhất.

1. **Nạp số dư bằng crypto** — Gửi ít nhất 25 US$ bằng BTC, USDT, USDC, ETH, SOL, LTC. Đăng nhập bằng số tài khoản; địa chỉ email là tùy chọn.
2. **Mua một pack lượt tìm kiếm** — 5.000 lượt tìm kiếm cho 9,25 US$ là quá đủ để gắn tìm kiếm vào một agent và thử mọi tùy chọn.
3. **Sao chép khóa** — Khi khoản nạp crypto của bạn được xác nhận và một pack được mua, khóa API của bạn đã chờ sẵn trong dashboard. Giữ nó trong biến môi trường tên là LLMWEBSEARCH_API_KEY.

## Lượt tìm kiếm đầu tiên trông như thế nào?

Đó là một HTTPS POST với một body JSON nhỏ. Chỉ `q` là bắt buộc: câu hỏi hoặc từ khóa, đúng như một người sẽ gõ. Các giá trị mặc định đã phù hợp với hầu hết agent. Bạn nhận được 5 kết quả đã xếp hạng, và các trang đứng sau 3 kết quả đầu được đọc và trả về dưới dạng Markdown tối đa 6.000 ký tự mỗi trang.

Ba đoạn snippet dưới đây gửi cùng một lượt tìm kiếm. Chọn đoạn khớp với stack của bạn, đặt `LLMWEBSEARCH_API_KEY` trong shell, rồi chạy.

*curl: một lượt tìm kiếm, đọc 3 trang đầu*

```bash
curl -s "https://llmwebsearch.com/api/v1/search" \
  -H "Authorization: Bearer $LLMWEBSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q": "how to rotate api keys without downtime", "max_results": 5, "read": 3}'
```

*Python: liệt kê các nguồn và kích thước của chúng*

```python
import os

import requests

resp = requests.post(
    "https://llmwebsearch.com/api/v1/search",
    headers={"Authorization": "Bearer " + os.environ["LLMWEBSEARCH_API_KEY"]},
    json={"q": "how to rotate api keys without downtime", "max_results": 5, "read": 3},
    timeout=60,
)
resp.raise_for_status()
data = resp.json()
print("credits used:", data["credits_used"])
for r in data["results"]:
    size = r.get("word_count", 0)
    print(r["position"], r["title"], r["url"], r["content_status"], size, "words")

```

*Node.js 18+: in ra trang đầu tiên được đọc*

```javascript
const res = await fetch('https://llmwebsearch.com/api/v1/search', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LLMWEBSEARCH_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ q: 'how to rotate api keys without downtime', max_results: 5, read: 3 }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
const first = data.results.find((r) => r.content_status === 'ok');
console.log(first ? `${first.title}\n${first.url}\n\n${first.content.slice(0, 600)}` : 'No page could be read.');

```

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

Một đối tượng JSON gồm `query` của bạn, thời điểm gọi tính bằng `created_at`, giá tính bằng `credits_used`, và một mảng `results` theo thứ tự xếp hạng. Mỗi kết quả có `position`, `title`, `url`, `host` và `snippet`, cộng thêm `published_at` khi biết ngày.

Field cần chú ý là `content_status`. Khi nó ghi `ok`, trang đã được đọc và nội dung chính nằm trong `content`, kèm `word_count`. Các kết quả ngoài `read` ghi `not_requested`. Một trang không đọc được sẽ ghi lý do, ví dụ `blocked_by_robots`. Trang [định dạng phản hồi](https://llmwebsearch.com/vi/docs/response/) giải thích từng field.

## Những tham số nào tôi sẽ thay đổi thường xuyên nhất?

Sáu tham số bao phủ gần như mọi agent. Tất cả đều tùy chọn.

| Tham số | Nó thay đổi điều gì |
|---|---|
| `max_results` | Số kết quả đã xếp hạng trả về, từ 1 đến 20 |
| `read` | Đọc bao nhiêu kết quả đầu, từ 0 đến 10 |
| `max_chars` | Giới hạn độ dài nội dung mỗi trang, từ 500 đến 50.000 ký tự |
| `topic` và `time_range` | Tin tức thay vì trang web, và khoảng thời gian tươi mới |
| `include_domains` | Chỉ kết quả từ các site bạn liệt kê |
| `country` và `language` | Tìm kiếm chạy ở đâu và bằng ngôn ngữ nào |

Trang [tham chiếu tìm kiếm](https://llmwebsearch.com/vi/docs/search/) ghi lại từng tham số kèm ví dụ, cộng thêm `format` và `exclude_domains`.

## Một lượt gọi dùng bao nhiêu credit?

Hầu hết các lượt gọi dùng một credit. Bộ quy tắc đầy đủ:

- **Tìm kiếm đọc 0 đến 3 trang: 1 credit.** Bao gồm tối đa 20 kết quả đã xếp hạng.
- **Tìm kiếm đọc 4 đến 10 trang: 2 credit.**
- **Extract:** Đọc các trang mà bạn đã có URL tốn 1 credit cho mỗi nhóm 3 trang bắt đầu được trả về kèm nội dung, tối đa 20 URL mỗi lượt gọi; các URL bị từ chối hoặc thất bại không được tính.
- **Lỗi: 0 credit.** Một tham số sai, khóa sai, số dư trống hay lượt tìm kiếm thất bại đều không tốn gì.
- **Một trang không đọc được** trong một lượt tìm kiếm thành công không làm thay đổi giá của lượt đó.
- **Kiểm tra số dư** bằng `GET https://llmwebsearch.com/api/v1/credits` là miễn phí.

Credit tìm kiếm không có ngày hết hạn: phần bạn không dùng trong tháng này vẫn còn đó vào năm sau.

## Điều gì xảy ra khi một site không muốn bị đọc?

Kết quả vẫn xuất hiện, với tiêu đề, URL và snippet, nhưng không có nội dung trang. Trình đọc của chúng tôi tôn trọng robots.txt: nó tự giới thiệu là LLMWebSearch, tuân theo các quy tắc mà một trang viết cho nó hoặc cho tất cả robot, và bỏ qua nội dung của bất kỳ trang nào nó không được phép đọc. Một trang đặt Content-Signal: ai-input=no trong robots.txt sẽ giữ nội dung các trang của mình khỏi nội dung trong kết quả của bạn.

Khi một site từ chối trình đọc của chúng tôi, kết quả mang `content_status: "target_refused"` và mã HTTP status của chính site đó trong `target_status`. Khi một trang từ chối trình đọc của chúng tôi, kết quả trả về không có nội dung kèm trạng thá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 lách qua một chặn chặn hoặc paywall. Trang [lỗi](https://llmwebsearch.com/vi/docs/errors/) liệt kê mọi status và những status đáng thử lại.

## Tiếp theo tôi nên xem gì?

- [Endpoint tìm kiếm](https://llmwebsearch.com/vi/docs/search/) — Mọi tham số của /search, kèm ví dụ
- [Endpoint trích xuất](https://llmwebsearch.com/vi/docs/extract/) — Đọc 1 đến 20 URL bạn đã có
- [Định dạng phản hồi](https://llmwebsearch.com/vi/docs/response/) — Từng field và mọi content_status
- [Lỗi](https://llmwebsearch.com/vi/docs/errors/) — Lỗi HTTP, status của trang, quy tắc thử lại
- [Python](https://llmwebsearch.com/vi/docs/python/) — requests, async httpx, câu trả lời kèm trích dẫn
- [Node.js](https://llmwebsearch.com/vi/docs/node/) — fetch, một pool nhỏ, cùng vòng lặp trích dẫn
- [curl và jq](https://llmwebsearch.com/vi/docs/curl/) — Công thức cho Terminal
- [MCP server](https://llmwebsearch.com/vi/docs/mcp/) — search_web cho Claude Code và Claude Desktop
- [LangChain và LlamaIndex](https://llmwebsearch.com/vi/docs/langchain/) — Một công cụ và một trình truy xuất
- [OpenAI function calling](https://llmwebsearch.com/vi/docs/openai/) — Schema công cụ, vòng lặp và Agents SDK
- [n8n](https://llmwebsearch.com/vi/docs/n8n/) — Công cụ HTTP Request cho một AI Agent
- [OpenClaw](https://llmwebsearch.com/vi/docs/openclaw/) — Tìm kiếm của chúng tôi qua MCP

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

### Tôi có cần SDK không?

Không. LLMWebSearch là một API HTTPS thuần, nên bất kỳ HTTP client nào cũng dùng được. Tài liệu này cung cấp mã sao chép-dán cho Python, Node.js và curl, cùng định nghĩa công cụ cho MCP, LangChain, LlamaIndex, OpenAI function calling, n8n và OpenClaw. Chúng tôi không phát hành package nào.

### API có viết câu trả lời cho tôi không?

Không. API trả về các nguồn, không phải một câu trả lời được viết sẵn: model của chính bạn đọc các trang, viết câu trả lời và trích dẫn các URL. Điều đó giúp bạn tự do chọn model, prompt và kiểu trích dẫn.

### Tôi có thể đặt khóa trong URL không?

Có, dưới dạng tham số truy vấn `api_key` của `GET /search`. Header `Authorization` là lựa chọn an toàn hơn, vì URL thường lọt vào log và lịch sử shell. Tạo một khóa API cho mỗi agent, ứng dụng hoặc đồng đội và thu hồi bất kỳ khóa nào trong dashboard mà không ảnh hưởng đến các khóa khác.

### Có gói miễn phí để dùng thử không?

Không. Không có gói miễn phí: pack 5.000 lượt tìm kiếm là cách để dùng thử, mua từ mức nạp tối thiểu; phần bạn nạp thêm chỉ để đạt mức tối thiểu đó sẽ được hoàn lại theo yêu cầu trong vòng 30 ngày, bằng USDT hoặc USDC, miễn là chưa dùng.

---

LLMWebSearch: LLMWebSearch là một web search API cho AI agent, trả về kết quả đã xếp hạng kèm nội dung của các trang hàng đầu ở định dạng Markdown, thanh toán bằng crypto mà không cần tải lên giấy tờ tùy thân. Credit trả trước từ 1,20 US$/1K lượt tìm kiếm không bao giờ hết hạn. Không cần KYC — không ID, không selfie, không giấy tờ. Thanh toán bằng crypto.