코딩을 위한 DeepSeek V4 API: deepseek-v4-pro 및 deepseek-v4-flash 라우팅

코딩 세션의 모든 단계를 하나의 모델로 처리하는 것은 가장 쉬운 라우팅 정책이지만, 대개 가장 비용이 많이 드는 방식입니다. 이 튜토리얼에서는 deepseek-v4-pro와 deepseek-v4-flash 간에 작업을 분할하여 TokenLab에서 DeepSeek V4 API를 코딩에 사용하는 방법을 설명합니다. 2026년 10월 3일 실시간 API에서 두 모델의 레코드를 읽었으며, 아래의 모든 내용은 해당 레코드와 TokenLab 문서를 기반으로 합니다. 비교 표, 예상 비용 산출, 도구 호출 요청, 재시도 및 폴백(fallback) 코드, 그리고 사전 점검(preflight check) 방법을 확인할 수 있습니다.

주요 내용

• 두 모델 모두 1,000,000 토큰의 입력 제한, 384,000 토큰의 출력 제한, 그리고 동일한 세 가지 요청 형식을 지원합니다. 가격이 가장 큰 차이점입니다.
• 정가 기준으로 deepseek-v4-pro는 deepseek-v4-flash보다 입력 토큰당 4.4배, 출력 토큰당 3.3배 더 비쌉니다.
• 20회 호출 예시에서 4회는 pro, 16회는 flash로 라우팅할 경우 오프피크(off-peak) 기준 약 $0.18가 소요됩니다. 20회 모두 pro로 전송하면 약 $0.46가 소요됩니다.
• 429 오류는 Retry-After 이후에 재시도하십시오. 500–504 오류는 retryable이 true일 때만 재시도하십시오. 400, 401, 402, 403, 404 또는 413 오류는 변경 없이 재시도하지 마십시오.
• 카탈로그에는 deepseek-v4.1-flash가 활성 상태로 기재되어 있습니다. deepseek-v4-pro와 deepseek-v4-flash 모두 대체 모델을 명시하지 않고 있습니다.
• 라우팅하기 전에 GET /v1/models/:model에서 제한, 형식, 가격을 읽어오십시오. 복사한 표를 하드코딩하지 마십시오.

코딩을 위한 DeepSeek V4 API: 카탈로그 정보

2026년 10월 3일에 두 레코드를 가져왔습니다. 아래 표는 두 모델을 나란히 비교한 것입니다. 가격은 100만 토큰당 USD이며, 카탈로그 가격은 2026년 10월 2일 16:53:30.068Z에 마지막으로 업데이트되었습니다.

항목	deepseek-v4-pro	deepseek-v4-flash	출처 (2026-10-03 관측)
컨텍스트 제한 (최대 입력 토큰)	1,000,000	1,000,000	pro, flash
출력 제한 (최대 출력 토큰)	384,000	384,000	pro, flash
허용된 요청 형식	anthropic_messages, openai_chat_completions, openai_responses	anthropic_messages, openai_chat_completions, openai_responses	pro, flash
기능	json-mode, prompt-cache, tool-use	json-mode, prompt-cache, tool-use	pro, flash
오프피크 입력	$0.66	$0.15	pro, flash
오프피크 출력	$1.98	$0.60	pro, flash
오프피크 캐시 읽기	$0.022	$0.003	pro, flash
오프피크 캐시 쓰기	$0.66	기재되지 않음	pro, flash
피크 입력	$1.32	$0.30	pro, flash
피크 출력	$3.96	$1.20	pro, flash
피크 캐시 읽기	$0.044	$0.006	pro, flash
수명 주기 단계	활성, 2026-04-24 출시	활성, 2026-04-24 출시	pro, flash

각 레코드의 기본 가격 블록은 오프피크 항목과 일치합니다. 피크 시간대는 레코드마다 다릅니다. deepseek-v4-pro의 경우 베이징 시간 09:00-12:00 및 14:00-18:00에 피크 가격이 적용됩니다. deepseek-v4-flash의 경우 레코드에 따르면 피크 시간대는 중국 공휴일을 제외한 평일에 적용됩니다. 오프피크에는 주말과 해당 공휴일이 포함된다고 되어 있으나 구체적인 시간은 명시되지 않았습니다. flash 시간대에 맞춰 예산을 책정하기 전에 가격 책정 엔드포인트를 확인하십시오.

수명 주기 및 최신 DeepSeek 모델

두 레코드 모두 lifecycle stage active로 표시되며, replacement model, deprecated_at, retired_at 필드는 모두 비어 있습니다. 따라서 카탈로그상 두 모델 모두 제거 예정이 없으며, 후속 모델도 지정되어 있지 않습니다.

카탈로그에는 deepseek-v4.1-flash도 나열되어 있습니다. 2026년 10월 3일에 관측된 해당 레코드는 출시일이나 대체 모델 없이 활성 상태입니다. deepseek-v4-flash와 동일한 제한, 형식, 정가를 가집니다. 기능 목록에 reasoning과 vision이 추가되었으며, 오프피크 캐시 쓰기 가격은 $0.15로 표시됩니다.

이는 별도의 모델 ID이므로 이 기사는 기존 주제를 유지합니다. deepseek-v4.1-flash를 교체하기 전에 직접 작업에서 테스트해 보시기 바랍니다. 카탈로그에는 deepseek-v4-flash-vision-exp도 나열되어 있으나 해당 레코드는 읽지 않았습니다. 필요한 경우 모델 페이지에서 확인하십시오.

작업별 deepseek-v4-pro 및 deepseek-v4-flash 라우팅

5개 모듈에 걸친 변경 사항을 계획하고, 편집 내용을 작성한 뒤, 12개의 테스트 스텁을 생성하는 에이전트 세션을 상상해 보십시오. 첫 번째 단계는 가장 많은 컨텍스트와 주의가 필요합니다. 마지막 단계는 반복적이며 다시 수행해도 비용이 저렴합니다. 카탈로그는 품질의 경계가 어디에 있는지 알려줄 수 없습니다. 2026년 10월 3일에 관측된 TokenLab의 코딩 에이전트 모델 가이드에 따르면, 리더보드 결과는 모델이 사용자의 지시와 도구를 얼마나 잘 따르는지 예측하지 못합니다.

우리의 시작 휴리스틱은 더 비싼 모델이 파일 간 작업에서 비용만큼의 가치를 한다고 가정합니다. 이를 발견된 사실이 아닌 테스트할 가설로 취급하십시오:

+-------------------------------------------------------------+
|                      수신된 작업                            |
+-------------------------------------------------------------+
                               |
         [작업에 다중 파일 컨텍스트, 하위 호환성,
          또는 보안 검토가 포함됩니까?]
                               |
               +---------------+---------------+
               |                               |
             [예]                            [아니오]
               |                               |
               v                               v
       deepseek-v4-pro                 deepseek-v4-flash

deepseek-v4-pro로 작업을 보내야 하는 기준:

• 여러 가져온 파일에 걸친 로직 수정.
• 보안 또는 취약성 평가.
• 공용 인터페이스에 대한 엄격한 하위 호환성 유지.
• 정확도가 처리 속도보다 중요한 다중 턴 작업.

독립형 테스트 스캐폴딩, 스키마 포맷팅, 독스트링(docstrings), 구문 완성은 deepseek-v4-flash로 보냅니다.

휴리스틱을 테스트하려면 동일한 가이드를 따르십시오. 각 모델에 동일한 저장소 상태, 지침, 도구, 시간 제한을 제공하십시오. 그런 다음 정확성, 통과된 테스트, 불필요한 변경 사항, 총 토큰 수, 최종 비용, 그리고 사람이 개입해야 했던 빈도를 비교하십시오. 한 모델은 검토는 잘하지만 구현은 못할 수 있으므로 작업 유형별로 결과를 보관하십시오.

코딩 에이전트 루프 비용 추정

에이전트는 매 호출마다 지침, 기록, 코드, 도구 결과를 다시 보냅니다. 2026년 10월 3일에 관측된 비용 가이드는 긴 세션이 단일 채팅 요청보다 훨씬 더 많은 비용이 들 수 있음을 지적합니다. 아래 산술 계산은 정가를 기준으로 했습니다. 결과는 측정된 청구서가 아닌 추정치입니다.

가정 (측정되지 않은 당사 가정): 20회의 모델 호출 루프, 각 호출마다 30,000개의 입력 토큰과 1,500개의 출력 토큰 사용. 총 600,000개의 입력 토큰과 30,000개의 출력 토큰.

공식은 입력 토큰 / 1M × 입력 가격 + 출력 토큰 / 1M × 출력 가격입니다. 가격은 위 표에서 가져왔습니다.

20회 호출 모두 deepseek-v4-pro 사용:

• 오프피크: 0.6 × $0.66 = $0.396(입력) + 0.03 × $1.98 = $0.0594(출력) = $0.4554.
• 피크: 0.6 × $1.32 = $0.792 + 0.03 × $3.96 = $0.1188 = $0.9108.

20회 호출 모두 deepseek-v4-flash 사용:

• 오프피크: 0.6 × $0.15 = $0.09 + 0.03 × $0.60 = $0.018 = $0.108.
• 피크: 0.6 × $0.30 = $0.18 + 0.03 × $1.20 = $0.036 = $0.216.

혼합: pro 4회, flash 16회. Pro는 120,000개의 입력 및 6,000개의 출력 토큰을 처리합니다. Flash는 480,000개의 입력 및 24,000개의 출력 토큰을 처리합니다.

• 오프피크: pro는 0.12 × $0.66 + 0.006 × $1.98 = $0.0792 + $0.01188 = $0.09108. Flash는 0.48 × $0.15 + 0.024 × $0.60 = $0.072 + $0.0144 = $0.0864. 총합은 $0.17748.
• 피크: pro는 0.12 × $1.32 + 0.006 × $3.96 = $0.1584 + $0.02376 = $0.18216. Flash는 0.48 × $0.30 + 0.024 × $1.20 = $0.144 + $0.0288 = $0.1728. 총합은 $0.35496.

시나리오	오프피크 추정치	피크 추정치
deepseek-v4-pro 20회 호출	$0.4554	$0.9108
deepseek-v4-flash 20회 호출	$0.1080	$0.2160
pro 4회 + flash 16회	$0.1775	$0.3550

2026년 10월 3일에 관측된 정가 기준 추정치 (pro, flash).

캐시 변형 (오프피크, 가정: 입력 토큰의 80%가 캐시 읽기). 즉, 루프당 480,000개의 캐시 읽기 토큰과 120,000개의 캐시되지 않은 토큰.

• Pro: 0.48 × $0.022 = $0.01056 + 0.12 × $0.66 = $0.0792 + $0.0594(출력) = $0.14916.
• Flash: 0.48 × $0.003 = $0.00144 + 0.12 × $0.15 = $0.018 + $0.018(출력) = $0.03744.

이 변형은 캐시되지 않은 토큰에 대해 일반 입력 가격을 청구하며, 레코드에 나열되지 않은 flash의 캐시 쓰기 비용은 무시합니다. 이 할인을 기대하기 전에 응답 또는 사용량(Usage)에서 캐시된 토큰 수를 확인하십시오. 청구 가이드는 또한 재시도가 누적되기 때문에 토큰당 최저 가격이 항상 작업 완료당 최저 비용은 아님을 경고합니다.

코딩 에이전트를 위한 도구 호출 요청

두 레코드 모두 tool-use를 나열하며, 둘 다 openai_chat_completions를 허용합니다. 아래 요청은 도구 호출 가이드(2026년 10월 3일 관측)의 필드만 사용합니다: model, messages, 그리고 type: "function"을 포함한 tools. 청구 가이드에서 응답 길이를 제한하는 방법으로 나열한 max_tokens를 추가했습니다. tool_choice는 Responses 형식에 대해서만 문서화되어 있으므로 제외했습니다.

curl https://api.tokenlab.sh/v1/chat/completions \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-pro",
    "max_tokens": 2000,
    "messages": [
      {"role": "system", "content": "You are a software engineering assistant."},
      {"role": "user", "content": "The pagination test in tests/test_api.py fails. Find the cause."}
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "read_file",
          "description": "Read a file from the repository",
          "parameters": {
            "type": "object",
            "properties": {"path": {"type": "string"}},
            "required": ["path"]
          }
        }
      },
      {
        "type": "function",
        "function": {
          "name": "run_tests",
          "description": "Run the test suite for one path",
          "parameters": {
            "type": "object",
            "properties": {"path": {"type": "string"}},
            "required": ["path"]
          }
        }
      }
    ]
  }'

모델은 tool_calls에 함수 이름과 인수를 반환합니다. 백엔드에서 도구를 실행합니다. 루프는 다음 5단계로 진행됩니다:

1. 메시지와 도구 정의를 보냅니다.
2. tool_calls에 대한 응답을 읽습니다.
3. 백엔드에서 도구를 실행합니다.
4. 동일한 API 형식으로 도구 결과를 추가합니다.
5. 모델이 최종 답변을 반환할 때까지 계속합니다.

가이드에는 도구 결과 메시지 형태가 인라인으로 표시되지 않습니다. 추측하지 말고 Create Chat Completion 참조(/api-reference/chat/create-completion)에서 가져오십시오.

호출을 실행하기 전에 인수를 검증하고 자체 권한 확인을 적용하십시오. 클라이언트 재시도가 동일한 도구 호출을 반복할 수 있으므로 실행을 멱등성(idempotent) 있게 만드십시오. 형식마다 도구 상태를 다르게 표현하므로 전체 교환에 대해 하나의 API 형식을 유지하십시오.

두 모델 간의 재시도, 백오프 및 폴백

2026년 10월 3일에 관측된 오류 가이드와 속도 제한 가이드가 정책을 설정합니다. HTTP 상태와 code에 따라 분기하고, message에 따라 분기하지 마십시오.

상태	동일한 요청 반복?	조치
400, 401, 402, 403, 404, 413	아니오	요청, 키, 잔액, 권한 또는 입력 수정
429	예	Retry-After 대기; 없으면 지터(jitter)를 포함한 지수 백오프 사용
500–504	retryable이 true일 때만	retry_after 준수 및 시도 횟수 제한
응답 전 연결 종료	경우에 따라	도구 호출이 부작용을 반복할 수 있으므로 주의하여 재시도
출력 후 스트림 중단	아니오	불완전한 것으로 처리; 반복 시 다른 출력이 생성되거나 두 번째 요금이 청구될 수 있음

두 가지 경우는 각별한 주의가 필요합니다. 503 all_channels_failed 또는 503 delivery_tier_unavailable가 항상 일시적인 것은 아닙니다. retryable이 false이고 retry_after가 없으면 요청을 반복하지 마십시오. 다른 모델을 선택하기 전에 GET /v1/models를 확인하십시오. 또한, context_length_exceeded는 두 모델 모두 동일한 1,000,000 토큰 입력 제한을 나열하므로 모델을 전환해도 해결되지 않습니다.

아래 코드는 해당 정책을 적용합니다. SDK가 자동으로 재시도하지 않도록 max_retries=0으로 설정합니다. 각 모델은 4번의 시도를 하며, 폴백은 첫 번째 모델이 재시도 가능한 오류를 모두 소진한 후에만 실행됩니다.

import os
import random
import time
from openai import OpenAI, APIStatusError, APIConnectionError

client = OpenAI(
    api_key=os.environ["TOKENLAB_API_KEY"],
    base_url="https://api.tokenlab.sh/v1",
    timeout=30.0,
    max_retries=0,
)

FALLBACK = {
    "deepseek-v4-pro": "deepseek-v4-flash",
    "deepseek-v4-flash": "deepseek-v4-pro",
}

def error_fields(exc):
    body = getattr(exc, "body", None)
    if isinstance(body, dict):
        return body.get("error", body)
    return {}

def backoff(attempt):
    return min(30, 2 ** attempt + random.random())

def retry_delay(exc, attempt):
    """대기 시간(초), 반복해서는 안 되는 경우 None 반환."""
    if isinstance(exc, APIConnectionError):
        return backoff(attempt)
    fields = error_fields(exc)
    header = exc.response.headers.get("Retry-After")
    if exc.status_code == 429:
        return float(header) if header else backoff(attempt)
    if exc.status_code >= 500 and fields.get("retryable") is True:
        wait = fields.get("retry_after") or header
        return float(wait) if wait else backoff(attempt)
    return None

def chat_with_fallback(model, messages, tools=None, attempts=4):
    last_exc = None
    for candidate in (model, FALLBACK[model]):
        kwargs = {"model": candidate, "messages": messages}
        if tools:
            kwargs["tools"] = tools
        for attempt in range(attempts):
            try:
                return candidate, client.chat.completions.create(**kwargs)
            except (APIStatusError, APIConnectionError) as exc:
                delay = retry_delay(exc, attempt)
                if delay is None:
                    raise  # 4xx 또는 재시도 불가능한 5xx: 반복하거나 폴백하지 않음
                last_exc = exc
                if attempt < attempts - 1:
                    time.sleep(delay)
        print(f"{candidate} 재시도 소진, {FALLBACK[candidate]} 시도 중")
    raise last_exc

def pick_model(is_complex):
    return "deepseek-v4-pro" if is_complex else "deepseek-v4-flash"

used, response = chat_with_fallback(
    pick_model(is_complex=False),
    [{"role": "user", "content": "Write a pytest case: an empty list returns 0 for sum_items()."}],
)
print(used, response.choices[0].message.content)

어떤 모델이 응답했는지 항상 기록하십시오. 코딩 에이전트 가이드는 폴백 시 가격, 컨텍스트 제한, 도구 형식 또는 출력 스타일이 변경될 수 있으므로 모델이 변경되면 사용자에게 알릴 것을 경고합니다. flash에서 pro로 폴백하면 정가 기준으로 입력 비용이 대략 4배 증가하므로 이에 대해 경고하십시오. 지원팀이 오류를 추적할 수 있도록 각 호출 시 응답 헤더의 요청 ID를 저장하십시오.

라우팅 전 제한, 형식 및 가격 확인

2026년 10월 3일에 관측된 Get a Model 참조는 GET /v1/models/:model을 설명합니다. 응답에는 capabilities, pricing, max_input_tokens, max_output_tokens, accepted_request_formats, lifecycle이 포함된 tokenlab 객체가 있습니다. 알 수 없는 모델은 404 model_not_found를 반환합니다. 청구 가이드는 또한 현재 가격을 확인하기 위해 GET /v1/models/:model/pricing을 참조하도록 안내합니다.

import json
import urllib.request

def read_model(model_id):
    url = f"https://api.tokenlab.sh/v1/models/{model_id}"
    with urllib.request.urlopen(url, timeout=10) as resp:
        meta = json.load(resp)["tokenlab"]
    return {
        "max_input_tokens": meta.get("max_input_tokens"),
        "max_output_tokens": meta.get("max_output_tokens"),
        "formats": meta.get("accepted_request_formats"),
        "capabilities": meta.get("capabilities"),
        "lifecycle": meta.get("lifecycle"),
        "pricing": meta.get("pricing"),
    }

def preflight(model_id, input_tokens):
    info = read_model(model_id)
    problems = []
    if "openai_chat_completions" not in (info["formats"] or []):
        problems.append("chat completions not accepted")
    if "tool-use" not in (info["capabilities"] or []):
        problems.append("no tool-use capability")
    if info["max_input_tokens"] and input_tokens > info["max_input_tokens"]:
        problems.append("input exceeds max_input_tokens")
    return info, problems

for model_id in ("deepseek-v4-pro", "deepseek-v4-flash"):
    info, problems = preflight(model_id, input_tokens=30_000)
    print(model_id, json.dumps(info, indent=2), problems)

이 기사의 증거로는 해당 응답 내의 정확한 JSON 레이아웃을 보여줄 수 없으므로 lifecycle과 pricing은 원시 데이터로 출력합니다. 출력을 한 번 검사한 다음 필요한 필드를 파싱하십시오. 문서는 복사된 가격 표를 하드코딩하지 말 것을 권장하므로 시작 시 또는 일정에 따라 점검을 실행하십시오. GET /v1/models와 같은 공개 검색 엔드포인트에는 자체 속도 제한이 있으므로 요청당 호출하는 대신 결과를 캐시하십시오.

속도 제한의 경우, 2026년 10월 3일에 관측된 바와 같이 표준 사용자 계층은 API 키당 분당 1,000개의 요청을 허용합니다. 가이드에 따르면 활성 구성은 다를 수 있습니다. 429 오류 발생 시, 복사된 숫자보다 반환된 X-RateLimit-Limit 및 Retry-After 값을 신뢰하십시오.

FAQ

Anthropic Messages 형식을 통해 deepseek-v4-pro를 호출할 수 있습니까?

네. 2026년 10월 3일에 관측된 바와 같이 두 레코드 모두 허용된 형식에 anthropic_messages를 나열합니다. 코딩 에이전트 가이드는 Anthropic Messages 기본 URL을 Chat Completions가 사용하는 /v1 접미사 없이 https://api.tokenlab.sh로 제공합니다. 도구 스키마는 형식에 따라 다르므로 전체 대화에 대해 하나의 형식을 유지하십시오.

deepseek-v4-pro 또는 deepseek-v4-flash에서 발생하는 503 오류를 재시도해야 합니까?

오류 본문에 retryable이 true라고 명시된 경우에만 재시도하고, retry_after를 기다리십시오. retryable: false인 503 all_channels_failed는 선택한 전달 계층에 요청 공급이 없음을 의미합니다. 반복해도 도움이 되지 않습니다. 오류 가이드에 설명된 대로 다른 모델을 선택하기 전에 GET /v1/models를 확인하십시오.

deepseek-v4.1-flash가 deepseek-v4-flash를 대체합니까?

카탈로그는 그렇게 명시하지 않습니다. 2026년 10월 3일 기준 deepseek-v4-flash 레코드는 대체 모델을 표시하지 않았으며, deepseek-v4.1-flash는 활성 상태를 표시했습니다. 두 모델은 제한과 정가를 공유하며, 최신 모델은 reasoning 및 vision 기능을 추가합니다. 작업에서 테스트해 보고 모델 ID로 신중하게 전환하십시오.

캐시된 토큰이 에이전트 루프에서 deepseek-v4-flash를 더 저렴하게 만듭니까?

그럴 수 있습니다. 레코드는 일반 입력 $0.15에 대해 100만 토큰당 $0.003의 오프피크 캐시 읽기 가격을 나열합니다. 비용 가이드는 할인을 기대하기 전에 응답 또는 사용량에서 캐시된 토큰 사용량을 확인하라고 조언합니다. 캐시 동작과 가격은 모델마다 다릅니다.

deepseek-v4-flash로 라우팅하면 속도 제한이 올라갑니까?

아니오. 속도 제한 가이드에 따르면 더 빠른 모델을 사용한다고 해서 계정의 요청 제한이 올라가지 않습니다. 모델 속도, 토큰 제한, 계정 속도 제한은 별도의 제약 조건이며, 제한은 API 키당 적용됩니다.

라우터를 연결하기 전에 TokenLab 모델 페이지에서 현재 deepseek-v4-pro 및 deepseek-v4-flash 항목을 확인하십시오.