DeepSeek API 웹 검색·URL 읽기: 요금과 400 오류 해결

Chat Completions, Messages, Responses에서 deepseek-flash의 서버 측 웹 검색과 URL 읽기를 설정합니다. thinking 모드에 따른 검색 방식, 여러 대화 턴에서 signature를 보존하는 방법, 검색·페이지 가져오기 요금과 토큰 비용 계산, 일반적인 400 오류 해결 방법을 안내합니다. 내장 도구와 독립형 Search, Fetch, OCR, ASR, TTS API의 선택 기준도 비교합니다.

목차
DeepSeek API 웹 검색·URL 읽기: 요금과 400 오류 해결

챗봇이 웹에서 최신 정보를 검색하고 출처를 표시해야 한다면 deepseek-flash에 deepseek_web_search를 선언하고 thinking을 비활성화하세요. 여러 단계의 조사가 필요하면 thinking을 켜고, 사용자가 제공한 링크를 읽으려면 deepseek_read_url을 사용하세요. 먼저 DeepSeek 공식 API에서 확인하는 것이 좋습니다. 일반적인 호환 API 게이트웨이가 새 서버 도구의 전용 필드와 결과를 모두 보존한다는 보장은 없습니다.

DeepSeek은 2026년 11월 13일 이러한 기능을 공개했습니다. 검색, URL 읽기, 파일 처리, 음성 서비스에는 일반적인 모델 토큰 요금 외에 별도의 사용료가 부과됩니다.

이 글에서는 세 가지 지원 API의 요청 형식, 실행 예제, 과금 카운터, 400 오류 해결 방법, 독립형 도구 API의 선택 기준을 설명합니다.

11월 13일 DeepSeek API 업데이트에서 무엇이 달라졌나요?

DeepSeek은 기존 채팅 앱에서 주로 제공하던 여러 기능을 개발자가 API로 사용할 수 있도록 개방했습니다.

11월 13일 공식 업데이트 내역에 따르면 모델 ID가 deepseek-flash인 DeepSeek V4.1 Flash에서 다음 기능을 지원합니다.

  • 출처 인용을 포함한 웹 검색과 이미지 검색.
  • 추론 단계마다 검색하고 페이지를 열어 본문을 조사하는 심층 검색.
  • 사용자 메시지에 포함된 URL 읽기.
  • PDF, Office 문서, 이미지 입력 및 텍스트 추출 또는 상세 레이아웃 분석.
  • 모델 입력과 출력에 대한 콘텐츠 안전 검사.

이 기능은 Messages, Responses, Chat Completions API에서 사용할 수 있습니다. DeepSeek이 서버에서 도구를 실행하고 검색 결과를 모델 문맥에 결합합니다.

내장 도구를 사용하면 앱에서 검색 엔진을 호출하거나 웹페이지를 내려받는 코드를 따로 실행할 필요가 없습니다.

DeepSeek은 독립형 Search, Fetch, OCR, ASR, TTS API도 제공합니다. 이 API는 검색 결과, 추출한 텍스트, 음성 인식 결과, 생성된 오디오를 앱 코드에 직접 반환합니다.

검색 모드는 어떻게 선택하나요?

thinking 설정에 따라 deepseek_web_search의 동작이 달라집니다.

모드도구 선언Thinking동작
일반 웹 검색deepseek_web_search비활성화필요할 때 검색하고 출처를 인용하여 답변합니다
심층 검색deepseek_web_search활성화여러 추론 단계에서 검색하고 페이지를 열어 본문을 찾습니다
URL 읽기deepseek_read_url비활성화 또는 웹 검색 없이 활성화마지막 사용자 메시지의 URL을 확인합니다
검색과 URL 읽기두 도구 모두비활성화검색할지 사용자가 제공한 URL을 읽을지 모델이 결정합니다

심층 검색에서는 답변 전에 도구를 약 20회까지 호출할 수 있습니다. 문서에 나온 대략적인 상한이며, 매번 그 횟수만큼 실행되는 것은 아닙니다.

두 도구를 함께 선언할 때는 중요한 동작 차이가 있습니다.

thinking이 켜져 있고 deepseek_web_search를 선언하면 해당 턴에서는 심층 검색이 사용됩니다. deepseek_read_url의 별도 URL 읽기 동작은 실행되지 않습니다.

사용자가 지정한 URL을 읽는 작업이 중요하다면 deepseek_read_url만 선언하세요.

서버 도구를 선언해도 실행이 강제되지는 않습니다. 실제 검색이나 페이지 가져오기는 모델이 결정합니다.

모델 자체의 특징은 DeepSeek V4.1 Flash 코딩 성능과 요금 가이드에서 확인할 수 있습니다.

Chat Completions에서 deepseek_web_search를 활성화하려면?

POST https://api.deepseek.com/chat/completions로 요청을 보내고, 모델을 deepseek-flash로 지정한 다음 tools에 검색 도구를 선언하세요.

유효한 DeepSeek API 키와 Bash, cURL, jq가 필요합니다.

다음 Bash 예제는 일반 웹 검색과 콘텐츠 안전 검사를 활성화합니다. 첫 명령은 키를 화면에 표시하지 않고 입력받습니다. 입력 대기 상태가 되면 DeepSeek에서 생성한 API 키를 붙여 넣으세요.

read -rs DEEPSEEK_API_KEY && export DEEPSEEK_API_KEY

curl -sS https://api.deepseek.com/chat/completions \
  -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-flash",
    "thinking": {"type": "disabled"},
    "tools": [
      {"type": "deepseek_web_search"}
    ],
    "safety_check": {"level": "high"},
    "messages": [
      {
        "role": "user",
        "content": "What did DeepSeek announce on November 13, 2026? Cite the official sources."
      }
    ]
  }' | jq '{
    error: .error,
    answer: .choices[0].message.content,
    citations: .choices[0].message.annotations,
    tool_calls: .choices[0].message.server_tool_calls,
    finish_reason: .choices[0].finish_reason,
    usage: .usage
  }'

검색을 실행한 정상 응답에는 다음 필드가 포함될 수 있습니다.

  • choices[0].message.content: 답변 본문.
  • choices[0].message.annotations: 출처 URL과 답변 내 인용 위치.
  • choices[0].message.server_tool_calls: 서버에서 수행한 검색 단계.
  • usage.server_tool_use: 검색과 페이지 가져오기 사용량 카운터.

답변이 완료되면 choices[0].finish_reason = "stop"이 반환됩니다. length는 출력 길이 제한으로 답변이 잘렸음을 뜻합니다. content_filter는 콘텐츠 검사에서 응답이 거부되었다는 의미입니다.

server_tool_calls가 없다고 해서 요청이 실패한 것은 아닙니다. 모델이 검색이 필요하지 않다고 판단했을 수 있습니다. 최신 정보가 필요한 질문으로 다시 확인하세요.

심층 검색 활성화하기

검색 도구 선언을 유지하고 thinking 설정만 변경합니다.

{
  "thinking": {"type": "enabled"},
  "tools": [
    {"type": "deepseek_web_search"}
  ]
}

여러 검색을 실행하거나 서로 다른 출처의 정보를 비교해야 할 때 적합합니다.

심층 검색은 페이지를 열어 본문을 검색할 수도 있습니다. 따라서 일반 검색보다 추론 토큰과 과금 대상 페이지 가져오기 횟수가 늘어날 수 있습니다.

실제로 실행할 단계는 모델이 선택합니다.

웹 검색 없이 URL 읽기

도구를 deepseek_read_url만 선언하고, 마지막 사용자 메시지에 URL을 포함하세요.

{
  "thinking": {"type": "disabled"},
  "tools": [
    {"type": "deepseek_read_url"}
  ],
  "messages": [
    {
      "role": "user",
      "content": "Summarize https://api-docs.deepseek.com/updates/ and identify the November 13 changes."
    }
  ]
}

이 요청에는 첫 번째 Chat Completions 예제와 동일한 엔드포인트, 모델, 인증, 안전 검사 설정을 사용하세요.

URL 읽기에는 다음 규칙이 적용됩니다.

  • 마지막 사용자 메시지에서만 URL을 찾습니다.
  • 같은 URL을 반복해도 한 번만 계산합니다.
  • 서로 다른 URL 중 처음 10개까지만 고려합니다.
  • 실제로 읽을 URL은 모델이 선택합니다.
  • 긴 페이지 여러 개를 읽으면 각 페이지의 내용이 일부 잘릴 수 있습니다.

자세한 내용은 공식 Web Tools 가이드에 나와 있습니다.

이전 사용자 메시지에만 URL이 있다면 다음 요청에서 해당 URL을 자동으로 다시 읽는다고 기대해서는 안 됩니다.

Messages와 Responses에서는 같은 도구를 어떻게 선언하나요?

세 API 모두 새 도구를 지원하지만 요청 형식과 응답 구조는 다릅니다.

API엔드포인트문서에 나온 도구 선언Thinking 제어
Chat Completions/chat/completions{"type":"deepseek_web_search"}thinking.type
Messages/anthropic/v1/messages{"type":"deepseek_web_search","name":"deepseek_web_search"}thinking.type
Responses/responses{"type":"deepseek_web_search"}reasoning.effort

세 경로 모두 https://api.deepseek.com을 호스트로 사용합니다.

DeepSeek 공식 Messages 예제에는 도구 선언에 type과 name이 모두 포함되어 있습니다. 다만 이 예제만으로 모든 유효한 요청에서 name이 필수라고 단정할 수는 없습니다.

Messages는 x-api-key 인증 헤더를 사용합니다. Chat Completions와 Responses는 Authorization: Bearer를 사용합니다.

프로토콜을 변경하기 전에는 Messages, Chat Completions, Responses 호환성 가이드를 참고하세요. 같은 모델 ID를 사용하더라도 도구와 대화 기록의 형식은 다를 수 있습니다.

Messages API 예제

다음 Bash 요청은 Anthropic 호환 Messages 형식으로 지정된 URL을 읽습니다.

curl -sS https://api.deepseek.com/anthropic/v1/messages \
  -H "x-api-key: ${DEEPSEEK_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-flash",
    "thinking": {"type": "disabled"},
    "tools": [
      {
        "type": "deepseek_read_url",
        "name": "deepseek_read_url"
      }
    ],
    "safety_check": {"level": "high"},
    "messages": [
      {
        "role": "user",
        "content": "Summarize https://api-docs.deepseek.com/updates/"
      }
    ]
  }' | jq '{
    content: .content,
    stop_reason: .stop_reason,
    usage: .usage
  }'

답변은 content 블록에 들어 있습니다. 서버 도구 호출은 server_tool_use 블록으로 표현되고, 그 뒤에 결과 블록이 이어집니다.

출처 인용은 텍스트 블록에 연결됩니다. 정상적으로 완료되면 stop_reason = "end_turn"이 반환됩니다.

스트리밍 응답에서는 마지막 message_delta 이벤트에서 전체 사용량을 읽으세요. message_start의 usage에는 첫 추론 단계의 사용량만 포함됩니다.

Responses API 예제

Responses API에서는 thinking.type 대신 reasoning.effort를 사용합니다.

none은 thinking을 끕니다. low, high, max는 지정된 수준의 thinking을 활성화합니다.

curl -sS https://api.deepseek.com/responses \
  -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-flash",
    "reasoning": {"effort": "high"},
    "tools": [
      {"type": "deepseek_web_search"}
    ],
    "safety_check": {"level": "high"},
    "input": "Research the November 13, 2026 DeepSeek API update and compare the official documentation."
  }' | jq '{
    status: .status,
    output: .output,
    usage: .usage
  }'

Responses API의 도구 실행 정보는 output 안의 web_search_call 항목으로 반환됩니다. 최종 답변은 message 항목이고, 출처는 output_text의 annotations에 포함됩니다.

정상 완료된 답변은 status = "completed"입니다. 출력 제한이나 콘텐츠 검사로 중단되면 incomplete가 될 수 있습니다. 생성에 실패하면 failed가 반환될 수 있습니다.

재시도하기 전에 incomplete_details.reason이나 error.code를 확인하세요.

세 프로토콜의 응답을 같은 구조로 처리해서는 안 됩니다. 특히 도구 실행 기록을 유지할 때 이 차이가 중요합니다.

여러 대화 턴에서 signature를 보존해야 하는 이유

deepseek_read_url이 페이지를 성공적으로 읽으면 DeepSeek은 암호화된 페이지 표현을 signature에 담아 반환합니다.

페이지 전문은 결과 블록에 일반 텍스트로 노출되지 않습니다. url, title, data, published_at 필드는 주로 화면 표시용입니다.

다음 대화 턴에서 DeepSeek은 signature를 사용해 이전에 읽은 페이지의 내용을 문맥에 복원할 수 있습니다.

이전 assistant 응답은 kind, signature, 서버 도구 호출 구조를 포함해 변경 없이 다시 전송하세요.

다음 Python 예제는 Chat Completions를 사용하며, 첫 assistant 메시지를 완전히 보존한 상태로 다음 질문을 보냅니다.

실행하기 전에 requests를 설치하고 DEEPSEEK_API_KEY를 환경 변수로 export하세요.

import os
import requests

endpoint = "https://api.deepseek.com/chat/completions"

headers = {
    "Authorization": f"Bearer {os.environ['DEEPSEEK_API_KEY']}",
    "Content-Type": "application/json",
}

tools = [{"type": "deepseek_read_url"}]

messages = [
    {
        "role": "user",
        "content": (
            "Read https://api-docs.deepseek.com/updates/ "
            "and summarize the November 13, 2026 entry."
        ),
    }
]


def complete_turn(history):
    response = requests.post(
        endpoint,
        headers=headers,
        json={
            "model": "deepseek-flash",
            "thinking": {"type": "disabled"},
            "tools": tools,
            "safety_check": {"level": "high"},
            "messages": history,
        },
        timeout=180,
    )

    response.raise_for_status()
    data = response.json()

    if data.get("error"):
        raise RuntimeError(data["error"])

    choice = data["choices"][0]

    if choice["finish_reason"] != "stop":
        raise RuntimeError(
            f"Incomplete response: {choice['finish_reason']}"
        )

    return choice["message"]


first_reply = complete_turn(messages)

# Preserve the complete assistant object, including server_tool_calls.
messages.append(first_reply)

messages.append(
    {
        "role": "user",
        "content": "Which developer features does that entry list?",
    }
)

second_reply = complete_turn(messages)
print(second_reply["content"])

이 예제는 문서에 나온 대화 형식을 보여줍니다. 실제 API 키로 실행해 검증한 결과는 아닙니다.

first_reply["server_tool_calls"]를 확인해 모델이 URL을 읽었는지 검사하세요. read_link 호출이 없다면 첫 응답에 보존할 페이지 signature도 없습니다.

다른 프로토콜에서도 해당 형식의 전체 기록을 유지해야 합니다.

API다음 요청에 다시 전달할 항목
Messageskind와 signature를 포함한 이전 assistant의 content 블록
Responsesweb_search_call, kind, signature를 포함한 이전 output 항목
Chat Completionsserver_tool_calls를 포함한 assistant 메시지 전체

라이브러리나 게이트웨이가 signature를 삭제하더라도 다음 요청은 성공할 수 있습니다. 그러나 이전에 읽은 페이지의 내용이 문맥에 다시 추가되지는 않습니다.

이전 심층 검색의 검색 결과, 열었던 페이지, 추론 단계가 다음 턴에 전문으로 자동 전달되는 것은 아닙니다. 일반적으로 이전 답변 텍스트만 남습니다. URL 읽기의 유효한 signature는 문서에 명시된 예외입니다.

페이지 내용을 후속 대화에 활용해야 한다면 assistant 기록을 role과 content만 남기도록 단순화하지 마세요.

독립형 Search, Fetch, OCR, ASR, TTS API는 언제 사용하나요?

데이터를 가져오거나 처리하는 과정을 앱 코드에서 직접 제어해야 한다면 독립형 API를 선택하세요.

내장 도구와 달리 독립형 API는 결과를 코드에 직접 반환합니다. 앱에서 내용을 검증하고 필터링하거나 저장한 뒤, 필요한 부분만 모델에 전달할 수 있습니다.

독립형 API 엔드포인트와 입력값

APIhttps://api.deepseek.com 기준 엔드포인트필수 입력결과
SearchPOST /v1/tools/searchJSON query구조화된 results
FetchPOST /v1/tools/fetchJSON url페이지 title과 Markdown content
OCRPOST /v1/tools/ocrMultipart file, purposepages[].text와 page_count
ASRPOST /v1/tools/asrMultipart 오디오 file음성 인식 text와 duration_ms
TTSPOST /v1/tools/ttsJSON textWAV 또는 PCM 오디오

다섯 API 모두 Bearer 인증을 사용합니다.

다음은 Bash에서 각 API를 호출하는 예제입니다. 앞서 export한 DEEPSEEK_API_KEY를 사용합니다.

# Search for pages and return structured results.
curl -sS https://api.deepseek.com/v1/tools/search \
  -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"query":"DeepSeek API release","count":5,"need_content":true}' \
  | jq '.results[] | {title, url, summary, content}'

# Fetch one page as Markdown.
curl -sS https://api.deepseek.com/v1/tools/fetch \
  -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://api-docs.deepseek.com/updates/"}' \
  | jq '{title, content}'

# Extract text from a local PDF.
curl -sS https://api.deepseek.com/v1/tools/ocr \
  -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
  -F purpose="text_recognition" \
  -F file="@document.pdf" \
  | jq '{page_count, pages}'

# Transcribe a local audio file.
curl -sS https://api.deepseek.com/v1/tools/asr \
  -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
  -F file="@speech.wav" \
  | jq '{text, duration_ms}'

# Generate a WAV file.
curl -sS https://api.deepseek.com/v1/tools/tts \
  -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello from DeepSeek.","voice_id":"stella"}' \
  --output speech.wav

OCR와 ASR 예제에는 로컬 입력 파일이 필요합니다. TTS 명령은 현재 작업 디렉터리에 speech.wav를 생성합니다.

2026년 11월 14일 기준 주요 제한은 다음과 같습니다.

  • Search: query 길이는 1–128 Unicode 문자입니다. count로 1–50개 결과를 요청할 수 있습니다. 계정당 제한은 100 QPS입니다.
  • Fetch: 요청당 HTTP 또는 HTTPS URL 하나를 처리합니다. 대상 사이트의 접근 정책이 적용됩니다. 계정당 제한은 25 QPS이며, 도메인별 QPS 제한도 있습니다.
  • OCR: 파일당 최대 100 MiB, 1,000페이지입니다. 계정당 동시에 실행할 수 있는 인식 작업은 최대 15개입니다.
  • ASR: 요청당 최대 120초와 8 MiB의 오디오를 처리합니다. 16-bit PCM WAV와 Ogg Opus를 지원합니다.
  • TTS: 요청당 최대 10,000개의 과금 대상 문자입니다. 전체 텍스트 음성 생성과 WebSocket 스트리밍을 지원합니다.

독립형 Search API에서는 site:, lang:, after: 같은 검색 연산자를 사용할 수 있습니다. 2026년 11월 14일 기준 독립형 Search API는 이미지 검색을 지원하지 않습니다. 이미지 검색은 내장 웹 도구에서 사용할 수 있습니다.

입력 형식과 제한은 Search 및 Fetch, OCR, ASR, TTS 문서에서 확인하세요.

파일 입력과 독립형 OCR의 차이

모델에 문서 내용을 질문하려면 파일 입력을 사용하세요. 추출한 텍스트를 앱 코드에서 직접 처리하려면 독립형 OCR을 사용하세요.

파일을 모델에 전달하는 과정은 다음과 같습니다.

  1. multipart/form-data 형식으로 POST https://api.deepseek.com/files에 문서를 업로드합니다.
  2. purpose 폼 필드를 file보다 먼저 전송합니다. 순서를 바꾸면 400이 반환될 수 있습니다.
  3. purpose에 text_recognition 또는 rich_layout_recognition을 지정합니다.
  4. 처리가 성공하면 file_id를 받은 다음, 후속 deepseek-flash 대화 요청에서 참조합니다.

다음 Bash 예제는 로컬 PDF를 업로드합니다.

curl -sS https://api.deepseek.com/files \
  -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
  -F purpose="text_recognition" \
  -F file="@report.pdf" \
  | jq '{id, filename, purpose}'

-F 옵션은 multipart 폼 요청을 만듭니다. purpose 다음에 file을 보내는 순서를 지키세요. multipart Content-Type의 경계 문자열을 직접 지정하지 마세요. cURL이 자동으로 생성합니다.

업로드 응답의 id를 대화 요청에서는 file_id로 사용합니다. 문서 분석은 업로드 중에 수행되므로 별도로 상태를 확인하는 polling은 필요하지 않습니다.

text_recognition은 텍스트를 추출하지만 차트, 사진, 도표를 모델 해석에 제공하지 않습니다. rich_layout_recognition은 감지된 그림도 문서의 해당 위치에 맞춰 모델에 전달합니다.

Chat Completions의 사용자 메시지에서 파일을 참조하는 형식은 다음과 같습니다.

{
  "role": "user",
  "content": [
    {"type": "file", "file_id": "file-api-xxxxxxxxxxxxxxxx"},
    {"type": "text", "text": "Summarize the key points of this document."}
  ]
}

예제 ID 대신 업로드 응답에서 받은 실제 file_id를 사용하세요.

한 요청에서 참조할 수 있는 문서는 최대 20개입니다. 문서에서 추출한 텍스트의 전체 크기는 8 MiB를 초과할 수 없습니다.

문서 분석 요금은 업로드에 성공했을 때 한 번 부과됩니다. 이후 모델 요청에서 해당 문서를 사용하면 문서 내용에 대한 입력 토큰 요금이 발생합니다.

구현 전에 파일 분석 가이드를 참고하세요.

DeepSeek 웹 검색과 OCR·음성 API 요금은 얼마인가요?

2026년 11월 14일 기준 DeepSeek은 모델 추론 요금과 도구 사용 요금을 별도로 청구합니다.

공식 요금표에 나온 미국 달러 기준 요금은 다음과 같습니다.

기능과금 단위요금
텍스트 웹 검색과금 대상 검색 1,000회$0.75
이미지 검색과금 대상 검색 1,000회$0.75
웹 Fetch 또는 URL 읽기과금 대상 가져오기 1,000회$0.75
파일 분석 또는 OCR정상 처리된 1,000페이지$0.225
ASR오디오 1시간프로모션 $0.058, 정가 $0.116
TTS과금 대상 10,000문자프로모션 $0.225, 정가 $0.45

ASR과 TTS 할인은 기간 한정으로 표시되어 있습니다. 검토한 요금표와 API 문서에는 종료일이 명시되지 않았습니다.

TTS에서는 중국어 문자 하나를 과금 문자 두 개로 계산합니다. 공백을 포함한 다른 문자는 한 개씩 계산합니다.

ASR은 오디오 길이를 초 단위로 계산하며, 1초 미만의 나머지는 올림 처리합니다.

실제 과금 횟수는 어떤 usage 필드로 확인하나요?

내장 웹 도구에는 다음 카운터를 사용하세요.

  • usage.server_tool_use.tool_search: 과금 대상 텍스트 검색 횟수.
  • usage.server_tool_use.tool_image_search: 과금 대상 이미지 검색 횟수.
  • usage.server_tool_use.tool_fetch: 과금 대상 페이지 가져오기 횟수.

web_search_requests 또는 web_fetch_requests를 요금 계산에 사용하면 안 됩니다.

이 값은 오류를 포함한 결과 블록 수를 나타내는 표시용 카운터입니다. 실제 과금 대상 횟수와는 다릅니다.

서버의 검색 도구 호출 한 번이 여러 검색 쿼리를 실행할 수 있습니다. 성공한 쿼리가 세 개라면 tool_search가 세 번 증가할 수 있습니다.

검색이 실패하거나 결과가 없으면 요금이 부과되지 않습니다.

이미지 검색에서는 이미지 하나를 검색 한 번으로 계산합니다. 모델이 이미지 내부에서 선택한 각 영역도 추가 검색 한 번으로 계산합니다. 검색이 실패하거나 결과가 없으면 과금하지 않습니다.

URL 읽기는 페이지를 성공적으로 가져온 경우 과금됩니다. 이후 안전 검사에서 결과를 오류로 바꿨더라도, 이미 가져온 페이지에 대해 요금이 발생할 수 있습니다.

심층 검색에서는 문맥에 이미 있는 페이지를 다시 열어도 추가 Fetch 요금이 없습니다. 페이지 안에서 텍스트를 검색하는 작업도 무료입니다.

독립형 Search와 Fetch는 과금 방식이 다릅니다. 정상 처리된 API 요청마다 한 번씩 과금하며, Search 결과 수가 많다고 요청 요금이 늘어나지는 않습니다.

100개 요청의 비용 계산 예시

thinking을 사용하지 않는 DeepSeek Flash 요청 100개에서 다음 사용량이 발생했다고 가정하겠습니다.

사용량가정한 값
과금 대상 텍스트 검색 쿼리200
과금 대상 페이지 가져오기100
캐시를 사용하지 않은 입력 토큰200,000
캐시에서 읽은 입력 토큰0
안전 검사 토큰을 포함한 출력 토큰50,000
이미지 검색0

deepseek-flash의 공식 비혼잡 시간 요금은 캐시를 사용하지 않은 입력 토큰 100만 개당 $0.15, 출력 토큰 100만 개당 $0.60입니다.

계산식은 다음과 같습니다.

Text searches = 200 / 1,000 × $0.75 = $0.150
Page fetches  = 100 / 1,000 × $0.75 = $0.075
Input tokens  = 200,000 / 1,000,000 × $0.15 = $0.030
Output tokens = 50,000 / 1,000,000 × $0.60 = $0.030

Estimated total = $0.285 for 100 requests

이 조건에서 100개 요청의 예상 총비용은 $0.285입니다. 실제 API 사용량을 측정하거나 청구서를 확인한 결과가 아니라 가정에 따른 계산입니다.

DeepSeek의 공개 일정에 따르면 혼잡 시간은 월요일부터 금요일까지 01:00–04:00 및 06:00–10:00 UTC입니다. 중국 공휴일에는 해당 혼잡 시간 요금을 적용하지 않습니다.

혼잡 시간의 Flash 요금은 캐시를 사용하지 않은 입력 토큰 100만 개당 $0.30, 출력 토큰 100만 개당 $1.20입니다.

같은 사용량의 혼잡 시간 예상 총비용은 $0.345입니다.

실제 청구액은 추론 단계, thinking 토큰, 캐시 적중, 이미지 검색, 페이지 가져오기, 안전 검사, 적용되는 요금에 따라 달라집니다.

thinking 토큰은 이미 output_tokens에 포함되어 있습니다. 별도의 출력 토큰 비용으로 다시 더하지 마세요.

오류가 발생한 요청에도 요금이 부과되나요?

실패가 발생하기 전에 처리된 작업이 있다면 요금이 발생할 수 있습니다.

생성이 시작된 뒤 오류가 발생하면 응답 본문에 오류가 있어도 HTTP 상태가 200일 수 있습니다.

실패 전에 수행된 모델 추론, 검색, 페이지 가져오기에는 일반적인 요금이 적용됩니다.

스트리밍에서는 초기 HTTP 상태만 보지 말고 마지막 이벤트와 최종 usage를 확인하세요.

비스트리밍 Chat Completions에서도 HTTP 200 응답에 error 객체가 있는지 확인해야 합니다.

Responses에서는 failed, incomplete를 포함한 status 값을 확인하세요.

DeepSeek 웹 도구의 일반적인 400 오류 해결 방법

많은 요청 검증 오류는 서버 도구를 일반 함수처럼 강제로 선택하거나 지원하지 않는 옵션을 함께 사용해서 발생합니다.

공식 Web Tools 오류 문서에는 다음 메시지가 나와 있습니다.

오류 메시지원인해결 방법
tool_choice: deepseek_web_search cannot be forcedtool_choice로 서버 웹 도구를 강제 선택함강제 선택을 제거하고 모델이 결정하도록 합니다
tools: deepseek_web_search can only be declared once같은 도구를 중복 선언함선언을 하나만 남깁니다
tools: allowed_domains is not supported by deepseek_web_search지원하지 않는 도메인 또는 위치 옵션을 추가함allowed_domains, blocked_domains, user_location을 제거합니다
tools: other tools cannot be used together with deepseek_web_search, deepseek_read_url, safety_check or title yet호환되지 않는 다른 서버 도구를 선언함충돌하는 서버 도구를 제거합니다
safety_check: level must be low or high안전 검사 수준이 유효하지 않음low 또는 high를 사용합니다
messages: the last assistant message used deepseek_web_search or deepseek_read_url and cannot be continued; resend the previous request웹 도구를 사용한 부분 응답의 생성을 이어가려고 함이어 쓰기 대신 원래 요청을 다시 전송합니다

원래 오류 문자열에는 필드 이름을 감싸는 백틱이 있습니다. 위 표에서는 읽기 쉽게 해당 표시를 생략했습니다.

모든 해결 방법을 차례로 적용할 필요는 없습니다. 실제 오류 문자열에 해당하는 원인을 수정한 뒤 다시 요청하세요.

tool_choice로 웹 검색을 강제로 실행할 수 있나요?

불가능합니다. tool_choice로 deepseek_web_search 또는 deepseek_read_url을 강제 지정할 수 없습니다.

tool_choice를 none으로 설정하면 URL 읽기를 포함한 모든 도구가 꺼집니다.

Chat Completions와 Responses에서 웹 도구 사용 시 tool_choice: "required"는 auto로 처리됩니다. 따라서 이 설정도 검색을 보장하지 않습니다.

앱에서 특정 검색 쿼리를 반드시 실행해야 한다면 독립형 Search API를 호출하세요.

일반 function calls와 함께 사용할 수 있나요?

문서의 오류는 호환되지 않는 서버 도구 선언에 관한 것입니다.

이 설명만으로 개발자가 정의한 모든 일반 함수가 금지된다고 결론 내릴 수는 없습니다. 반대로 모든 에이전트 프레임워크에서 함께 동작한다는 검증도 없습니다.

Responses에서는 이 도구들과 web_search를 함께 선언할 수 없습니다. custom, namespace, tool_search 같은 일부 도구 형식도 지원하지 않습니다.

Claude Code, OpenCode 또는 자체 함수를 선언하는 에이전트에 추가하기 전에 전체 요청과 도구 호출·결과 전달 과정을 시험하세요.

웹 도구 없이 일반 OpenAI 호환 요청이 성공했다는 사실만으로 새 도구 조합의 호환성이 확인되지는 않습니다.

웹 도구를 사용한 답변의 이어 쓰기가 400을 반환하는 이유

새 대화 턴을 추가하는 것과 중단된 생성 결과를 이어서 만드는 것은 서로 다른 작업입니다.

새 턴에서는 완료된 assistant 응답 뒤에 새로운 사용자 메시지를 추가합니다.

이어 쓰기는 같은 assistant의 부분 응답을 계속 생성하려고 시도합니다.

DeepSeek은 deepseek_web_search 또는 deepseek_read_url을 사용한 응답의 이어 쓰기를 지원하지 않습니다.

검색을 사용한 답변이 중간에 잘렸다면 적절한 출력 한도를 지정해 이전 요청을 다시 보내세요. 이때 검색과 페이지 가져오기가 다시 수행되어 추가 요금이 발생할 수 있습니다.

웹 도구를 사용하지 않는 일부 Chat Completions 이어 쓰기에서는 beta 엔드포인트와 마지막 assistant 메시지의 prefix: true를 사용할 수 있습니다. 하지만 웹 도구 응답에 대한 제한은 그대로 적용됩니다.

url_not_accessible, url_not_allowed, unavailable은 무엇을 의미하나요?

페이지 가져오기에 실패하면 DeepSeek은 signature가 없는 web_fetch_tool_result_error를 반환합니다.

실패 원인은 error_code로 구분합니다.

오류 코드의미권장 조치
url_not_accessible링크를 읽을 수 없음URL, 사이트 가용성, 인증, 접근 제한을 확인합니다
url_not_allowed읽기가 허용되지 않거나 안전 검사에서 페이지가 거부됨제한을 우회하지 말고 허용된 다른 출처를 요청합니다
unavailable서비스가 불가용하거나 심층 검색 중 페이지를 열지 못했거나 호출이 완료되지 않음응답 상태를 확인하고 필요할 때 횟수를 제한해 재시도합니다

세 코드의 원인은 서로 다릅니다.

url_not_allowed가 항상 네트워크 오류를 뜻하는 것은 아닙니다. 콘텐츠 안전 검사에서 거부되었을 수도 있습니다.

unavailable이라고 해서 반드시 무료인 것도 아닙니다. 오류 발생 전에 이미 페이지 가져오기가 끝났을 수 있습니다.

스트리밍에서는 각 도구 호출과 결과를 식별자로 연결하세요. 여러 페이지를 읽을 때는 호출 직후에 해당 결과가 오지 않을 수 있습니다.

응답 종료 상태도 확인해야 합니다.

  • Messages의 end_turn은 답변이 완료되었음을 뜻합니다.
  • max_tokens는 출력 한도 또는 사용 가능한 문맥 한도에 도달했음을 뜻합니다.
  • refusal은 콘텐츠 검사가 응답을 거부했음을 나타냅니다.

Chat Completions의 관련 종료 값에는 stop, length, content_filter가 있습니다.

일반 사용자에게 제공하는 앱에서는 다음 안전 검사를 활성화하세요.

{
  "safety_check": {"level": "high"}
}

DeepSeek은 공개 서비스에서 안전 검사를 활성화하도록 요구합니다. 이 설정은 입력과 출력을 기본적으로 검사하지만, 앱 자체의 콘텐츠 검토나 관련 법령에 따른 등록 및 AI 생성 콘텐츠 표시 의무를 대신하지는 않습니다.

거부된 답변이라도 거부되기 전 사용한 토큰에 대해 요금이 부과될 수 있습니다.

프로토콜별 거부 응답 형식은 Model Content Safety 가이드에서 확인하세요.

DeepSeek 내장 도구와 자체 검색 API 중 무엇을 선택하나요?

모델이 대화 중 직접 조사를 진행해야 한다면 내장 도구가 적합합니다. 검색 과정과 원본 결과를 앱 코드에서 제어해야 한다면 독립형 API가 적합합니다.

앱 요구사항먼저 선택할 방법이유
출처를 포함한 챗봇 답변thinking을 끈 deepseek_web_search자체 검색 제어 코드를 줄일 수 있습니다
여러 출처를 조사하는 작업thinking을 켠 deepseek_web_search모델이 여러 단계로 검색하고 페이지를 조사할 수 있습니다
사용자가 제공한 링크 요약deepseek_read_url대상 URL을 읽고 signature로 페이지 문맥을 유지할 수 있습니다
특정 사이트 검색이나 구조화된 결과독립형 Search쿼리 연산자와 검색 결과를 코드가 제어합니다
지정 URL에서 Markdown 가져오기독립형 Fetch페이지 본문을 앱에서 직접 받습니다
많은 문서에서 텍스트 추출독립형 OCR페이지별 추출 결과를 받습니다
업로드한 문서에 관한 질의응답File Parsing과 deepseek-flash문서 내용이 모델 문맥에 포함됩니다
음성 입력이나 읽어주기ASR과 TTS음성 처리를 위한 전용 API를 사용합니다

이미 운영 중인 코딩 에이전트라면 외부 검색 통합을 유지하는 편이 나을 수도 있습니다. 기존 도구 선언과 검색 작업 제어 방식을 변경하지 않아도 되기 때문입니다.

기존 에이전트에 Parallel Search MCP를 연결하는 가이드에서 다른 접근법을 확인할 수 있습니다. 같은 작업을 기준으로 실제 비용, 도구 호환성, 가져온 콘텐츠의 품질을 비교하세요.

BetterToken이나 다른 호환 게이트웨이에서도 사용할 수 있나요?

2026년 11월 14일 기준 BetterToken 모델 목록에는 deepseek-flash가 포함되어 있었습니다. 접속 경로를 선택하기 전에 현재 모델 요금을 확인하세요.

하지만 모델이 목록에 있다는 사실만으로 DeepSeek의 새 서버 도구가 지원된다고 볼 수는 없습니다.

BetterToken에서 도구 선언 전달, signature 보존, usage.server_tool_use 반환, 추가 도구 요금 기록이 제대로 처리되는지는 검증되지 않았습니다.

따라서 이 글의 모든 예제는 DeepSeek 공식 엔드포인트를 사용합니다.

호환 게이트웨이를 사용하기 전에는 검색 요청 한 번, URL 읽기 요청 한 번, signature를 보존하는 다음 대화 턴을 검증하세요. 그다음 usage 카운터와 실제 청구액을 비교하세요.

새 앱이라면 thinking을 끈 일반 웹 검색부터 시작하세요. 출처와 과금 사용량을 확인한 뒤 여러 조사 단계가 필요할 때 심층 검색을 켜세요. 검색 절차를 코드가 직접 제어해야 하는 작업에는 독립형 Search와 Fetch를 사용하세요.

LLM 워크플로를 최적화할 준비가 되셨나요?

하나의 API로 모델을 연결하고 키와 AI 비용을 관리하세요.

무료로 시작하기