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 기반 워크플로우를 다룹니다.
<!--kg-card-begin: html-->
<!--kg-card-end: html-->
제품 수준 개요는 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및 Nodeopenai@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를 반환합니다.
요청 매개변수
모든 필드는 비용 및 결과 동작에 직접 연결됩니다. 주요 매개변수 정리:
| 매개변수 | 유형 | 값 | 참고 |
|---|---|---|---|
model |
문자열 |
deepseek-v4-pro, deepseek-v4-flash
|
필수. |
messages |
배열 | role/content 쌍 | 필수. OpenAI와 동일한 스키마. |
thinking_mode |
문자열 |
non-thinking, thinking, thinking_max
|
기본값은 non-thinking. |
temperature |
부동 소수점 | 0 ~ 2 | DeepSeek은 1.0을 권장. |
top_p |
부동 소수점 | 0 ~ 1 | DeepSeek은 1.0을 권장. |
max_tokens |
정수 | 1 ~ 131,072 | 출력 길이 제한. |
stream |
부울 | true 또는 false | SSE 스트리밍 활성화. |
tools |
배열 | OpenAI 도구 사양 | 함수 호출용. |
tool_choice |
문자열 또는 객체 |
auto, required, none, 또는 특정 도구 |
도구 사용 제어. |
response_format |
객체 | {"type": "json_object"} |
JSON 모드 출력. |
seed |
정수 | 모든 정수 | 재현성을 위해. |
presence_penalty |
부동 소수점 | -2 ~ 2 | 반복되는 주제에 불이익. |
frequency_penalty |
부동 소수점 | -2 ~ 2 | 반복되는 토큰에 불이익. |
-
thinking_mode는 비용에 가장 큰 영향을 줍니다.non-thinking은 추론 없이 빠르게 응답하며,thinking은 코드/수학 정확도를 높여주지만 토큰 비용이 추가됩니다.thinking_max는 가장 높은 품질과 함께 많은 토큰을 소모합니다.
Python 클라이언트
OpenAI 공식 SDK를 사용하면 base_url만 교체하여 바로 DeepSeek V4에 연결할 수 있습니다.
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는 별도 래퍼 없이 thinking_mode 등 커스텀 필드를 바로 전달할 수 있습니다.
스트리밍 응답
stream: true로 설정하면, OpenAI와 동일하게 SSE로 응답을 받을 수 있습니다.
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로 추론 트레이스를 별도로 받을 수 있습니다.
도구 호출
V4는 OpenAI 도구 호출 스키마를 그대로 지원합니다. 함수 정의와 호출 패턴은 OpenAI와 동일하게 적용됩니다.
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" 메시지로 추가하고, 동일한 패턴으로 루프를 반복 호출하여 완성형 워크플로우를 구현할 수 있습니다.
JSON 모드
구조화된 JSON 출력을 강제하려면 response_format을 사용하십시오.
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에서 컬렉션 구축
터미널에서 직접 반복 호출은 비효율적이며, 실행 간 차이가 드러나지 않습니다. 실제 워크플로우를 위해 아래 절차를 따르세요.
- Apidog를 다운로드하고 프로젝트를 생성합니다.
-
{{DEEPSEEK_API_KEY}}를 비밀 변수로 저장한 환경을 추가합니다. -
Authorization: Bearer {{DEEPSEEK_API_KEY}}헤더로{{BASE_URL}}/chat/completionsPOST 요청을 저장합니다. -
model과thinking_mode를 변수로 만들어 A/B 테스트가 쉽도록 만듭니다. - 응답 뷰어에서
usage.reasoning_tokens를 항상 확인하여 사고 모드 비용을 추적합니다.
이미 Apidog에서 GPT-5.5 API 컬렉션을 사용하는 경우, 복제 후 base_url과 모델 ID만 바꿔 바로 비교 워크플로우를 구성할 수 있습니다.
오류 처리
OpenAI 응답 포맷과 동일하므로, 아래 표를 참조해 오류를 신속하게 진단하세요.
| 코드 | 의미 | 해결책 |
|---|---|---|
| 400 | 잘못된 요청 | JSON 스키마, 특히 messages 및 tools 확인 |
| 401 | 유효하지 않은 키 | platform.deepseek.com에서 키 재생성 |
| 402 | 잔액 부족 | 계정에 충전 |
| 403 | 모델 허용 안됨 | 키 범위/모델 ID 철자 확인 |
| 422 | 매개변수 범위 초과 |
max_tokens 또는 thinking_mode 확인 |
| 429 | 속도 제한 | 잠시 대기 후 지수적 지터로 재시도 |
| 500 | 서버 오류 | 한 번 재시도, 반복되면 상태 페이지 확인 |
| 503 | 과부하 | V4-Flash 대체 또는 30초 후 재시도 |
429/5xx는 지수 백오프와 함께 재시도 헬퍼로 감싸고, 4xx는 논리 오류이므로 자동 재시도를 하지 마세요.
비용 관리 패턴
비용 예측과 통제는 다음과 같이 접근하세요.
- 기본적으로 V4-Flash를 사용하고, 품질이 반드시 중요한 프롬프트만 V4-Pro로 전환합니다.
-
thinking_max는 플래그로 관리하세요. 고비용 모드이므로 꼭 필요할 때만 활성화합니다. -
max_tokens제한: 대부분의 답변은 2,000 토큰 이내. 1M 컨텍스트는 입력용입니다. -
모든 호출에
usage기록: 입력/출력/추론 토큰을 모니터링 스택에 전송하고, 급격한 변동에 알림을 걸어둡니다.
이전 DeepSeek 모델에서 마이그레이션
2026년 7월 24일까지 이전 모델 ID(deepseek-chat, deepseek-reasoner)를 deepseek-v4-pro로 변경해야 합니다. 호출부 한 줄만 바꾸면 됩니다.
- model="deepseek-chat"
+ model="deepseek-v4-pro"
전환 전 Apidog에서 A/B 비교를 실행해 품질 차이를 직접 확인하고, 변경 후 운영에 반영하세요.
FAQ
DeepSeek V4 API는 프로덕션 준비가 되었습니까?
네. 2026년 4월 23일 라이브 출시, 1년 이상 검증된 인프라 기반입니다.
V4는 Anthropic 메시지 형식을 지원합니까?
네. https://api.deepseek.com/anthropic/v1/messages 엔드포인트를 사용하세요.
컨텍스트 창 크기는?
V4-Pro, V4-Flash 모두 100만 토큰. thinking_max에는 최소 384K 권장.
전송 전 입력 토큰 계산은?
OpenAI 토크나이저로 근사치 산출, 실제 비용은 응답의 usage 참고.
API로 미세 조정(finetune) 가능합니까?
불가. 미세 조정은 Hugging Face 체크포인트를 통해 별도 진행.
API를 무료로 써볼 수 있습니까?
계정 무료 티어는 없으나, 신규 가입자에 한해 평가판 크레딧이 제공될 수 있습니다.
Top comments (0)