DeepSeek Search·Fetch API 사용법｜Python 웹 검색·페이지 수집·요금·오류 해결

DeepSeek Search API는 검색어로 웹페이지를 찾고, Fetch API는 URL 한 개의 본문을 Markdown으로 가져옵니다. 검색 결과와 원문을 프로그램에서 다루려면 두 기능을 구분해야 합니다. 직접 호출은 각각 성공 요청 1,000회당 0.75달러이며, 일부 도구 경유 호출의 한시 무료 조건과는 다릅니다.

딥시크 검색 API 사용법을 찾고 있다면 호출 준비 → Search 결과 확인 → 필요한 URL만 Fetch → 원문·날짜 검수 → 비용 확인 순서로 진행하세요. 이 글은 웹·앱의 검색 버튼 설정이 아니라 개발자용 Search·Fetch API를 설명합니다.

공식 문서 확인 기준: 2026년 10월 19일. 아래 코드는 공식 요청·응답 규격을 바탕으로 구성한 예제이며 실제 API 호출 결과나 한국어 검색 품질을 측정한 후기는 아닙니다. 요금과 이용 조건은 사용 시 공식 문서를 다시 확인하세요.

목차

• Search·Fetch 차이
• API 키와 호출 준비
• Search 호출·응답 읽기
• Fetch로 Markdown 가져오기
• 검색에서 원문 검수까지
• 요금·무료 조건·비용 계산
• 401·404·429 오류 대응
• 자주 묻는 질문
• 공식 자료와 관련 글

1. Search API와 Fetch API의 차이

구분	Search	Fetch
입력	검색어 query	페이지 주소 url
목적	관련 페이지 찾기	선택한 페이지 읽기
응답	results 배열	title·content 객체
경로	/v1/tools/search	/v1/tools/fetch

두 API는 https://api.deepseek.com에 POST 요청을 보내는 독립 API입니다. Search에서 need_content=true를 설정하면 검색 결과에 본문이 포함될 수 있으므로, 이미 충분한 본문을 얻었다면 모든 결과에 Fetch를 다시 호출할 필요는 없습니다.

Fetch의 응답 전체가 Markdown 파일인 것은 아닙니다. JSON 안의 content 값이 Markdown 문자열입니다. 근거: Search 레퍼런스, Fetch 레퍼런스.

2. API 키와 호출 환경 준비하기

1. DeepSeek API 플랫폼에서 API 키와 계정 잔액을 확인합니다.
2. 키를 실행 환경의 DEEPSEEK_API_KEY 환경변수에 설정합니다.
3. 요청 헤더에 Authorization: Bearer API키와 Content-Type: application/json을 넣습니다.
4. 처음에는 검색 결과 수를 작게 설정하고 응답과 비용을 확인합니다.

이 글의 curl 예제는 macOS·Linux 또는 Bash 계열 셸을 기준으로 합니다. Python 예제는 환경변수 설정과 requests 설치가 필요합니다. Windows PowerShell에서는 curl 명령의 별칭과 줄바꿈 문법이 다를 수 있으므로 Python 예제를 이용하면 셸 문법 혼동을 줄일 수 있습니다.

python -m pip install requests

실제 API 키를 Blogger HTML·브라우저 JavaScript·공개 저장소에 넣지 마세요. 블로그에는 설명용 예제만 게시하고, 호출은 키를 보호할 수 있는 서버나 로컬 환경에서 실행합니다. 이미 키가 공개됐다면 발급 서비스에서 폐기·재발급하고 연결 환경도 갱신해야 합니다.

API 키 유출 경고가 발생했을 때 대응 순서 확인하기

3. Search API 호출과 검색 결과 해석

curl로 공식 문서 검색하기

curl --fail-with-body https://api.deepseek.com/v1/tools/search \
  -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "DeepSeek Search Fetch site:api-docs.deepseek.com",
    "count": 3,
    "need_content": true
  }'

위 검색어는 site:로 공식 문서 도메인을 지정한 예시입니다. 특정 순위나 결과 수를 보장하는 검색식은 아닙니다. API는 site:, -site:, 따옴표 구문 등 검색 연산자를 지원합니다.

주요 요청값 확인하기

필드	조건·의미
query	필수. 1~128 Unicode 문자, 공백만으로 구성 불가
count	결과 수 설정. 기본 10, 허용 범위 1~50
need_content	본문 포함 요청. 기본 false
ori_question	선택. 검색을 유발한 원래 질문, 1~128 문자. null은 미제공 취급
localization	지역화에 사용하는 선택 IP 주소. 언어 코드 입력란이 아님

Python으로 빈 결과와 빈 본문 구분하기

import os
import requests

api_key = os.environ["DEEPSEEK_API_KEY"]
headers = {"Authorization": f"Bearer {api_key}"}

response = requests.post(
    "https://api.deepseek.com/v1/tools/search",
    headers=headers,
    json={
        "query": "DeepSeek Search Fetch site:api-docs.deepseek.com",
        "count": 3,
        "need_content": True,
    },
    timeout=30,
)
response.raise_for_status()
results = response.json().get("results", [])

if not results:
    print("검색은 완료됐지만 일치 결과가 없습니다.")

for item in results:
    print("제목:", item.get("title", ""))
    print("URL:", item.get("url", ""))
    print("요약:", item.get("summary", ""))
    print("발표일:", item.get("date") or "확인 필요")

    content = item.get("content", "")
    if content:
        print("본문 일부:", content[:500])
    else:
        print("본문 없음: 필요하면 해당 URL을 Fetch로 확인하세요.")

snippet은 짧은 요약, summary는 더 긴 요약, content는 확보된 페이지 본문입니다. 요약이 있다고 원문 전체를 읽은 것은 아닙니다. 날짜가 null이면 게시일을 추정하지 말고 원문에서 확인하세요.

need_content=false일 때 빈 content는 정상입니다. true여도 본문을 확보하지 못하면 비어 있을 수 있습니다. 반면 results=[]는 일치 검색 결과가 없다는 뜻입니다. 관련성·권위성 점수 역시 공급자의 평가값이며 사실 정확성을 보증하지 않습니다. 근거: Search 요청·응답 규격.

4. Fetch API로 웹페이지 Markdown 가져오기

읽을 페이지 주소를 알고 있거나 Search 결과에서 추가 확인할 원문을 골랐다면 Fetch를 사용합니다. 다음은 공개된 DeepSeek 발표문을 지정한 예제이며, 특정 페이지의 수집 성공을 보장하지 않습니다.

import os
import requests

response = requests.post(
    "https://api.deepseek.com/v1/tools/fetch",
    headers={
        "Authorization": f"Bearer {os.environ['DEEPSEEK_API_KEY']}"
    },
    json={
        "url": "https://api-docs.deepseek.com/news/news261017/"
    },
    timeout=30,
)
response.raise_for_status()
page = response.json()

print("제목:", page.get("title", ""))
print(page.get("content", ""))

requests의 json= 인자가 JSON 직렬화와 Content-Type 설정을 처리합니다. 예제의 30초는 클라이언트에서 지정한 대기 시간이며 DeepSeek의 응답시간 보장이 아닙니다.

Fetch URL은 host가 있는 HTTP·HTTPS 주소여야 하며 최대 8,192자입니다. URL에 사용자명·비밀번호를 포함하면 안 됩니다. 페이지 제목은 확인되지 않을 때 빈 문자열일 수 있습니다. 근거: Fetch 공식 레퍼런스.

5. 검색에서 원문 검수까지 연결하는 순서

1. 질문을 좁힙니다. 제품명·기능명·확인할 조건을 검색어에 넣습니다.
2. 공식 출처를 우선합니다. 필요하면 site:로 기관·사업자 도메인을 지정합니다.
3. 본문 확보 여부를 봅니다. Search content가 충분한지 확인하고 필요한 URL만 Fetch합니다.
4. 원문 날짜와 적용일을 대조합니다. 발표일·시행일·무료 종료일을 분리합니다.
5. 주장과 근거를 연결합니다. URL·제목·확인 날짜와 핵심 근거를 함께 기록합니다.
6. 빠진 자료를 표시합니다. 본문에 첨부파일이나 이미지로만 제시된 조건은 별도 확인합니다.

Markdown 추출만으로 원문 이미지·표·첨부자료의 모든 정보를 확보했다고 판단하면 안 됩니다. 특히 요금·정책·지원 조건처럼 날짜에 따라 달라지는 정보는 원문을 직접 대조한 뒤 활용하세요.

업무 자동화에 연결할 때도 먼저 수집 결과를 검수한 뒤 다음 단계로 전달하세요. Apps Script·Webhook을 이용하는 흐름의 기본 구조는 아래 글에서 확인할 수 있습니다.

Google Workspace Studio의 Apps Script·Webhook 연결법 확인하기

6. 직접 API 요금과 한시 무료 조건

공식 요금표는 Search·Fetch를 성공 요청 횟수 기준으로 각각 과금합니다. 생성 모델의 입력·출력 토큰 비용은 별도입니다.

이용 경로	확인된 과금 기준
Search 직접 호출	성공 1,000회당 0.75달러
Fetch 직접 호출	성공 1,000회당 0.75달러
지정 도구의 서버 측 경유 호출	DeepSeek API 이용 조건에 따른 한시 무료. 아래 시작 시각부터 과금
생성 모델 사용	모델별 입력·출력 토큰 요금 별도

한시 무료는 DeepSeek API를 DeepSeek Harness·Claude Code·Codex에서 사용할 때 발생하는 서버 측 Search·Fetch 호출에 관한 안내입니다. 이 도구들의 모든 이용 요금이나 직접 API 호출까지 무료라는 의미가 아닙니다.

경유 호출 과금 시작: 2026년 10월 31일 16:00 UTC
한국시간: 2026년 11월 1일 오전 1시
기준: 공식 발표·공식 요금표.

성공 과금은 HTTP 200이면서 실제 결과가 있는 요청을 기준으로 합니다. Search는 비어 있지 않은 results, Fetch는 페이지 본문을 반환해야 합니다. 실패·검색 결과 없음·시간 초과는 과금하지 않으며, count를 늘려도 요청 한 번의 단가는 달라지지 않습니다. 근거: 공식 가이드의 과금 규칙.

검색 1회·Fetch 3회 비용 계산

직접 호출에서 질문 하나당 Search 1회와 Fetch 3회가 모두 과금 대상 성공 요청이라면, 질문 1,000개에 Search 1,000회와 Fetch 3,000회가 발생합니다.

Search: 1,000 ÷ 1,000 × $0.75 = $0.75
Fetch:  3,000 ÷ 1,000 × $0.75 = $2.25
합계: $3.00

이는 요청 구조를 설명하는 가상 계산입니다. 생성 모델 요금·환전 비용·세금·추가 호출은 반영하지 않았습니다. 결과 3개를 받는 Search 한 번과 Fetch 세 번은 서로 다른 요청이므로 분리해 계산하세요.

7. 401·404·429 오류가 발생했을 때

상태	확인할 원인	대응
400	JSON·헤더·필드 값 오류	query 길이·count 범위·url 확인
401	키 누락·유효하지 않은 키	환경변수·Bearer 헤더 확인
402	계정 잔액 부족	잔액 확인·충전 후 재시도
403	Fetch 안전정책 거부	URL·허용 범위 확인
404	Fetch가 사용 가능한 본문을 확보하지 못함	원본 주소·접근 정책·콘텐츠 형식 확인
429	호출 속도 제한 초과	동시 요청 축소·대기 후 재시도
408·5xx	요청 읽기 시간 초과·서버 오류 등	대기 후 제한된 횟수로 재시도

Fetch의 404가 곧 원본 사이트의 404를 뜻하지는 않습니다. 사이트 정책 차단, 지원하지 않는 형식, 추출 가능한 Markdown 부재 등도 원인이 될 수 있습니다. 원본 페이지를 직접 열어 확인하고 접근이 허용된 다른 공식 자료를 찾으세요.

Search·Fetch의 호출 속도 제한은 계정 단위이며 각각 독립적으로 적용됩니다. Fetch에는 대상 도메인별 제한도 있습니다. 같은 계정의 키만 바꾸는 방식으로 계정 제한을 해결하려 하지 말고 전체 호출량을 조절하세요. 최신 한도는 공식 가이드의 제한 항목을 확인하세요.

공식 가이드는 408·429·5xx에 대기 후 재시도하도록 안내합니다. 402는 잔액을 해결한 뒤 재시도하고, 그 밖의 4xx는 요청을 수정하지 않은 채 반복하지 않습니다. 프로그램에서는 재시도 횟수·전체 대기 시간을 제한하고 실패 내역을 기록하세요.

8. 자주 묻는 질문

Search를 호출하면 AI가 최종 답변까지 만들어 주나요?

이 글의 독립 Search API는 구조화된 검색 결과를 반환합니다. 최종 답변 생성이 필요하면 확보한 자료를 모델에 전달하는 별도 흐름을 구성하고 생성 모델 비용도 계산해야 합니다.

count를 50으로 설정하면 50회 과금되나요?

아닙니다. count는 요청 한 번에서 받을 검색 결과 수 설정입니다. 결과 수를 바꿔도 Search 한 번의 단가는 같으며, 이후 Fetch를 호출하면 해당 요청은 별도로 계산합니다.

한국어 검색 정확도는 어느 정도인가요?

이 글에서는 한국어 품질을 실측하지 않았습니다. 실제 업무 질문으로 공식 출처 포함 여부·최신성·누락·본문 확보 여부를 확인한 뒤 도입 여부를 판단하세요. 다국어 지원 안내만으로 국내 검색 품질을 단정할 수는 없습니다.

사이트에서 읽히지 않는 자료도 Fetch로 가져올 수 있나요?

모든 사이트·형식의 수집을 보장하지 않습니다. 대상 사이트의 가용성과 접근 정책, 추출 가능한 본문 유무에 영향을 받습니다. 로그인이 필요한 자료나 정책으로 제한된 페이지를 읽을 수 있다고 가정하지 마세요.

공식 예제와 같은 결과가 나오지 않으면 오류인가요?

검색 결과는 시점과 질의에 따라 달라질 수 있습니다. 먼저 HTTP 상태와 results 유무를 확인하고, 본문 확보 여부를 따로 확인하세요. 예제의 문장·순위와 다르다는 이유만으로 호출 실패로 판단하지 않습니다.

9. 시작 전 확인사항과 공식 자료

• 실제 API 키는 환경변수로 관리했는가?
• Search 결과와 원문 content를 구분했는가?
• 필요한 URL만 Fetch하도록 구성했는가?
• 직접 API·도구 경유 호출·모델 비용을 나눴는가?
• 빈 결과·404·429를 구분하고 재시도 상한을 정했는가?
• 원문 날짜와 주요 조건을 사람이 확인했는가?

• DeepSeek 2026년 10월 17일 공식 발표 — Search·Fetch 공개와 경유 호출 과금 시작.
• DeepSeek 변경기록 — 검색 API 공개와 모델 갱신 구분.
• Search API 레퍼런스 — 검색 요청·응답 필드.
• Fetch API 레퍼런스 — URL 조건·Markdown 응답.
• Search·Fetch 공식 가이드 중국어판 — 인증·오류·성공 과금·호출 제한.
• DeepSeek 공식 요금표 — 직접 API 단가와 모델 요금.

함께 보면 좋은 글

• GitHub Secret Scanning Supabase·Lovable 키 탐지｜유출 경고 대응법
• Google Workspace Studio 자동화｜Apps Script·Webhook·Slack·Jira 연결법
• GitHub Copilot JetBrains 업데이트｜MCP 자동 시작 끄기·기본 모델·IDE 지원 종료