11월 13일 DeepSeek가 앱 도구를 API로 연 뒤, deepseek-flash JSON에서 deepseek_web_search, deepseek_read_url, safety_check를 어떻게 선언하고 tool_search를 토큰과 따로 청구할까

모델 이름만으로는 검색이 켜지지 않습니다. tools, thinking, safety_check가 JSON을 정합니다. 청구 횟수는 tool_search입니다.

model을 deepseek-flash로 써도 검색은 켜지지 않습니다. 2026년 11월 13일 DeepSeek는 채팅 앱 뒤의 도구를 API에 열었습니다. 이름 deepseek-flash는 DeepSeek-V4.1-Flash-1017입니다. 옛 이름 deepseek-v4-flash와 deepseek-v4-flash-vision-exp도 여기로 가고 Flash 가격으로 청구됩니다. 컨텍스트는 100만 토큰. 최대 출력은 38.4만. 사고가 기본값입니다.

이 페이지는 2026년 11월 16일 기준이며, 11월 13일 변경 기록, 웹 도구 가이드, Search와 Fetch 가이드, 안전 가이드, 가격 페이지를 따릅니다. 사흘 전에 Gemini 4 Carbon의 usage를 다뤘습니다. 요청과 청구를 바꾸는 필드는 tools, thinking, safety_check, usage.server_tool_use입니다.

11월 13일에 열린 것

같은 모델이 세 엔드포인트에서 도구를 받습니다. Messages는 POST https://api.deepseek.com/anthropic/v1/messages이고 헤더는 x-api-key입니다. Responses는 POST https://api.deepseek.com/responses. Chat Completions는 POST https://api.deepseek.com/chat/completions. 뒤의 둘은 Authorization: Bearer를 보냅니다. Search, Fetch, OCR, ASR, TTS는 단독으로도 호출합니다. 이미지 검색은 POST /v1/tools/search에 없고 deepseek_web_search 안에만 있습니다.

기능켜는 JSON돌아오는 것
웹 검색deepseek_web_search, 사고 끔모델이 필요하다고 볼 때 검색하고 인용한다
깊은 사고 검색deepseek_web_search, 사고 켬search, open_page, find_in_page, 약 20회
URL 읽기deepseek_read_url마지막 사용자 메시지만. 서로 다른 URL은 앞의 10개까지
안전safety_check.level = high입력과 출력을 검토. 대중 서비스에는 켜야 한다
파일Files API의 file_idPDF, Office, 이미지를 파싱한 뒤 대화에 넣는다

세 엔드포인트의 요청 JSON

Messages는 도구를 type과 name에 모두 씁니다. Responses와 Chat은 type만 보냅니다. tool_choice로 이 이름을 지정하면 400, deepseek_web_search cannot be forced 입니다. none은 URL 읽기를 포함해 선언한 웹 도구를 끕니다. Responses와 Chat의 required는 auto입니다.

allowed_domains, blocked_domains, user_location은 보내지 않습니다. 같은 도구를 두 번 선언하지 않습니다. 다른 서버 도구도 섞지 않습니다. 오류는 다른 도구를 아직 deepseek_web_search, deepseek_read_url, safety_check, title와 함께 쓸 수 없다고 합니다. Responses에서는 web_search 도구와 text가 아닌 text.format이 400입니다. Chat에서는 web_search_options와 text가 아닌 response_format이 400입니다. 구조화 JSON과 이 웹 도구는 한 요청에 둘 수 없습니다. 자기 스키마는 다음 호출로 미룹니다. 구조화 출력이란을 보세요.

사고를 끄면 인용 검색, 켜면 깊은 사고 검색입니다. 둘 다 켜진 라운드에서는 deepseek_read_url이 돌지 않습니다. 링크는 사고가 꺼졌을 때, 또는 deepseek_read_url만 선언했을 때 읽습니다. Messages와 Chat은 thinking.type을 disabled 또는 enabled로 둡니다. Responses 문서의 깊은 사고 검색 예는 reasoning.effort를 high로 둡니다.

{
  "model": "deepseek-flash",
  "thinking": {
    "type": "disabled"
  },
  "safety_check": {
    "level": "high"
  },
  "tools": [
    {
      "type": "deepseek_web_search",
      "name": "deepseek_web_search"
    },
    {
      "type": "deepseek_read_url",
      "name": "deepseek_read_url"
    }
  ],
  "messages": [
    {
      "role": "user",
      "content": "What changed in the DeepSeek API on 13 November 2026?"
    }
  ]
}

Responses의 사고 검색:

{
  "model": "deepseek-flash",
  "reasoning": {
    "effort": "high"
  },
  "safety_check": {
    "level": "high"
  },
  "tools": [
    {
      "type": "deepseek_web_search"
    },
    {
      "type": "deepseek_read_url"
    }
  ],
  "input": "Which official page states the height of Tokyo Tower?"
}

블록, kind, 인용

Messages에서는 호출마다 server_tool_use와 결과가 옵니다. tool_use_id로 짝을 맞춥니다. 스트림에서는 둘 다 content_block_start에 한 번에 옵니다. 최종 usage는 message_delta에 있습니다. message_start의 usage는 첫 추론 단계만 담습니다.

input.actionnamekind결과
searchdeepseek_web_search사고 중에는 deep_search, 아니면 searchweb_search_tool_result
open_pagedeepseek_web_searchdeep_searchweb_fetch_tool_result. data는 빈 문자열. signature 없음
find_in_pagedeepseek_web_searchdeep_search같은 모양. title은 null. 청구되지 않음
read_linkdeepseek_read_urlread_linkweb_fetch_tool_result와 signature

이미지 검색의 kind는 image_search 또는 deep_image_search입니다. queries는 빈 배열입니다. 결과에 표시용 image_url이 붙을 수 있습니다. Messages 인용은 text 블록의 web_search_result_location입니다. cited_text는 그 블록의 답 문장이고 페이지 인용이 아닙니다. encrypted_index는 항상 빈 문자열입니다. 한 블록에 같은 URL은 한 번입니다. 스트림에서는 citations_delta입니다.

Responses는 호출을 web_search_call에 두고 kind와 action을 붙입니다. 답은 url_citation 주석이 있는 output_text입니다. start_index와 end_index는 유니코드 코드 포인트입니다. Chat은 message.server_tool_calls입니다. 각 단계에 reasoning_content와 calls가 있습니다. message.content에는 인용 표시가 없고, 인용은 message.annotations입니다. message.reasoning_content는 마지막 단계만입니다.

이 도구를 쓴 답변은 이어서 생성할 수 없고, API는 400과 함께 이전 요청을 다시 보내라고 합니다. 다음 턴에는 kind와 signature를 포함해 그대로 돌려보냅니다. 검색 스니펫과 이전 사고는 이후 맥락에 다시 넣지 않습니다. 답 문장만 남습니다. 읽은 페이지는 signature에서 복원됩니다. read_link의 data는 항상 빈 문자열입니다. signature를 빼면 요청은 성공하지만 페이지는 없습니다. 실패 코드는 url_not_accessible, url_not_allowed, unavailable입니다. url_not_allowed는 안전 검토를 통과하지 못한 페이지도 포함합니다.

Responses 검색 항목 하나:

{
  "type": "web_search_call",
  "id": "srvtoolu_s_00_3f2a9c",
  "status": "completed",
  "kind": "search",
  "action": {
    "type": "search",
    "queries": [
      "DeepSeek API 13 November 2026"
    ],
    "sources": [
      {
        "type": "url",
        "url": "https://example.com/news",
        "title": "Change log",
        "snippet": "Web search and URL reading are now API tools.",
        "published_at": "2026-11-13T00:00:00+00:00"
      }
    ]
  }
}

단독 Search와 Fetch JSON

모델이 아니라 코드가 검색할 때는 원시 JSON API를 호출합니다. Search는 POST https://api.deepseek.com/v1/tools/search입니다. query는 필수이고 1~128자이며 공백만은 안 됩니다. count는 1~50, 기본 10입니다. ori_question은 선택이고 역시 1~128자입니다. localization은 선택 IP입니다. need_content 기본값은 false입니다. 알 수 없는 필드는 무시됩니다. 그대로 전달되는 연산자는 site:, -site:, -, -"...", "...", lang:, after:, before:입니다.

{
  "query": "DeepSeek site:api-docs.deepseek.com after:2026-11-01",
  "count": 10,
  "need_content": false
}

Fetch는 POST https://api.deepseek.com/v1/tools/fetch입니다. 필드는 url뿐이고, 최대 8,192자, 호스트가 있는 HTTP 또는 HTTPS, 사용자 이름과 비밀번호는 없습니다. 응답은 title과 Markdown content입니다. 제목이 없으면 빈 문자열입니다.

{
  "url": "https://api-docs.deepseek.com/updates"
}
필드저장할 의미
rerank_score0~3. 가이드는 1.5 이상을 고품질로 봅니다
authority0~4. −1은 알 수 없음. 3 이상은 권위가 높음
snippet / summary짧은 쪽은 UI, 긴 쪽은 모델용
contentneed_content가 true가 아니거나 내용이 없으면 빈 문자열
dateRFC 3339 UTC, 또는 null

file_id, OCR, 음성 JSON

파일 입력은 두 단계입니다. POST https://api.deepseek.com/files에서 purpose를 file보다 먼저 보냅니다. text_recognition은 도표를 버립니다. rich_layout_recognition은 그림을 본문 위치에 자르고 이미지 토큰을 씁니다. 파일 객체는 파싱이 끝난 뒤에만 옵니다. id는 file-api-... 형태입니다. 연결이 끊겨도 이후 성공한 파싱은 저장되고 청구됩니다. 원본과 파싱 결과는 받을 수 없습니다. Chat Completions는 이렇게 참조합니다.

{
  "role": "user",
  "content": [
    {
      "type": "file",
      "file_id": "file-api-xxxxxxxxxxxxxxxx"
    },
    {
      "type": "text",
      "text": "Summarize the revenue chart."
    }
  ]
}

Messages는 헤더 anthropic-beta: files-api-2025-04-14와 source.type이 file인 document 블록이 필요합니다. Responses는 input_file과 file_id입니다. 파싱된 문서를 이미지 블록으로 보낼 수 없습니다. 바이트나 파일 URL을 채팅 요청에 직접 넣을 수도 없습니다. 요청 하나는 문서 20개, 본문 합계 8 MiB까지입니다. 이후 턴에도 파싱 전문이 맥락에 남습니다. 너무 길면 400입니다. 조용히 자르지 않습니다.

한도: PDF, Word, PowerPoint, 일반 이미지. 형식은 바이트로 판별합니다. 100 MiB를 넘으면 413. 1,000페이지. 업로드 120초가 아니면 408. 파싱 120초가 아니면 504. 계정당 진행 중인 문서 업로드는 15개. 암호 파일은 400. 일반 텍스트, csv, json, 소스, xlsx, xls, epub, mobi는 purpose를 user_data로 하고 페이지 요금이 없습니다. 파일은 32 MiB, 텍스트는 8 MiB까지. AZW3와 DRM 전자책은 지원하지 않습니다.

파싱은 성공할 때만 1,000페이지당 0.225달러를 한 번 받습니다. 이후 대화는 입력 토큰이고 페이지는 다시 받지 않습니다. OCR도 같은 페이지 가격이며 POST /v1/tools/ocr는 Files API에 들어가지 않습니다. multipart의 file과 purpose이고 JSON 본문이 아닙니다. ASR은 multipart 오디오입니다. TTS는 JSON이고 POST /v1/tools/tts입니다.

TTS 정가는 1만 자당 0.45달러, 공개된 기간 한정가는 0.225달러입니다. 한자는 2자, 그 외는 1자입니다. 목소리는 stella(기본)와 tide입니다. 언어 필드는 없습니다. ASR 정가는 오디오 1시간당 0.116달러, 기간 한정 0.058달러이고, 초 단위이며 미만은 1초로 올립니다. 가격 페이지에 반값 종료일은 없습니다.

{
  "text": "Hello from DeepSeek.",
  "voice_id": "stella",
  "format": "wav",
  "filter_markdown": true
}

safety_check와 거부 JSON

대중이 닿는 서비스는 safety_check를 {"level":"high"}로 둡니다. low는 생략과 같습니다. 다른 level은 400입니다. 이 매개변수는 자체 검토, 등록, 표시 의무를 대신하지 않습니다. 입력이 통과하지 못하면 400 Content Exists Risk이고, 그 입력 토큰은 캐시 적중 가격으로 청구됩니다. 모델이 끝난 뒤에도 출력 검토가 끝날 때까지 연결은 열려 있습니다. 이미 흘러간 텍스트는 거둘 수 없습니다. 보여 준 답을 자신의 거부 문으로 바꾸세요. 거부 전에 쓴 토큰은 청구됩니다. 검토 토큰은 출력 토큰에 들어 있고, Messages와 Responses에서는 usage.output_tokens_details.safety_tokens, Chat에서는 usage.completion_tokens_details.safety_tokens에도 나옵니다. 막힌 이미지는 messages.1.content.0 같은 경로를 stop_details.explanation, refusal 내용, 또는 message.refusal에 둘 수 있습니다. 웹 도구를 선언하고 safety_check가 없는 요청도 거부로 끝날 수 있습니다.

API거부 JSON
Messagesstop_reason이 refusal, stop_details.type이 refusal. 비스트림은 사고와 답 문장을 빼고 도구 블록과 빈 text 하나를 남긴다
Responsesstatus가 incomplete, incomplete_details.reason이 content_filter. output은 실행된 web_search_call만 남긴다
Chatfinish_reason이 content_filter. content는 빈 문자열. annotations는 생략. server_tool_calls는 남고 각 단계의 사고는 비운다

tool_search를 청구하고 web_search_requests는 더하지 않기

토큰과 도구는 따로 청구합니다. Flash 가격은 100만 토큰당입니다. 피크는 월요일부터 금요일 UTC 01:00–04:00과 06:00–10:00이고, 중국 공휴일은 빠집니다. 그 외는 오프피크이며, 주말과 중국 공휴일은 하루 종일 오프피크입니다. 오프피크는 피크의 절반입니다. cache_creation_input_tokens는 0으로 남습니다.

시간캐시 적중 / 100만미스 / 100만출력 / 100만
오프피크$0.003$0.15$0.60
피크$0.006$0.30$1.20

검색과 웹 가져오기는 성공 1,000회당 0.75달러입니다. 모델이 도구를 부르든, 직접 /v1/tools/search나 /v1/tools/fetch를 부르든 같습니다. 결과가 있는 도구 검색은 쿼리마다 청구되어 쿼리 3개면 3회입니다. count는 Search API 단가를 바꾸지 않습니다. HTTP 200이고 results가 빈 배열이면 청구되지 않습니다. Fetch는 페이지 내용이 올 때만입니다. 그 뒤 안전 검토가 url_not_allowed나 unavailable로 바꿔도, 가져오기는 이미 일어났으므로 청구됩니다. 깊은 사고 검색에서 같은 페이지를 다시 여는 것은 무료입니다. find_in_page도 무료입니다.

Search는 계정당 초당 100, Fetch는 25이고 도메인별 한도가 더 있습니다. 한도는 키가 아니라 계정이며, Flash 동시 실행 2,500과 별개입니다. 가이드의 쿼리 2개 예는 web_search_requests 1, tool_search 2입니다. 저장할 값은 tool_search, tool_fetch, tool_image_search입니다. web_search_requests를 더하지 않습니다. Responses와 Chat은 이 셋이 모두 0이면 server_tool_use에서 그 묶음을 생략합니다.

HTTP가 이미 200인 뒤 생성이 실패하면 본문은 오류와 usage입니다. Messages 스트림은 error 이벤트로 끝나고 그 뒤에 message_delta가 없습니다. 본문을 확인하세요. SDK는 상태 200에서 예외를 내지 않습니다. 그 쿼리 2개의 공개 예입니다. thinking_tokens와 safety_tokens는 이 객체에 없습니다. 사고가 켜졌거나 safety_check가 high일 때 따로 나타나며, 이미 output_tokens 안에 있습니다.

{
  "input_tokens": 1905,
  "cache_creation_input_tokens": 0,
  "cache_read_input_tokens": 0,
  "output_tokens": 72,
  "service_tier": "standard",
  "server_tool_use": {
    "web_search_requests": 1,
    "web_fetch_requests": 0,
    "tool_search": 2,
    "tool_fetch": 0,
    "tool_image_search": 0
  }
}

출시 전에 확인할 JSON

  1. 본문 모델은 deepseek-flash. Messages 도구는 type과 name을 모두 가진다. 인용 검색이면 사고는 disabled.
  2. 공개 앱은 safety_check.level을 high로 보낸다. 이 호출의 response_format과 text.format은 text로 둔다.
  3. 파서는 tool_use_id와 kind를 맞추고, 다음 턴을 위해 signature를 남긴다.
  4. 청구는 tool_search, tool_fetch, tool_image_search와 캐시 미스 입력, 캐시 적중 입력, 출력. web_search_requests는 더하지 않는다.
  5. 단독 query는 1~128자. count는 1~50. 빈 결과는 요금이 아니다.

로컬에서 JSON 검증, JSONPath($.usage.server_tool_use.tool_search), JSON Diff로 이전 요청과 비교합니다. 업로드되지 않습니다.

FAQ

thinking을 켜면 검색이 바뀌나요?

바뀝니다. thinking.type이 disabled이면 인용이 있는 웹 검색이고 kind는 search입니다. enabled는 깊은 사고 검색으로, search, open_page, find_in_page를 약 20번 호출하고 kind는 deep_search입니다. 사고가 기본값입니다. 사고와 deepseek_web_search가 모두 켜진 라운드에서는 deepseek_read_url이 돌지 않습니다.

tool_choice로 deepseek_web_search를 강제할 수 있나요?

없습니다. 이름을 지정하면 400이고, deepseek_web_search cannot be forced 입니다. 검색 여부는 모델이 정합니다. tool_choice가 none이면 URL 읽기를 포함해 선언한 웹 도구가 꺼집니다. Responses와 Chat에서 required는 auto로 취급됩니다.

청구에 web_search_requests를 쓰나요?

쓰지 않습니다. 이 수는 오류를 포함하고 표시용입니다. 청구 필드는 tool_search, tool_fetch, tool_image_search입니다. 웹 도구 가이드에서 쿼리 2개인 검색 블록 하나는 web_search_requests 1, tool_search 2입니다. 결과가 있는 검색은 쿼리마다 과금됩니다. 빈 결과나 실패는 과금되지 않습니다.

POST /v1/tools/search가 이미지 검색인가요?

아닙니다. 이미지 검색은 deepseek_web_search 안에서만 됩니다. kind는 image_search 또는 deep_image_search이고 queries는 빈 배열입니다. 이미지 1장이 검색 1회이고, 모델이 고른 영역도 각각 1회입니다.

공개 서비스는 안전 검사를 어떻게 보내나요?

DeepSeek는 대중에 여는 서비스가 safety_check의 level을 high로 두라고 합니다. low는 필드를 생략하는 것과 같습니다. 입력이 위험하면 400 Content Exists Risk이고, 그 입력 토큰은 캐시 적중 가격으로 청구됩니다. 거부는 stop_reason이 refusal, Responses는 incomplete와 content_filter, Chat은 finish_reason이 content_filter입니다.

검색한 답변을 이어서 생성할 수 있나요?

없습니다. deepseek_web_search 또는 deepseek_read_url을 쓴 답변은 400입니다. 이전 요청을 다시 보냅니다. 다음 턴에는 kind와 signature를 포함해 어시스턴트 블록을 그대로 돌려보냅니다. 유효한 signature가 없어도 요청은 성공하지만, 페이지는 맥락으로 돌아오지 않습니다.

요약

11월 13일 도구는 요청, 저장해야 하는 블록, 청구서의 또 한 줄을 바꿉니다. deepseek-flash에 deepseek_web_search와 deepseek_read_url을 선언합니다. 인용 검색은 사고를 끄고, 깊은 사고 검색은 켭니다. 공개 앱은 safety_check.level을 high로 둡니다. tool_search를 청구하고 web_search_requests는 청구하지 않습니다.