빠른 답변: DeepSeek Search API는 세 가지 코딩 도구 내에서만, 그리고 2026년 10월 31일 16:00 UTC까지만 무료입니다. Claude Code, Codex 또는 DeepSeek Harness가 서버 측에서 수행하는 Search 및 Fetch 호출은 그때까지 비용이 들지 않습니다. 그 이후에는, 그리고 엔드포인트에 대한 모든 직접 호출에 대해 엔드포인트당 성공한 요청 1,000건당 $0.75를 지불합니다. 실패한 호출, 빈 결과 및 시간 초과는 절대 청구되지 않습니다.
DeepSeek는 2026년 10월 17일 DeepSeek-V4.1-Flash-1017 릴리스와 함께 Search 및 Fetch API를 모든 사람에게 공개했습니다. 이들은 에이전트에게 쿼리에 대한 최신 웹 결과와 모든 페이지의 깔끔한 Markdown 복사본을 제공합니다. 이 가이드는 무료인 것, 기간 이후 비용, 속도 제한, 첫 요청, 그리고 Apidog CLI로 두 엔드포인트를 테스트하는 방법을 다룹니다.
아래의 모든 사실은 2026년 10월 28일에 확인한 DeepSeek의 Search & Fetch 가이드와 가격 페이지에서 가져온 것입니다.
DeepSeek Search API는 무료인가요?
예, 두 가지 제한이 있습니다: 어디에서 호출하는지, 그리고 언제인지입니다. DeepSeek 문서에 따르면 DeepSeek Harness, Claude Code 또는 Codex를 통해 이루어지는 서버 측 Search 및 Fetch 호출은 “현재 무료”입니다. 해당 호출에 대한 요청별 청구는 UTC+8 기준 2026년 11월 1일 00:00, 즉 2026년 10월 31일 16:00 UTC에 시작됩니다.
| 경로 | 2026년 10월 31일 16:00 UTC 이전 Search 및 Fetch 비용 | 이후 |
|---|---|---|
| DeepSeek API 키를 사용하는 Claude Code | $0 | 성공한 호출 1,000건당 $0.75 |
| DeepSeek API 키를 사용하는 Codex | $0 | 성공한 호출 1,000건당 $0.75 |
| DeepSeek Harness | $0 | 성공한 호출 1,000건당 $0.75 |
POST를 /v1/tools/search 또는 /v1/tools/fetch로 직접 호출 |
성공한 호출 1,000건당 $0.75 | 성공한 호출 1,000건당 $0.75 |
이것이 진정한 0달러 경로가 되지 못하게 하는 두 가지 문제가 있습니다:
- 여전히 자금이 있는 DeepSeek API 키가 필요합니다. 무료 기간은 검색 호출을 포함하며, 모델은 포함하지 않습니다. DeepSeek의 Claude Code 통합 페이지에 따르면 검색 결과를 요약할 때 추가 LLM 요청이 사용되며, 해당 토큰은 일반 모델 가격으로 청구됩니다.
- 이 기간은 서버 측 도구 호출만 포함합니다. 문서는 이를 세 가지 도구로 범위를 한정합니다. 자체 코드에서 엔드포인트를 호출하면 첫 성공한 요청부터 비용을 지불합니다.
무료 검색이 아니라 무료 DeepSeek 모델을 원한다면, DeepSeek이 무료인지에 대한 가이드에서 모든 경로를 나열하고, 무료 DeepSeek API 키에서 키 자체를 다룹니다.
DeepSeek Search 및 Fetch API의 기능
DeepSeek Search API는 쿼리를 받아 구조화된 웹 결과를 반환합니다: 제목, URL, 스니펫, 모델 지향적인 더 긴 요약, 선택적 전체 페이지 콘텐츠 필드, 관련성 점수 및 권위 점수입니다. DeepSeek Fetch API는 하나의 URL을 받아 해당 페이지의 제목과 콘텐츠를 Markdown으로 반환합니다. 함께 사용하면 에이전트에게 두 번의 호출로 검색과 읽기를 제공합니다.
연구 에이전트는 보통 한 번 검색한 다음 두세 페이지를 가져오며, 각각은 기간 이후 별도의 청구 가능한 호출입니다. 검색은 연산자를 지원합니다: site:, -site:, "phrase", -term, lang:en,ja, after: 및 before:.
이를 무료 웹 검색 API, Claude 웹 검색 API 및 Perplexity Search API 모음에서 다른 옵션과 비교할 수 있습니다.
무료 기간 이후 DeepSeek Search API 가격
기간이 종료되면 두 엔드포인트 모두 동일한 방식으로 청구됩니다:
| Search API | Fetch API | |
|---|---|---|
| 가격 | 성공한 요청 1,000건당 $0.75 | 성공한 요청 1,000건당 $0.75 |
| 호출당 | $0.00075 | $0.00075 |
| 청구 시점 | 비어 있지 않은 results 배열과 함께 HTTP 200 |
페이지 콘텐츠와 함께 HTTP 200 |
| 청구되지 않음 | 실패한 요청, 빈 결과, 시간 초과 | 실패한 요청, 시간 초과 |
count가 가격을 변경하나요? |
아니요 | 해당 없음 |
요금은 DeepSeek 잔액에서 차감되며, 가격 페이지에 따르면 두 종류의 잔액이 모두 있을 때 충전된 잔액보다 부여된 잔액이 먼저 사용됩니다.
하루에 200개의 작업을 실행하고 각 작업에 하나의 검색과 세 개의 가져오기가 있는 연구 에이전트에 대한 간단한 계산:
- 200회 검색 x $0.00075 = $0.15
- 600회 가져오기 x $0.00075 = $0.45
- 합계: 하루 $0.60, 한 달 약 $18, 모델 토큰 제외
count가 가격을 변경하지 않으므로, 페이지를 나누는 대신 한 번의 호출로 최대 50개의 결과를 요청하세요. 모델 측면에서 deepseek-flash는 백만 입력 토큰당 $0.15(캐시 미스, 오프피크)이고 백만 출력 토큰당 $0.60이며, 피크 시간에는 두 배가 됩니다. DeepSeek V4.1 Flash 가격을 참조하세요.
DeepSeek Search API 속도 제한
일부 타사 문서에서는 5 QPS 제한을 언급합니다. DeepSeek 자체 가이드는 다른 숫자를 제시하며, 이 숫자를 기준으로 계획해야 합니다:
- Search: 초당 100 쿼리
- Fetch: 초당 25 쿼리, 그리고 값이 공개되지 않은 도메인별 제한
제한은 계정당 적용되며 모든 API 키에 걸쳐 적용되고 모델 동시성과는 별개입니다. Search와 Fetch는 독립적으로 측정되므로 가져오기 버스트가 검색 예산을 소모하지 않습니다. 초과하면 HTTP 429를 반환합니다.
도메인별 Fetch 제한에 주의하세요: 하나의 문서 사이트에서 20페이지를 가져오는 에이전트는 25 QPS보다 훨씬 낮은 속도에서도 제한에 도달할 수 있습니다. 동일 도메인 가져오기 사이에 간격을 두고 429를 백오프로 재시도하세요.
엔드포인트 및 첫 번째 DeepSeek Search API 호출
두 엔드포인트 모두 POST이며 베어러 토큰을 사용하고 JSON을 받습니다:
- Search:
https://api.deepseek.com/v1/tools/search - Fetch:
https://api.deepseek.com/v1/tools/fetch
검색 요청 필드
| 필드 | 유형 | 필수 | 기본값 | 비고 |
|---|---|---|---|---|
query |
string | 예 | 없음 | 1~128자, 연산자 허용 |
count |
integer | 아니요 | 10 | 1~50 |
ori_question |
string | 아니요 | 없음 | 사용자의 원래 질문, 1~128자 |
localization |
string | 아니요 | "" |
결과를 현지화할 IP 주소 |
need_content |
boolean | 아니요 | false | false일 때 content는 비어 있음 |
문서에서 가져온 검색 요청:
curl https://api.deepseek.com/v1/tools/search \
-H "Authorization: Bearer $DEEPSEEK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "DeepSeek V4 release", "count": 5, "need_content": true}'
results 배열의 각 항목에는 title, url, snippet, summary, content, site_name, site_icon, date(UTC RFC 3339 또는 null), rerank_score 및 authority가 포함됩니다. 가져오기 전에 두 가지로 필터링하세요:
rerank_score는 0에서 3까지입니다. DeepSeek은 1.5 이상을 고품질로 간주합니다.authority는 0에서 4까지이며, 알 수 없는 경우 -1입니다. 3 이상은 매우 권위 있는 출처를 의미합니다.
가져오기 요청은 하나의 필드 url을 받습니다(HTTP 또는 HTTPS, 최대 8,192자, 내장된 사용자 이름이나 비밀번호 없음):
curl https://api.deepseek.com/v1/tools/fetch \
-H "Authorization: Bearer $DEEPSEEK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/article"}'
이것은 title(비어 있을 수 있음)과 Markdown 형식의 content를 반환합니다.
발생할 수 있는 오류
| 코드 | 의미 | 재시도? |
|---|---|---|
| 400 | 잘못된 헤더, 본문 또는 필드 값 | 먼저 요청 수정 |
| 401 | 키 누락 또는 유효하지 않음 | 아니요 |
| 402 | 잔액 부족 | 충전 후 재시도 |
| 403 | 보안 정책으로 인해 Fetch 차단됨 | 아니요 |
| 404 | Fetch가 사용 가능한 콘텐츠를 가져오지 못함 | 아니요 |
| 408 / 429 / 5xx | 시간 초과, 속도 제한, 서버 오류 | 예, 대기 후 |
오류 본문은 OpenAI 형식을 따릅니다: message, type, param(항상 null) 및 code.
Claude Code 또는 Codex에서 Search 사용 vs 직접 호출
무료 기간은 코딩 도구가 대신 호출할 때만 적용되므로 설정이 청구서를 결정합니다.
Claude Code. Claude Code를 DeepSeek의 Anthropic 호환 엔드포인트로 지정하면 DeepSeek의 API가 서버 측에서 Web Search 도구를 실행합니다. DeepSeek 페이지의 핵심 변수:
export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
export ANTHROPIC_AUTH_TOKEN=<your DeepSeek API key>
export ANTHROPIC_MODEL=deepseek-flash[1m]
모델 변수를 몇 개 더 설정하는 전체 블록을 DeepSeek 페이지에서 복사하세요.
Codex. Codex의 내장 웹 검색은 DeepSeek의 Codex 통합 페이지에 따라 deepseek-v4-pro에서만 작동합니다. 설정 스크립트는 기본적으로 웹 검색을 끄므로 ~/.codex/config.toml에 다음 두 줄을 설정하고 재시작하세요:
model = "deepseek-v4-pro"
web_search = "live"
트레이드오프: deepseek-v4-pro는 deepseek-flash보다 토큰당 비용이 더 높습니다.
직접 호출. 자체 에이전트를 구축하거나 count, need_content 및 연산자를 직접 제어하려면 엔드포인트를 직접 호출하세요. 첫 성공한 호출부터 비용을 지불합니다. 코딩하는 동안 정보를 찾는 에이전트만 원한다면 기간 동안 Claude Code 또는 Codex를 사용하세요.
Apidog CLI로 코딩 에이전트가 DeepSeek Search API를 테스트하도록 하기
Search와 Fetch를 제품에 연결하기 전에 인증, 응답 형식 및 오류가 문서에 설명된 대로 작동하는지 확인하세요. 코딩 에이전트가 Apidog CLI로 이러한 검사를 구축하고 실행할 수 있으므로 테스트가 팀이 CI에서 다시 실행하는 프로젝트에 포함됩니다.
한 번 설정하세요:
npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_APIDOG_TOKEN>
npx -y skills add https://apidog.com # pick your agent when prompted
그런 다음 Claude Code, Codex 또는 사용하는 에이전트에게 하나의 프롬프트를 제공하세요:
In Apidog project <projectId>, add the DeepSeek endpoints POST /v1/tools/search
and POST /v1/tools/fetch with base URL https://api.deepseek.com and bearer auth
from the DEEPSEEK_API_KEY variable. Create test cases that assert: search returns
200 with a results array whose rerank_score values are between 0 and 3; fetch on
https://example.com returns 200 with non-empty content; a bad key returns 401.
Run them against the deepseek environment and summarize any failures.
에이전트는 각 페이로드 스키마를 읽고 JSON을 검증한 다음 테스트를 작성하고 실행합니다:
apidog environment create deepseek --project <projectId> --base-url https://api.deepseek.com
apidog cli-schema get endpoint-create
apidog cli-schema validate endpoint-create --file search-endpoint.json
apidog endpoint create --project <projectId> --file search-endpoint.json
apidog cli-schema get test-case-create
apidog test-case create --project <projectId> --file search-case.json
apidog run --test-case <caseId> --project <projectId> -e <envId> -r cli,json
각 전체 실행은 기간 이후 두 번의 청구 가능한 호출(검색 한 번, 가져오기 한 번)을 수행하므로 비용은 $0.0015입니다. 401 검사는 실패한 요청이 청구되지 않으므로 비용이 들지 않습니다. 동일한 apidog run ... -r junit 줄은 CI/CD에서 Apidog CLI 실행에 표시된 대로 파이프라인에 포함할 수 있습니다. Claude Code가 에이전트라면 Claude Code의 Apidog CLI에서 스킬 설치를 안내합니다.
Apidog의 무료 플랜은 최대 4명의 사용자를 지원하므로 소규모 팀이 프로젝트와 테스트 기록을 공유할 수 있습니다.
FAQ
10월 31일 이후 DeepSeek Search API는 무료인가요? 아니요. 2026년 10월 31일 16:00 UTC부터 Claude Code, Codex 및 DeepSeek Harness를 통한 Search 및 Fetch 호출은 직접 호출과 마찬가지로 성공한 요청 1,000건당 $0.75입니다.
DeepSeek Fetch API는 무료인가요? Search와 동일한 조건에서만 무료입니다: Claude Code, Codex 또는 DeepSeek Harness가 마감 전에 서버 측에서 호출하면 무료이고, 그 이후에는 성공한 요청 1,000건당 $0.75입니다.
Claude Code에서 무료 검색을 사용하려면 DeepSeek API 키가 필요한가요? 예. Claude Code는 https://api.deepseek.com/anthropic을 통해 DeepSeek API 키로 실행되어야 하며, 결과를 요약하는 데 사용되는 모델 토큰은 정상적으로 청구됩니다.
DeepSeek Search API 속도 제한은 무엇인가요? DeepSeek 가이드에는 계정당 Search 100 QPS, Fetch 25 QPS, 그리고 Fetch에 대한 공개되지 않은 도메인별 제한이 나와 있습니다. 초과하면 HTTP 429를 반환합니다.
검색이 아무것도 반환하지 않으면 요금이 청구되나요? 아니요. 빈 결과, 실패한 요청 및 시간 초과는 청구되지 않습니다. Search는 비어 있지 않은 results 배열과 함께 HTTP 200인 경우에만 청구됩니다.
더 많은 결과를 요청하면 비용이 더 드나요? 아니요. count 필드(1~50)는 가격을 변경하지 않으므로 50개 결과 검색 한 번은 5개 결과 검색과 동일한 비용이 듭니다.