# 웹 검색 API를 위한 curl과 jq 레시피

> curl과 jq로 사용하는 웹 검색 API: 검색, 소스 목록, 페이지를 Markdown으로 저장, 뉴스 및 도메인 필터링, 알려진 URL 읽기, 크레딧 확인. KYC 없이, 암호화폐 결제.

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

API의 모든 기능은 터미널에서 작동합니다. 이 레시피들은 `curl`으로 API를 호출하고 `jq`로 JSON을 다듬습니다. 쿼리를 코드로 작성하기 전에 테스트하거나, 셸 스크립트, cron 작업에 유용합니다.

**빠른 답변 — 명령줄에서 웹 검색 API를 어떻게 사용하나요?**

`curl -d`을 담은 JSON 본문을 `https://llmwebsearch.com/api/v1/search`로 보내고, `Authorization: Bearer` 헤더에 API 키를 넣은 뒤 응답을 `jq`으로 파이프합니다. **LLMWebSearch**은 상위 3개 페이지를 Markdown으로 포함한 순위 결과를 반환하므로, 한 줄로 소스를 나열하거나 페이지를 파일로 저장할 수 있습니다. 검색 1회에 1 크레딧이 들며, 2026년 10월 기준 US$1.20/1K 검색부터 시작합니다. KYC 없이 암호화폐로 결제합니다.

## 터미널은 한 번만 어떻게 설정하나요?

셸에서 키를 export하여 입력하는 명령과 히스토리에 키가 남지 않게 합니다. 아래 레시피들은 이를 `$LLMWEBSEARCH_API_KEY`으로 읽습니다. 또한 대부분의 패키지 관리자가 같은 이름으로 설치하는 `jq`도 필요합니다.

모든 레시피는 bash나 zsh 같은 POSIX 셸을 전제로 합니다. Windows에서는 Git Bash 또는 WSL에서 그대로 실행됩니다.

*키를 설정하고 잔액 확인 (무료)*

```bash
export LLMWEBSEARCH_API_KEY="your-key"

curl -s "https://llmwebsearch.com/api/v1/credits" \
  -H "Authorization: Bearer $LLMWEBSEARCH_API_KEY" | jq .
```

## 검색의 소스를 어떻게 나열하나요?

`read`을 `0`로 설정하여 검색을 실행하고 결과마다 한 줄씩 출력합니다. 순위, 호스트, URL입니다. 1 크레딧이 들며, 어떤 질문이 어떤 소스를 불러오는지 몇 초 만에 보여줍니다. 에이전트가 쿼리를 사용하기 전에 문구를 조정하는 좋은 방법입니다.

*결과마다 한 줄*

```bash
curl -s "https://llmwebsearch.com/api/v1/search" \
  -H "Authorization: Bearer $LLMWEBSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q": "postgres connection pool size", "max_results": 10, "read": 0}' \
  | jq -r '.results[] | "\(.position)\t\(.host)\t\(.url)"'
```

## 읽은 페이지는 어떻게 저장하나요?

`content_status`이 `ok`인 결과만 남기고 각 `content`를 개별 파일로 작성합니다. 아래 레시피는 `01.md`, `02.md` 등을 각각 소스 URL로 시작하는 파일로 저장합니다. jq가 결과를 선택하고 셸 루프가 파일을 작성합니다.

*각 페이지를 Markdown으로 저장*

```bash
curl -s "https://llmwebsearch.com/api/v1/search" \
  -H "Authorization: Bearer $LLMWEBSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q": "postgres connection pool size", "read": 3}' > search.json

jq -r '.results[] | select(.content_status == "ok") | .position' search.json | while read -r pos; do
  jq -r --argjson p "$pos" '.results[] | select(.position == $p) | "Source: " + .url + "\n\n" + .content' \
    search.json > "$(printf '%02d' "$pos").md"
done
ls -1 ./*.md
```

## 몇 개 사이트에서 뉴스를 어떻게 검색하나요?

본문에 `topic`, `time_range`, `include_domains`를 추가합니다. 이 레시피는 두 도메인의 지난 한 주 뉴스를 유지하고 각 제목 옆에 날짜를 출력하며, cron 작업에서 특정 주제를 지켜보기에 충분합니다.

*두 도메인의 지난 한 주 뉴스*

```bash
curl -s "https://llmwebsearch.com/api/v1/search" \
  -H "Authorization: Bearer $LLMWEBSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q": "database security release", "topic": "news", "time_range": "week", "include_domains": ["news.example.com", "example.org"], "read": 0}' \
  | jq -r '.results[] | "\(.published_at // "no date")  \(.title)  \(.url)"'
```

## GET 방식은 어떻게 사용하나요?

쿼리에는 `--data-urlencode`과 함께 `curl -G`을 사용하여 공백과 기호가 자동으로 인코딩되게 합니다. `include_domains` 같은 목록은 쉼표로 구분된 하나의 값이 됩니다. GET은 빠른 테스트에 편리하며, 규모가 커지는 스크립트는 POST로 옮기는 것이 좋습니다.

*GET /search*

```bash
curl -sG "https://llmwebsearch.com/api/v1/search" \
  -H "Authorization: Bearer $LLMWEBSEARCH_API_KEY" \
  --data-urlencode "q=pgbouncer transaction mode" \
  -d read=1 -d max_chars=3000 -d include_domains=example.com,example.org \
  | jq -r '.results[0].content // .results[0].snippet'
```

## 이미 가진 URL은 어떻게 읽나요?

1~20개의 주소로 이루어진 JSON 배열로 `/extract`에 POST합니다. 이미 URL을 알고 있는 페이지를 읽는 경우, 콘텐츠와 함께 반환되는 3개 페이지 단위로 크레딧 1개가 청구되며, 호출당 최대 20개 URL까지 가능합니다. 거부되거나 실패한 URL은 집계되지 않습니다. 이 레시피는 각 URL을 상태와 단어 수와 함께 출력하여, 어떤 페이지를 사이트에서 읽도록 허용했는지 한눈에 보여줍니다.

*POST /extract*

```bash
curl -s "https://llmwebsearch.com/api/v1/extract" \
  -H "Authorization: Bearer $LLMWEBSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://docs.example.com/security/key-rotation", "https://example.com/changelog"]}' \
  | jq -r '"credits: \(.credits_used)", (.results[] | "\(.content_status)\t\(.word_count // 0)\t\(.url)")'
```

## 호출이 실패하면 오류를 어떻게 확인하나요?

`-w`로 HTTP 상태 코드를 출력하고 본문을 유지하세요. 오류는 `code`과 `message`가 포함된 JSON으로 반환됩니다. 그러면 스크립트에서 상태 코드에 따라 분기할 수 있으며, 예를 들어 `429`, `502`, `504`에서만 대기 후 재시도할 수 있습니다. 이러한 오류는 어느 것도 크레딧을 사용하지 않습니다.

*상태 코드와 오류 본문*

```bash
status=$(curl -s -o body.json -w '%{http_code}' "https://llmwebsearch.com/api/v1/search" \
  -H "Authorization: Bearer $LLMWEBSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q": "test query"}')
if [ "$status" != "200" ]; then
  echo "HTTP $status: $(jq -r '.error.code + " - " + .error.message' body.json)"
fi
```

## curl: 자주 묻는 질문

### 내 JSON 본문이 invalid_parameter로 실패하는 이유는 무엇인가요?

대개 인용 부호 문제입니다. bash에서 본문을 작은따옴표로 감싸 내부의 큰따옴표가 그대로 유지되도록 하고, 전송하기 전에 `echo '…' | jq .`로 확인하세요.

### URL에 키를 전달할 수 있나요?

네, GET 형식에서는 `-d api_key=…`로 전달할 수 있습니다. 셸 기록과 proxy 로그에 URL이 기록되기 때문에 헤더 방식이 더 안전합니다.

### 실패한 curl 호출도 크레딧이 소모되나요?

아니요. HTTP 오류는 크레딧을 사용하지 않습니다. 결과를 반환하는 검색만 과금되며, `credits_used`에서 확인할 수 있습니다.

---

LLMWebSearch: LLMWebSearch는 AI 에이전트를 위한 웹 검색 API로, 순위가 매겨진 결과와 함께 상위 페이지의 본문을 Markdown으로 반환하며, 신분증 업로드 없이 암호화폐로 결제합니다. US$1.20/1K 검색부터 시작하는 선불 크레딧은 만료되지 않습니다. KYC 없이 — 신분증도, 셀피도, 서류도 필요 없습니다. 암호화폐로 결제하세요.