> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# DeepSeek 웹 검색 및 Fetch API

> DeepSeek의 네이티브 Search / Fetch 도구 API: 쿼리를 통한 웹 검색과 모든 URL을 Markdown으로 가져오는 기능을 지원하여 에이전트 및 RAG에 활용할 수 있습니다. APIYI는 /v1/tools/search 및 /v1/tools/fetch를 제공하며 성공한 요청당 과금됩니다. 고액 충전 고객에게는 공식 가격과 동일하게 적용됩니다.

DeepSeek는 실시간 웹 데이터가 필요한 에이전트 및 RAG 파이프라인을 위한 두 가지 독립형 도구 API를 제공합니다:

* **Search**: 쿼리를 전송하여 구조화된 웹 검색 결과(제목, 링크, 요약, 선택적 페이지 본문)를 가져옵니다.
* **Fetch**: URL을 전송하여 Markdown으로 이미 변환된 페이지 본문을 가져옵니다.

이 API들은 **채팅 모델이 아닙니다**. tokens를 소비하지 않으며 **성공한 요청 건당 과금**됩니다. 작성한 코드에서 검색 시점과 대상을 결정한 후, 결과 데이터를 모든 모델에 전달할 수 있습니다.

> [!NOTE]
>
> **모델 이름**: `deepseek-search`, `deepseek-fetch`. **엔드포인트**: `POST /v1/tools/search`, `POST /v1/tools/fetch`. `default` / `svip` 그룹에서 지원됩니다.
> 이 페이지의 모든 데이터는 2026년 10월 21일 (UTC+8) 기준 APIYI 테스트 결과에서 가져왔습니다.

> [!WARNING]
>
> **ClaudeCode 그룹의 키로는 이 두 API를 호출할 수 없습니다.** 호출 시 503 `no available channels for model deepseek-search` 오류가 반환됩니다. `default` 또는 `svip` 그룹에서 별도의 키를 생성하십시오.

## 기능 개요 및 사용 시기

| | 검색(Search) | 가져오기(Fetch) |
| - | - | - |
| 입력 | 쿼리(`site:` 및 `lang:`과 같은 연산자 지원) | 하나의 HTTP / HTTPS URL |
| 출력 | 1\~50개의 검색 결과, 페이지 본문(선택 사항) | 페이지 제목 + Markdown 본문 |
| 주요 용도 | 에이전트 웹 검색, RAG를 위한 실시간 컨텍스트 제공, 뉴스 및 주제 모니터링 | 결과 중 하나의 페이지 읽기, 문서 사이트 크롤링, 요약을 위해 모델에 페이지 전달 |
| 측정 지연 시간 | 1.6\~3.0초 | 1.6\~5초 (대상 사이트에 따라 다름) |

일반적인 패턴은 **먼저 검색(Search)한 다음 몇 가지 결과만 가져오는(Fetch) 것**입니다. 각 결과의 `summary`만으로도 모델이 관련성을 판단하기에 충분하므로, 전체 내용이 필요한 페이지만 가져오시면 됩니다.

### Claude Code 내장 검색과의 관계

이 페이지는 **일반 API**에 대한 설명입니다. 작성한 코드에서 `/v1/tools/search` 및 `/v1/tools/fetch`를 직접 호출합니다.

Claude Code 및 Codex와 같은 클라이언트에서 모델이 시작하는 웹 검색은 채팅 API 내부의 서버 측 도구(`web_search`)를 통해 처리되며, 이는 본 API와는 다른 방식입니다. APIYI는 향후 릴리스에서 이러한 클라이언트 내 DeepSeek 모델을 위한 내장 검색을 지원할 예정이며, 세부 사항은 별도로 공지하겠습니다.

## 요금 안내

| API | 공식 가격 | APIYI 정가 | 고액 충전 고객 부담액 (÷1.2) | 일반 고객 부담액 (÷1.1) |
| - | - | - | - | - |
| Search (`deepseek-search`) | \$0.75 / 1,000건 요청 | \$0.90 / 1,000건 요청 | **\$0.75 / 1,000건 요청** | 약 \$0.82 / 1,000건 요청 |
| Fetch (`deepseek-fetch`) | \$0.75 / 1,000건 요청 | \$0.90 / 1,000건 요청 | **\$0.75 / 1,000건 요청** | 약 \$0.82 / 1,000건 요청 |

> [!NOTE]
>
> **요금 한 줄 요약: “20% 보너스가 적용되는 고액 충전 고객”을 기준으로 책정되어, 보너스 적용 시 공식 가격과 동일해집니다.** 정가는 요청당 \$0.0009이며, 20% [충전 보너스](/ko/faq/recharge-promotions)를 적용한 실제 비용은 요청당 \$0.00075로 **DeepSeek 공식 가격과 동일합니다**. 10% 보너스가 적용되는 일반 고객의 부담액은 공식 가격의 약 1.09배입니다. 가격에는 **세금이 포함되어 있으며** 인보이스 발행이 가능합니다. DeepSeek는 해당 API에 대해 할인을 제공하지 않으며, APIYI 역시 수익을 목적으로 가격을 책정하지 않았습니다. 이는 **안정적인 공급을 확보하고 고객에게 편의를 제공하기 위해** 제공되는 것입니다. 별도의 DeepSeek 계정이나 충전 없이도 단 하나의 APIYI 키로 search, fetch 및 모든 주요 모델을 이용할 수 있습니다.

> [!NOTE]
>
> 모델 가격은 공식 가격을 따르며 공식 가격 변동에 따라 변경될 수 있습니다. 위 표는 참고용일 뿐이며 상단 내비게이션의 **모델 가격** 탭을 기준으로 합니다: [모델 가격](/en/models/index).

**과금 규칙** (공식 API와 동일):

* **성공한 요청에 대해서만 과금됩니다**: 결과가 반환된 HTTP 200
* 파라미터 오류(400) 및 페치 실패(404)는 **과금되지 않습니다**
* 가격은 `count`, `need_content` 또는 응답 길이에 영향을 받지 **않습니다**: 결과가 1건이든 페이지 본문을 포함한 50건이든 동일하게 1건의 요청으로 처리됩니다
* 각 호출은 콘솔 로그에 모델명 `deepseek-search` 또는 `deepseek-fetch`으로 별도의 행에 기록되므로, 모델별로 내역을 대조할 수 있습니다

## 빠른 시작

```bash Search theme={null}
curl https://api.apiyi.com/v1/tools/search \
  -H "Authorization: Bearer $APIYI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "DeepSeek V4 release",
    "count": 5
  }'
```

```bash Fetch theme={null}
curl https://api.apiyi.com/v1/tools/fetch \
  -H "Authorization: Bearer $APIYI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://docs.apiyi.com/en"
  }'
```

```python Python theme={null}
import os
import requests

BASE = "https://api.apiyi.com/v1/tools"
HEADERS = {"Authorization": f"Bearer {os.environ['APIYI_API_KEY']}"}

# 1. Search
r = requests.post(f"{BASE}/search", headers=HEADERS, timeout=60,
                  json={"query": "DeepSeek V4 release", "count": 5})
r.raise_for_status()
results = r.json()["results"]
for item in results:
    print(item["rerank_score"], item["title"], item["url"])

# 2. Fetch the top result
r = requests.post(f"{BASE}/fetch", headers=HEADERS, timeout=60,
                  json={"url": results[0]["url"]})
if r.status_code == 200:
    page = r.json()
    print(page["title"])
    print(page["content"][:500])
else:
    print("Fetch failed, not billed:", r.status_code, r.json()["error"]["message"])
```

요청 본문에는 `model` 필드가 필요하지 **않으며**, 필드를 전송하더라도 무시됩니다.

## 요청 파라미터

### 검색: `POST /v1/tools/search`

| 파라미터 | 타입 | 필수 여부 | 설명 |
| - | - | - | - |
| `query` | string | ✓ | 검색 쿼리, 1\~128자, 공백만으로는 구성할 수 없습니다. 아래의 연산자를 지원합니다 |
| `count` | int | | 결과 수, 1\~50개, 기본값 10. **가격에 영향을 주지 않습니다** |
| `need_content` | bool | | 페이지 본문 반환 여부, 기본값 `false`(이 경우 `content`은 항상 빈 문자열입니다). 응답 크기가 대략 2배로 증가합니다 |
| `ori_question` | string | | 이 검색의 배경이 되는 사용자의 원래 질문, 1\~128자, 의도를 파악하는 데 사용됩니다 |
| `localization` | string | | **사용자의 IP 주소**, 지역화된 결과의 우선순위를 정하는 데 사용됩니다. **로캘 코드가 아님**: `ja-JP`은 400을 반환합니다 |

**검색 연산자**(`query` 내부):

| 연산자 | 효과 | 예시 |
| - | - | - |
| `site:` | 해당 사이트만 검색; 여러 개인 경우 `OR`(으)로 연결 | `site:arxiv.org OR site:github.com RAG` |
| `-site:` | 사이트 제외 | `LLM -site:reddit.com` |
| `"..."` / `-"..."` | 정확한 문구 필수 포함 / 제외 | `"thinking mode" -"deprecated"` |
| `-keyword` | 해당 키워드를 포함하는 페이지 제외 | `apple -iphone` |
| `lang:` | 언어 제한, 쉼표로 구분 | `lang:zh,en DeepSeek` |
| `after:` / `before:` | 게시 날짜로 필터링(연도 또는 전체 날짜) | `after:2026-10-01 AI news` |

### 가져오기: `POST /v1/tools/fetch`

| 파라미터 | 타입 | 필수 여부 | 설명 |
| - | - | - | - |
| `url` | string | ✓ | HTTP / HTTPS URL, 최대 8192자, 사용자 이름 또는 비밀번호 제외 |

## 응답 필드

**Search**는 `{"results": [...]}`을 반환하며, 각 결과에는 다음 항목이 포함됩니다:

| 필드 | 설명 |
| - | - |
| `title` / `url` | 제목 및 링크 |
| `snippet` | 사용자에게 표시하기 위한 약 100–200자의 짧은 요약 |
| `summary` | **모델에 전달하기 위한** 약 600–800자의 긴 요약 |
| `content` | 페이지 본문, `need_content`이(가) `false`일 때는 빈 문자열 |
| `rerank_score` | 관련성 점수 0–3, **1.5 이상이면 고품질** |
| `authority` | 사이트 권위도 0–4, `-1` = 알 수 없음, **3 이상이면 높은 권위도** |
| `date` | 발행 시간(UTC, RFC 3339), `null`일 수 있음 |
| `site_name` / `site_icon` | 사이트 이름 및 아이콘, `null`일 수 있음 |

**Fetch**는 `{"title": "...", "content": "..."}`을 반환하며, 여기서 `content`은 Markdown 본문입니다.

## 테스트 결과

2026-10-21 (UTC+8) 테스트 기준:

| 케이스 | 결과 | 과금 |
| - | - | - |
| 검색, `count=5` | ✅ 결과 5건, 1.8초 | 요청 1회 |
| 검색, `count=5` + `need_content` | ✅ 본문 포함 전체 5건, 32 KB 응답 | 요청 1회 |
| 검색, `count=50` | ✅ 결과 50건, 180 KB 응답, 3.0초 | 요청 1회 |
| 검색, `site:` 연산자 | ✅ 지정된 사이트의 결과만 반환 | 요청 1회 |
| 검색, `localization`를 IP로 설정 | ✅ | 요청 1회 |
| 검색, `count=51` / 빈 `query` | 구체적인 사유와 함께 400 반환 | 과금되지 않음 |
| Fetch, 일반 페이지 | ✅ 6,400자 Markdown, 1.6초 | 요청 1회 |
| Fetch, 404 페이지 / 존재하지 않는 도메인 / 사설 주소 | 404 `failed to fetch URL` | 과금되지 않음 |
| Fetch, 잘못된 형식의 URL | 400 | 과금되지 않음 |
| 동시 검색 20건 | ✅ 모두 200 반환, 2초 이내 완료 | 각 1회 요청 |

## 알아두어야 할 사항

> **"No results, no charge" rarely applies**
>
> 검색 엔진은 거의 항상 결과를 반환합니다. 테스트 시 무작위 문자열을 입력해도 3개의 결과가 반환되었으며 과금되었습니다.
> 마찬가지로 일부 사이트는 누락된 페이지에 대해 404 대신 홈페이지나 안내 페이지로 응답합니다(소프트 404). Fetch는 이를 성공적인 가져오기로 간주하여 과금합니다.
> 호출하기 전에 자체 코드에서 쿼리와 URL을 미리 검증하십시오.

> **모든 Fetch 실패는 404로 반환됩니다. HTTP 상태 코드에 따라 분기 처리하십시오**
>
> Fetch가 사용할 수 있는 콘텐츠를 가져올 수 없는 경우 대상 페이지가 404이든, 도메인이 존재하지 않든, 사설 주소이든, 사이트에서 접근을 거부했든 관계없이 항상 404 `failed to fetch URL`를 반환합니다.
> 오류 본문의 `type` 필드는 항상 `shell_api_error`이므로, \*\*HTTP 상태 코드와 `message`\*\*를 함께 사용하여 오류를 구분하십시오:
> 400인 경우 매개변수를 수정하고, 404인 경우 다른 URL을 시도하며, 429 / 5xx인 경우 잠시 기다린 후 다시 시도하십시오.

> **결과는 가공되지 않은 타사 웹 콘텐츠이므로 신뢰할 수 없는 입력으로 취급하십시오**
>
> Search 및 Fetch는 인터넷의 가공되지 않은 콘텐츠를 반환하므로 광고, 잘못된 정보 또는 AI를 겨냥한 prompt injection까지 포함될 수 있습니다.
> 결과를 모델에 전달할 때는 지시문이 아닌 외부 웹 콘텐츠임을 명시적으로 알려주십시오. 웹 페이지나 앱에 결과를 표시할 때는 HTML을 이스케이프 처리하십시오.

> **요청 제한**
>
> 업스트림 제한은 Search의 경우 100 QPS, Fetch의 경우 25 QPS이며, Fetch에는 대상 도메인별로 별도의 제한이 적용됩니다.
> 제한을 초과하면 429가 반환됩니다. 잠시 기다린 후 다시 시도하십시오. 동일한 사이트에서 여러 페이지를 가져올 때는 클라이언트 측에서 요청 속도를 조절하십시오.

## 자주 묻는 질문

> **OpenAI / Claude / Gemini 웹 검색과 어떻게 다릅니까?**
>
> 해당 기능들은 **채팅 모델의 내장 도구**입니다. 모델이 검색 여부 및 검색할 내용을 결정하며, 검색은 추가적인 도구 호출로 과금됩니다(OpenAI `web_search`은 1,000회 호출당 \$10).
> 본 페이지에서 제공하는 것은 **독립형 검색 API**입니다. 코드에서 언제 무엇을 검색할지 직접 결정하며, 단가는 이에 비해 극히 일부 수준에 불과하고, 검색 결과를 모든 모델에 전달할 수 있습니다.
> 내장 도구에 대한 자세한 내용은 [OpenAI 웹 검색](/ko/api-capabilities/openai/web-search), [Claude 웹 검색](/ko/api-capabilities/claude-web-search) 및 [Gemini 웹 검색](/ko/api-capabilities/gemini/web-search)을 참고하십시오.

> **Claude Code에서 사용할 수 있습니까?**
>
> 아직 직접 사용할 수는 없습니다. Claude Code 내부에서 모델이 시작하는 웹 검색은 본 API가 아닌 채팅 API의 서버 측 도구를 통해 진행되며,
> ClaudeCode 그룹의 키 역시 본 API를 호출할 수 없습니다. APIYI는 향후 릴리스에서 해당 클라이언트의 DeepSeek 모델을 위한 내장 검색을 지원할 예정입니다.

> **결과는 얼마나 최신입니까?**
>
> 결과에는 `date` 필드가 포함되어 있으며, `after:` 연산자를 사용하여 최신 콘텐츠만 가져올 수 있습니다. 테스트 결과, 당일 발행된 뉴스도 검색되었습니다.

## 관련 문서

> **[검색 플레이그라운드](/ko/api-capabilities/deepseek-search-fetch/search-api)**
>
> 파라미터 레퍼런스, 오류 코드 및 실시간 요청 패널

> **[가져오기 플레이그라운드](/ko/api-capabilities/deepseek-search-fetch/fetch-api)**
>
> 어떤 웹 페이지든 Markdown으로 가져옵니다

> **[DeepSeek V4 Flash](/ko/api-capabilities/deepseek-v4-flash/overview)**
>
> 함께 연동하여 사용할 수 있는 채팅 모델입니다

> **[충전 보너스](/ko/faq/recharge-promotions)**
>
> 충전 금액이 많을수록 보너스가 커지며, 고액 충전 고객에게는 공식 가격이 적용됩니다


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.