DeepSeek V4 API 사용법

DeepSeek V4가 출시되었으며, API는 첫날부터 라이브로 제공됩니다. 모델 ID는 deepseek-v4-pro와 deepseek-v4-flash이며, 엔드포인트는 OpenAI와 호환되고, 기본 URL은 https://api.deepseek.com입니다. 이는 이미 GPT-5.5 또는 다른 OpenAI 호환 API에 사용하던 모든 클라이언트가 기본 URL만 변경하면 V4에 대해 작동한다는 의미입니다.

이 가이드는 인증, 모든 주요 매개변수, Python 및 Node 예제, 사고 모드 수학, 도구 호출, 스트리밍, 그리고 반복 작업 중에도 비용을 명확하게 파악할 수 있는 Apidog 기반 워크플로우를 다룹니다.

제품 수준 개요는 DeepSeek V4란 무엇인가를 참조하십시오. 무료 경로는 DeepSeek V4를 무료로 사용하는 방법을 참조하십시오.

요약

• DeepSeek V4는 https://api.deepseek.com/v1/chat/completions의 OpenAI 호환 엔드포인트와 https://api.deepseek.com/anthropic의 Anthropic 호환 엔드포인트에서 제공됩니다.
• 모델 ID: deepseek-v4-pro (총 1.6T, 활성 49B) 및 deepseek-v4-flash (총 284B, 활성 13B).
• 두 변형 모두 1M 토큰 컨텍스트와 세 가지 추론 모드를 지원합니다: non-thinking, thinking, thinking_max.
• DeepSeek 권장 사항에 따라 temperature=1.0, top_p=1.0을 사용하십시오. GPT-5.5 또는 Claude 기본값을 가져오지 마십시오.
• 레거시 ID인 deepseek-chat 및 deepseek-reasoner는 2026년 7월 24일에 사용 중단됩니다. 그 전에 마이그레이션하십시오.
• 요청을 재생하고, 사고 모드를 비교하고, 키가 셸 기록에 남지 않도록 Apidog 다운로드하십시오.

사전 요구 사항

첫 요청을 보내기 전에 네 가지를 준비하십시오.

• 최소 $2가 충전된 platform.deepseek.com의 DeepSeek 개발자 계정. 잔액이 없으면 402 Insufficient Balance 오류가 반환됩니다.
• 청구할 프로젝트 범위에 맞는 API 키. 프로젝트 범위 키는 프로덕션 환경에서 계정 키보다 안전합니다.
• OpenAI 호환 기본 URL에 요청을 보낼 수 있는 SDK. Python openai>=1.30.0 및 Node openai@4.x는 모두 수정 없이 작동합니다.
• 터미널에 스팸을 보내지 않고 요청을 재생할 수 있는 API 클라이언트. curl은 한 번의 호출에는 작동하지만, 그 이후에는 Apidog를 사용하십시오.

키를 한 번 익스포트하십시오:

export DEEPSEEK_API_KEY="sk-..."

엔드포인트 및 인증

두 개의 기본 URL은 두 가지 요청 형식을 다룹니다.

POST https://api.deepseek.com/v1/chat/completions    # OpenAI 형식
POST https://api.deepseek.com/anthropic/v1/messages  # Anthropic 형식

기존 Anthropic 형식의 코드베이스가 없다면 OpenAI 호환 형식을 선택하십시오. 이 가이드의 나머지 부분에서는 OpenAI 형식을 사용합니다.

인증은 표준 Authorization 헤더의 베어러 토큰입니다. 최소 작동 요청:

curl https://api.deepseek.com/v1/chat/completions \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-pro",
    "messages": [
      {"role": "user", "content": "MoE 라우팅을 두 문장으로 설명해주세요."}
    ]
  }'

성공적인 응답은 choices 배열, 입력 및 출력 토큰으로 분류된 usage 블록 (사고 모드가 켜져 있으면 reasoning_tokens 포함), 그리고 추적에 사용할 수 있는 id가 포함된 JSON 본문을 반환합니다. 실패 시에는 error.code 및 error.message가 포함된 표준 OpenAI 봉투를 반환합니다.

요청 매개변수

모든 필드는 비용 또는 동작에 매핑됩니다. 다음은 deepseek-v4-pro 및 deepseek-v4-flash에 대한 맵입니다.

thinking_mode는 가장 큰 비용 지렛대입니다. non-thinking은 추론 추적을 완전히 건너뛰고 대략 V3.2 속도로 토큰을 반환합니다. thinking은 추가 토큰 비용이 들지만 코드 및 수학 정확도를 향상시키는 추론 블록을 활성화합니다. thinking_max는 DeepSeek의 헤드라인 테이블에 있는 점수를 생성합니다. 또한 가장 많은 토큰을 소모하며 384K+ 컨텍스트 예산이 필요한 유일한 모드입니다.

Python 클라이언트

공식 openai SDK는 기본 URL 재정의와 함께 작동합니다. LangChain, LlamaIndex, DSPy를 포함한 모든 기존 OpenAI 호환 래퍼도 작동합니다.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com/v1",
)

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[
        {"role": "system", "content": "코드만으로 답해주세요."},
        {"role": "user", "content": "이벤트를 디바운싱하는 Rust 함수를 작성해주세요."},
    ],
    extra_body={"thinking_mode": "thinking"},
    temperature=1.0,
    top_p=1.0,
    max_tokens=2048,
)

choice = response.choices[0]
print("내용:", choice.message.content)
print("추론 토큰:", response.usage.reasoning_tokens)
print("총 토큰:", response.usage.total_tokens)

extra_body 트릭은 라이브러리를 패치하지 않고 OpenAI SDK를 통해 DeepSeek 특정 매개변수를 전달하는 방법입니다.

Node 클라이언트

Node에서도 동일한 구조입니다:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.DEEPSEEK_API_KEY,
  baseURL: "https://api.deepseek.com/v1",
});

const response = await client.chat.completions.create({
  model: "deepseek-v4-flash",
  messages: [
    { role: "user", content: "뮤온 최적화 도구를 일반적인 용어로 설명해주세요." },
  ],
  thinking_mode: "thinking",
  temperature: 1.0,
  top_p: 1.0,
});

console.log(response.choices[0].message.content);
console.log("사용량:", response.usage);

Node SDK는 알 수 없는 필드를 자동으로 받아들이므로 extra_body 없이 thinking_mode가 최상위 수준에서 전달됩니다.

스트리밍 응답

stream: true로 설정하고 SSE 청크를 반복합니다. 형식은 OpenAI와 정확히 일치합니다.

stream = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content": "MoE에 대한 300단어 에세이를 스트리밍해주세요."}],
    stream=True,
    extra_body={"thinking_mode": "non-thinking"},
)

for chunk in stream:
    delta = chunk.choices[0].delta.content or ""
    print(delta, end="", flush=True)

사고 모드가 켜져 있을 때 추론 추적은 별도로 스트리밍됩니다. delta.reasoning_content 필드가 이를 전달하며 UI에 표시하거나 삭제할 수 있습니다.

도구 호출

V4는 표준 OpenAI 도구 호출 스키마를 지원합니다. tools 배열에 정의된 함수는 호출 가능하며, 모델이 언제 호출할지 결정합니다.

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "도시의 현재 날씨를 반환합니다.",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string"},
                "unit": {"type": "string", "enum": ["c", "f"]},
            },
            "required": ["city"],
        },
    },
}]

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content": "라고스의 날씨는 섭씨로?"}],
    tools=tools,
    tool_choice="auto",
    extra_body={"thinking_mode": "thinking"},
)

tool_call = response.choices[0].message.tool_calls[0]
print(tool_call.function.name, tool_call.function.arguments)

여기서부터 함수를 호출하고, 결과를 role: "tool" 메시지로 추가하고, API를 다시 호출하여 루프를 계속합니다. 이 패턴은 OpenAI 및 Anthropic 도구 사용 루프와 동일합니다.

JSON 모드

구조화된 출력을 위해 JSON을 명시적으로 요청하고 응답 형식을 설정하십시오.

response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[
        {"role": "system", "content": "단일 JSON 객체로 답변해주세요."},
        {"role": "user", "content": "이 릴리스 노트를 {제목, 날짜, 불릿}으로 요약해주세요: ..."},
    ],
    response_format={"type": "json_object"},
    extra_body={"thinking_mode": "non-thinking"},
)

JSON 모드는 유효한 JSON을 강제하지만 특정 스키마를 강제하지는 않습니다. 스키마 유효성 검사를 위해서는 클라이언트 측에서 Pydantic 또는 Zod와 함께 사용하십시오.

Apidog에서 컬렉션 구축

터미널에서 요청을 재생하는 것은 크레딧을 소모하고 실행 간의 차이를 숨깁니다. 실제 사용에 견딜 수 있는 워크플로우:

1. Apidog를 다운로드하고 프로젝트를 생성합니다.
2. {{DEEPSEEK_API_KEY}}가 비밀 변수로 저장된 환경을 추가합니다.
3. Authorization: Bearer {{DEEPSEEK_API_KEY}} 헤더를 사용하여 {{BASE_URL}}/chat/completions에 대한 POST 요청을 저장합니다.
4. 요청을 중복할 필요 없이 변형 간에 A/B 테스트를 할 수 있도록 model 및 thinking_mode를 매개변수화합니다.
5. 응답 뷰어를 사용하여 모든 실행에서 usage.reasoning_tokens를 검사합니다. 이는 필요하지 않은 사고 모드에 비용을 지불하고 있는지 여부를 가장 명확하게 보여주는 단일 신호입니다.

이미 Apidog에서 일치하는 GPT-5.5 API 컬렉션을 실행하고 있는 팀은 이를 복제하고, 기본 URL을 https://api.deepseek.com/v1로 변경하고, 모델 ID를 변경한 후 몇 분 만에 두 공급자 간에 비교 프롬프트를 실행할 수 있습니다.

오류 처리

봉투는 OpenAI를 정확히 따릅니다. 먼저 발생할 수 있는 것들:

429 및 5xx 오류를 지수적 백오프와 함께 처리하는 재시도 헬퍼로 호출을 래핑하십시오. 4xx 오류는 자동으로 재시도하지 마십시오. 이는 일시적인 실패가 아니라 논리적 버그입니다.

비용 관리 패턴

네 가지 패턴으로 지출을 예측 가능하게 유지할 수 있습니다.

1. 기본적으로 V4-Flash를 사용합니다. 품질 향상을 측정한 프롬프트에만 V4-Pro로 전환하십시오.
2. thinking_max를 플래그 뒤에 숨깁니다. 이는 가장 비싼 모드이므로, 정확성이 지연 시간보다 중요할 때만 사용하십시오.
3. max_tokens를 제한합니다. 대부분의 답변은 2,000개 출력 토큰 안에 들어옵니다. 1M 컨텍스트는 입력용이며 출력용이 아닙니다.
4. 모든 호출에 usage를 기록합니다. 입력, 출력 및 추론 횟수를 관찰 가능성 스택에 보내십시오. 갑작스러운 추론 토큰 급증에 대한 경고는 변경된 프롬프트를 잡아냅니다.

이전 DeepSeek 모델에서 마이그레이션

이전 deepseek-chat 및 deepseek-reasoner ID는 2026년 7월 24일에 사용 중단됩니다. 마이그레이션은 호출 위치당 한 줄의 차이만 필요하며, 요청 및 응답 형식은 변경되지 않습니다.

-  model="deepseek-chat"
+  model="deepseek-v4-pro"

운영 환경에 적용하기 전에 Apidog에서 A/B 비교를 동시에 실행하십시오. 응답 품질 향상은 일반적으로 전환에 대한 보상이 되며, 사용 중단 기한은 어쨌든 이를 강제합니다.

FAQ

DeepSeek V4 API는 프로덕션 준비가 되었습니까?네. API는 가중치와 함께 2026년 4월 23일에 라이브로 제공되었습니다. DeepSeek V3 및 V3.2는 1년 이상 동일한 인프라에서 대규모로 실행되었으므로 API 표면은 성숙합니다.

V4는 Anthropic 메시지 형식을 지원합니까?네. https://api.deepseek.com/anthropic/v1/messages를 가리키고 Anthropic 형식 페이로드를 보내십시오. 두 형식 모두 동일한 기본 모델을 사용합니다.

컨텍스트 창은 얼마입니까?V4-Pro와 V4-Flash 모두 100만 토큰입니다. Think Max 모드는 최소 384K의 작업 창을 권장합니다.

전송 전에 입력 토큰을 어떻게 계산합니까?근사치를 위해서는 표준 OpenAI 토크나이저를 사용하십시오. DeepSeek은 모든 응답의 usage 블록에 정확한 수를 게시합니다. 프로덕션 예산 책정을 위해서는 응답 측 수를 신뢰하십시오.

API를 통해 미세 조정할 수 있습니까?출시 시점에는 안 됩니다. 미세 조정은 현재 Hugging Face의 자체 호스팅 Base 체크포인트를 통해 실행됩니다.

API를 무료로 사용해 볼 수 있습니까?계정 수준의 무료 티어는 없지만, 신규 가입자에게는 가끔 평가판 크레딧이 제공됩니다.