딥시크 검색·가져오기 API, 성공한 요청만 과금

딥시크(DeepSeek)가 AI 에이전트와 검색증강생성(RAG·외부 자료를 찾아 답변에 활용하는 방식) 서비스에 실시간 웹 자료를 공급하는 검색·가져오기 API를 공개했다. 검색어로 웹페이지를 찾고, 선택한 페이지의 내용을 마크다운으로 받아오는 두 기능이다. 해커뉴스에 소개된 가격은 성공한 요청 1,000건당 0.75달러다. 다만 실제 비용과 활용성은 결과가 나온 요청만 과금하는 규칙, 사이트별 접근 제한, 기존 도구 연동 방식까지 함께 봐야 드러난다.

핵심요약

  • 딥시크의 검색 API는 웹페이지를 구조화된 결과로 돌려주고 가져오기 API는 단일 페이지의 내용을 마크다운으로 반환해, 에이전트가 최신 웹 자료를 읽는 경로를 제공한다.
  • 검색과 가져오기는 토큰 수나 결과 개수가 아니라 결과가 있는 HTTP 200 요청을 기준으로 과금되므로, 빈 검색 결과와 실패한 요청에는 요금이 붙지 않는다.
  • 딥시크 하네스, 클로드 코드, 코덱스에서 발생하는 서버 측 도구 호출은 현재 무료이며, 이 호출에 대한 요청별 과금은 2026년 11월 1일 베이징 시간 0시에 시작된다.
  • 검색과 가져오기는 계정별 호출 한도가 따로 적용되고 가져오기는 도메인별 한도도 있어, 대량 수집에서는 가격과 함께 처리량을 살펴야 한다.
  • 토론에서는 저렴한 요청 가격을 반기는 의견과 함께 자체 검색 도구의 비용, 유료 서비스의 안정성, 실제 페이지 접근 가능성을 따져야 한다는 의견이 나왔다.

검색은 목록, 가져오기는 본문

딥시크가 공개한 기능은 웹을 읽는 작업을 두 단계로 나눈다. 검색 API는 질의를 받아 관련 웹페이지를 찾고, 제목과 주소 등을 담은 구조화된 결과를 돌려준다. 딥시크는 이 검색에 자체 검색 엔진을 사용한다고 설명한다. 가져오기 API는 지정한 웹페이지 하나를 읽어 제목과 본문을 반환하며, 본문 형식은 마크다운이다.

두 기능은 모두 JSON으로 요청과 응답을 주고받는 API다. 개발자는 검색 결과에서 필요한 페이지를 고른 뒤 가져오기로 본문을 읽는 흐름을 만들 수 있다. 검색 결과를 곧바로 답변의 단서로 쓰거나, 페이지 본문을 읽어 더 자세한 내용을 확인하는 식이다. 다만 검색이 찾아낸 페이지라고 해서 가져오기가 언제나 성공하는 것은 아니다. 딥시크는 대상 사이트의 접속 가능 상태와 접근 정책이 가져오기 결과에 영향을 준다고 명시했다.

이 구분은 AI 에이전트가 웹을 다룰 때 중요하다. 검색 목록에 실린 짧은 설명과 페이지 본문은 담고 있는 정보의 양이 다르기 때문이다. 목록만으로 충분한 질문에는 검색 결과를 쓰고, 내용을 확인해야 하는 작업에는 별도의 가져오기 요청을 보낼 수 있다. 반대로 많은 페이지의 본문을 한꺼번에 읽으려면 그만큼 요청과 사이트 접근 조건을 관리해야 한다.

기존 API 키로 보내는 JSON 요청

인증 방식은 딥시크 API와 같다. 요청 헤더에 API 키를 담는 베어러 인증(키를 헤더에 넣어 사용 권한을 확인하는 방식)을 쓰고, JSON 형식임을 표시한다. 문서의 예시는 같은 기본 주소인 https://api.deepseek.com 아래에서 검색에는 /v1/tools/search, 가져오기에는 /v1/tools/fetch를 사용한다. 두 API를 위해 별도의 인증 체계를 익혀야 하는 구조는 아니다.

검색 요청에는 검색어를 뜻하는 query, 돌려받을 결과 개수인 count, 본문 내용의 필요 여부를 나타내는 need_content가 예시로 제시됐다. 가져오기 요청은 읽으려는 페이지의 url을 보낸다. 문서는 요청 본문에 정의되지 않은 필드를 넣으면 오류를 내는 대신 무시한다고 설명한다. 개발자는 오타를 낸 필드가 조용히 넘어갈 수 있다는 점도 염두에 둬야 한다.

검색어에는 연산자도 함께 넣을 수 있다. 문서는 사이트를 지정하는 site:, 언어를 가리키는 lang:, 날짜 조건인 after:, 조건을 결합하는 OR를 하나의 질의에 섞은 예시를 보여준다. 딥시크는 이런 검색 문법을 유지한 채 질의를 전달한다고 설명한다. 단순히 문장 하나를 보내는 방식보다 검색 범위를 세밀하게 좁히는 데 쓸 수 있는 입력 형태다.

결과 배열과 마크다운 응답

검색이 성공하면 HTTP 200 상태와 함께 results 배열이 돌아온다. 검색에 맞는 페이지가 없는 정상적인 요청은 오류가 아니라 빈 배열을 반환한다. 문서의 응답 예시에는 페이지 제목과 URL 외에 짧은 발췌문, 요약, 본문, 사이트 이름, 날짜, 재정렬 점수 등이 나타난다. 이 예시에 등장하는 기사 제목과 날짜는 응답 형식을 보여주기 위한 값이지, 해당 제품 출시를 알리는 발표가 아니다.

가져오기 응답 예시는 더 단순하다. 페이지의 title과 마크다운 형식의 content가 들어 있다. 검색 결과에서 얻은 URL을 다시 가져오기에 넘겨 본문을 읽는 흐름을 생각할 수 있다. 하지만 이 API가 모든 웹페이지를 읽어 준다는 뜻은 아니다. 대상 사이트가 열려 있는지, 어떤 접근 정책을 적용하는지에 따라 본문을 얻지 못할 수 있다.

오류 형식은 오픈AI(OpenAI)와 호환되는 형태로 제시됐다. 예를 들어 count가 허용 범위인 1~50을 벗어나면 오류 메시지와 유형, 코드가 담긴 객체를 받는다. 오류 객체의 param 값은 항상 null이라고 문서는 설명한다. 또 검색과 가져오기는 읽기 전용 기능이다. 웹에서 자료를 찾고 받아오는 도구이지, 대상 페이지를 수정하는 도구는 아니다.

빈 결과에는 요금을 매기지 않는다

해커뉴스에 올라온 제목은 성공한 요청 1,000건당 0.75달러라는 가격을 앞세운다. 딥시크 문서가 설명하는 과금 단위는 토큰 수나 반환된 검색 결과 수가 아닌 ‘요청’이다. count를 바꿔 결과 개수를 조절해도 요청당 가격에는 영향을 주지 않는다. 따라서 비용을 계산할 때는 받은 결과의 총 개수보다 어떤 요청이 과금 대상이 되는지 살펴야 한다.

과금 대상은 HTTP 200을 반환하면서 실제 결과까지 만든 요청이다. 검색은 results 배열이 비어 있지 않아야 하고, 가져오기는 페이지 내용을 반환해야 한다. 검색 결과가 비어 있거나 요청이 실패하거나 시간이 초과됐다면 요금을 청구하지 않는다. 응답 상태가 200이라는 조건만이 아니라, 사용할 수 있는 결과가 있었는지가 기준에 들어간다.

문서는 기존 도구를 통한 호출도 별도로 짚는다. 딥시크 하네스(DeepSeek Harness), 클로드 코드(Claude Code), 코덱스(Codex)에서 딥시크 API를 사용하면 서버 측 도구 호출이 이미 검색·가져오기 API를 이용한다. 이 호출은 현재 무료이며, 2026년 11월 1일 베이징 시간 0시부터 요청별 과금이 시작된다. 직접 API를 호출하는 경우와 기존 도구에서 발생하는 서버 측 호출을 구분해 사용량을 확인해야 하는 이유다.

두 API의 호출 한도는 따로 계산된다

검색과 가져오기에는 계정별 호출 속도 제한이 각각 적용된다. QPS(초당 요청 수)는 어떤 API 키를 썼는지가 아니라 계정을 기준으로 계산하며, 모델 요청의 동시 실행 한도와도 별개다. 검색 트래픽이 가져오기 한도를 소모하지 않고, 가져오기 트래픽도 검색 한도를 소모하지 않는다. 한 작업에서 검색과 페이지 읽기를 연달아 수행한다면 두 제한을 따로 고려해야 한다.

가져오기에는 계정 한도에 더해 도메인별 QPS 제한이 있다. 같은 사이트의 여러 페이지를 빠르게 읽는 작업은 계정에 여유가 있어도 해당 도메인의 한도에 걸릴 수 있다. 한도를 넘긴 요청에는 HTTP 429가 반환된다. 검색을 여러 차례 하고 많은 페이지를 뒤따라 읽는 작업이라면, 요청당 가격만으로 실제 처리 흐름을 판단하기 어려운 지점이다.

오류별 대응도 문서에 나뉘어 있다. HTTP 408, 429 또는 5xx 오류라면 기다렸다가 다시 시도하라고 안내한다. HTTP 402가 나오면 계정 잔액을 채운 뒤 재시도해야 한다. 다른 4xx 오류는 요청을 바꾸지 않은 채 반복하지 말라는 설명이다. 실패한 요청에 과금하지 않는 규칙과 별개로, 재시도 방식은 작업을 얼마나 매끄럽게 이어갈 수 있는지에 영향을 준다.

커뮤니티 의견

한 사용자는 에이전트가 검색을 주도하게 되면 검색 API의 가격이 장차 0 아래로 내려갈 수도 있다고 예상했다. 검색 제공업체가 자사 API를 쓰도록 오히려 비용을 지급하고, 그 대가로 어떤 정보가 노출되는지 영향력을 확보할 수 있다는 주장이다. 특정 검색어에서 순위를 높이려는 사이트로부터 돈을 받는 방식도 가능성으로 제시했다.

다른 사용자는 직접 운영하는 검색 도구나 검색 결과를 긁어오는 도구를 쓰면 개인 용도에서는 무료로도 충분하다고 말했다. 이에 대한 답글에서는 조직이라면 응답 지연, 데이터 처리 보장, 기업 정보 유출 위험을 따져 호스팅 검색 서비스를 고를 수 있다고 반박했다. 특히 대화형 서비스의 짧은 질의나 검색을 10회 이상, 페이지 가져오기를 100회 이상 수행하는 조사 작업에서는 속도와 수집 안정성이 중요하다는 설명이다.

한 사용자는 검색 결과에 출처를 붙이는 수준을 넘어, 모델이 학습 단계부터 사실과 추론의 출처를 구분하도록 만들자고 제안했다. 답글에서는 사람도 단어의 뜻을 언제 누구에게 배웠는지 모두 밝혀낼 수는 없다며 그 요구의 어려움을 지적했다. 웹을 찾아오는 기능과 모델이 이미 알고 있던 내용을 출처별로 설명하는 기능은 다른 문제라는 논쟁이다.

구글(Google)이 유료 검색 API를 제공하지 않기 때문에 이런 서비스가 생긴다는 의견도 나왔다. 답글에서는 검색 API가 여러 애플리케이션에 유용할 텐데도 구글이 광고 사업과의 관계 때문에 이를 적극적으로 제공하지 않는 것 아니냐고 추측했다. 이는 딥시크의 기능 자체보다, 개발자가 검색을 외부 서비스로 연결해야 하는 시장 구조에 주목한 시각이다.

가격을 비교한 사용자는 1,000건 기준으로 브레이브(Brave) 검색 API는 5달러, 카기(Kagi) API는 12달러라고 적었다. 답글에는 세라믹.ai(Ceramic.ai)의 검색 1,000건당 0.25달러, 링크업(LinkUp)의 가져오기 1달러와 검색 5달러라는 비교도 이어졌다. 각 서비스가 제공하는 결과와 기능까지 같은 조건으로 비교한 수치는 아니지만, 참가자들이 요청 가격을 평가의 출발점으로 삼고 있음을 보여준다.

더 비싼 엑사(Exa)를 택한다는 사용자는 의미 기반 검색에서 얻는 신호 대비 잡음의 비율과 학술 자료 색인을 이유로 들었다. 값싼 요청을 많이 보내는 것보다 원하는 자료를 정확히 찾는 편이 낫다는 관점이다. 같은 토론에서 검색 입력 필드의 길이 차이도 비교했지만, 그 평가는 해당 사용자의 선택 이유로 읽어야 한다.

가져오기가 봇 차단을 만났을 때 어떻게 되는지 묻는 의견도 있었다. 클라우드플레어(Cloudflare)의 확인 화면이나 아누비스(Anubis)로 보호된 페이지에서 오류가 날지, 빈 내용이 올지, 실제 본문을 얻을지가 질문의 핵심이었다. 답글에서는 서비스의 접근 방식과 개별 사이트의 설정에 따라 결과가 달라진다고 설명했다. 이는 문서에 적힌 ‘대상 사이트의 접근 정책’이 실제 사용에서 확인해야 할 조건임을 짚는다.

직접 에이전트용 검색·가져오기 도구를 만들었다는 사용자는 자신의 방식이 오픈AI와 앤트로픽(Anthropic)의 통합 도구보다 15~20배 비용 효율적이었다고 말했다. 그러면서 딥시크의 이번 가격도 경쟁력 있게 평가했다. 자체 구축과 제공업체의 통합 도구 사이에서 선택할 때, 요청 단가뿐 아니라 개발·운영 방식을 함께 따져야 한다는 경험담이다.

핵심통찰

딥시크의 검색·가져오기 API는 에이전트가 웹을 읽는 과정을 결과 목록과 페이지 본문으로 나누고, 결과가 나온 요청에만 비용을 매기는 선택지를 더했다. 낮은 요청 가격은 분명 눈에 띄지만, 토론이 보여주듯 실제 가치는 원하는 자료를 얼마나 잘 찾고 필요한 페이지를 얼마나 안정적으로 읽는지에 달려 있다. 앞으로 지켜볼 것은 가격표 하나보다 검색 품질, 사이트 접근 성공률, 대량 작업에서의 호출 한도가 함께 만들어 내는 사용 경험이다.


원본: Search & Fetch | DeepSeek API Docs

토론: Hacker News