DeepSeek-V4-Pro-0813은 2026년 8월 12일에 `https://api.deepseek.com`에서 상시 운영되는 `deepseek-v4-pro` 모델 ID를 통해 일반에 공개되었으며, 더 저렴한 `deepseek-v4-flash`와 함께 제공됩니다(Unite.AI가 GA 발표를 보도했습니다). 주요 사양은 강력합니다: 1M 토큰 컨텍스트 윈도우, 384K 최대 출력, 도구 호출, 구조화된 출력, 그리고 모델의 추론 과정을 `reasoning_content` 필드에 나타내는 세 가지 사고 모드를 제공합니다.
특이한 점은 사양이 아닙니다. 하나의 모델이 세 가지 API 방언으로 응답한다는 것입니다. V4 Pro는 OpenAI ChatCompletions 요청, Anthropic Messages 요청, 그리고 DeepSeek 자체 Responses API 요청을 허용합니다. 기존 OpenAI SDK 코드를 연결하거나, Claude 기반 에이전트를 연결하거나, Codex 스타일 에이전트 루프에 연결할 수 있으며, 동일한 가중치로 세 가지 와이어 형식을 사용할 수 있습니다.
아직 아무도 세 가지 DeepSeek V4 Pro API 형식을 나란히 비교하지 않았으므로, 이 가이드에서 비교합니다. 각 형식별로 작동하는 요청 예시, 실제로 다른 모양, 비교표, 그리고 공유 환경 변수를 사용하여 단일 Apidog 프로젝트에서 세 가지 모두를 테스트하는 방법을 확인할 수 있습니다. 계정 설정 및 첫 호출 과정을 원하시면 DeepSeek V4 API 사용 방법부터 시작하여 다시 돌아오세요.
요약
- DeepSeek-V4-Pro-0813은 `https://api.deepseek.com`에서 `deepseek-v4-pro`를 통해 GA 되었으며, `deepseek-v4-flash`는 더 낮은 가격으로 동일한 인터페이스를 공유합니다.
- 세 가지 API 형식을 지원합니다: OpenAI ChatCompletions (`base_url` 변경으로 표준 `openai` SDK와 작동), Anthropic Messages (Claude Code를 포함한 `anthropic`-SDK 형태의 요청을 위한 드롭인), 그리고 DeepSeek의 Responses API (Codex 스타일 에이전트 및 상태 저장 워크플로우를 위해 구축된 최신 인터페이스).
- 사양: 1M 컨텍스트, 384K 최대 출력, 도구 호출, 구조화된 출력, `reasoning_content`를 포함한 세 가지 사고 모드.
- 가격: 입력 토큰당 $0.435/M (캐시 미스), 캐시 히트 시 $0.003625/M, 출력 토큰당 $0.87/M.
- 형식은 시스템 프롬프트 배치, `max_tokens` 의미론, 도구 스키마 모양, 스트리밍 이벤트 모양에서 차이가 있으며, 자세한 내용은 아래에 있습니다.
- `{{DEEPSEEK_API_KEY}}`와 형식별 기본 URL 변수를 사용하는 하나의 Apidog 프로젝트를 통해 동일한 프롬프트를 세 가지 모두에 보내고 원시 응답을 비교할 수 있습니다.
하나의 모델이 세 가지 방언을 사용하는 이유
이는 생태계 호환성을 위한 전략입니다. 모든 API 형식은 DeepSeek이 무료로 얻는 도구의 설치 기반입니다. ChatCompletions는 공용어이며, 수천 개의 SDK와 프레임워크가 `base_url` 한 줄 변경으로 V4 Pro를 호출할 수 있습니다. Anthropic Messages 형식은 Claude를 기반으로 구축된 팀을 대상으로 합니다. 에이전트, 평가 도구, Claude Code와 같은 도구는 코드 재작성 없이 V4 Pro를 사용할 수 있습니다. 그리고 Responses API는 DeepSeek의 에이전트에 대한 베팅입니다. `deepseek-v4-flash`는 7월에 Codex 스타일 호환성을 위해 이를 도입했으며, V4 Pro는 상태 저장, 다단계 워크플로우를 위해 GA와 함께 이를 제공합니다.
V4 Pro는 애그리게이터에도 등록되어 있지만(deepseek-v4-pro-0813에 대한 OpenRouter 페이지 참조), 세 가지 형식 이야기는 DeepSeek의 자체 API에 적용되며, 이 글에서 테스트하는 내용입니다. V4 제품군에 대한 더 넓은 시야를 원하시면 DeepSeek V4 사용 방법을 참조하십시오.
형식 1: OpenAI ChatCompletions
이것은 이미 익숙한 형태입니다: `role: "system"`을 가진 첫 번째 메시지로 시스템 프롬프트가 함께 전달되는 `messages` 배열과, 선택적인 최대 토큰 제한이 있습니다. 설정은 세 가지 형식 모두 동일하므로, 한 번만 설명합니다: DeepSeek API 키, DeepSeek의 기본 URL, 그리고 `model`을 `deepseek-v4-pro` (또는 `deepseek-v4-flash`)로 설정합니다. 엔드포인트와 본문 형태만 변경됩니다.
from openai import OpenAI
client = OpenAI(
api_key="YOUR_DEEPSEEK_API_KEY",
base_url="https://api.deepseek.com",
)
response = client.chat.completions.create(
model="deepseek-v4-pro",
messages=[
{"role": "system", "content": "You are a precise technical writer."},
{"role": "user", "content": "Explain idempotency keys in two sentences."}
],
)
print(response.choices[0].message.content)
새로운 SDK나 새로운 인증 방식은 없습니다. 도구 호출은 익숙한 중첩된 `function` 형태를 사용하며, 스트리밍은 `data: [DONE]`으로 끝나는 `chat.completion.chunk` 델타로 도착하여 OpenAI 사양과 일치합니다. V4 관련 한 가지 유의할 점: 사고 모드가 활성화되면 추론 추적은 `content`와 함께 별도의 `reasoning_content` 필드에 도착하므로, 파서는 추가 필드를 허용해야 합니다.
언제 사용해야 하는가: 기존 OpenAI 도구, LangChain 스타일 프레임워크 또는 이미 ChatCompletions를 지원하는 내부 라이브러리가 있는 경우입니다. 이는 마찰이 가장 적고 확인하기 가장 쉬운 경로이며, Apidog로 ChatGPT API 테스트하기에서 다룬 내용과 요청 구조가 동일하며, 호스트와 모델만 변경됩니다.
형식 2: Anthropic Messages
Messages 형식은 언뜻 보기에 비슷해 보이지만, 단순한 번역을 방해하는 방식으로 다릅니다. Anthropic 사양에서 상속된 세 가지 주요 차이점이 있습니다.
- 시스템 프롬프트가 배열 밖으로 이동합니다. 이것은 최상위 `system` 매개변수이며, `messages` 배열은 `user`와 `assistant`의 번갈아 가며 하는 차례만 포함합니다.
- `max_tokens`는 필수로, 선택 사항이 아닙니다. 모든 요청은 명시적인 출력 예산을 선언해야 합니다. V4 Pro의 384K 최대 출력은 넉넉한 한도이지만, 이를 명시해야 합니다.
- 도구 정의는 평면적입니다. 각 도구는 최상위 수준에서 `name`, `description`, `input_schema`를 가지며, 중첩된 `function` 래퍼는 없습니다. 도구 호출은 `tool_use` 콘텐츠 블록으로 돌아오며, 결과는 사용자 메시지 내의 `tool_result` 블록으로 반환합니다.
Python, Messages request through the `anthropic` SDK:
import os
import anthropic
client = anthropic.Anthropic(
api_key=os.environ["DEEPSEEK_API_KEY"],
base_url="https://api.deepseek.com/anthropic", # Anthropic-compatible base; confirm current path in DeepSeek's docs
)
message = client.messages.create(
model="deepseek-v4-pro",
max_tokens=8192,
system="You are a precise technical writer.",
messages=[
{"role": "user", "content": "Explain idempotency keys in two sentences."}
],
)
print(message.content[0].text)
응답은 단일 문자열이 아닌 콘텐츠 블록 목록으로 돌아오며, 스트리밍은 균일한 청크 대신 `message_start`, `content_block_delta`, `message_stop`과 같은 유형화된 SSE 이벤트를 사용합니다. 인증은 베어러 토큰 대신 Anthropic 사양의 헤더 규칙을 따릅니다. DeepSeek API 문서는 호환되는 인터페이스의 현재 세부 정보를 제공합니다.
실질적인 이점은 에이전트입니다. Claude Code와 같은 도구는 환경 변수에서 엔드포인트를 읽기 때문에, 코드 변경 없이 Claude 기반 에이전트를 DeepSeek으로 연결할 수 있습니다.
export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
export ANTHROPIC_AUTH_TOKEN=$DEEPSEEK_API_KEY
export ANTHROPIC_MODEL=deepseek-v4-pro
언제 사용해야 하는가: Claude를 기반으로 도구를 구축한 경우입니다. 팀에서 이미 Anthropic 모델에 Messages 형태의 요청을 보내고 있다면(저희 Claude Opus 5 API 가이드에서 다룬 동일한 구조), 이 형식을 통해 동일한 요청 본문과 동일한 스트리밍 핸들러로 동일한 환경에서 DeepSeek과 Claude를 A/B 테스트할 수 있습니다.
형식 3: DeepSeek의 Responses API
Responses API는 DeepSeek의 최신 인터페이스이며, 이 인터페이스가 존재하는 이유는 에이전트 때문입니다. V4 Flash는 7월에 Codex 스타일 에이전트가 DeepSeek 모델을 구동할 수 있도록 이를 도입했으며, V4 Pro는 첫날부터 이를 출시했습니다. 요청 형태는 OpenAI Responses 사양을 따릅니다: 단일 메시지 배열 대신 `input` (문자열 또는 유형화된 항목 목록)과 최상위 `instructions`를 보냅니다.
curl, Responses API request:
curl https://api.deepseek.com/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $DEEPSEEK_API_KEY" \
-d '{
"model": "deepseek-v4-pro",
"instructions": "You are an API review agent. Be terse.",
"input": "Review this OpenAPI diff and list any breaking changes: [diff here]",
"stream": false
}'
이 형식을 다른 두 형식과 구분하는 세 가지 특징은 모두 Responses 사양을 따릅니다.
- 상태는 서버 측에 있을 수 있습니다. 매 차례마다 전체 대화를 다시 보내는 대신, 후속 요청은 ID(사양의 `previous_response_id`)로 이전 응답을 참조할 수 있어 다단계 에이전트 루프를 저렴하게 조율할 수 있습니다.
- 출력은 단일 메시지가 아닌 유형화된 항목 목록입니다: 추론 항목, 텍스트 항목, 도구 호출 항목이 개별 엔트리로 도착하며, 이는 각 항목 유형에 따라 다르게 작동하는 에이전트에 적합합니다.
- 스트리밍은 의미론적입니다. 원시 텍스트 델타 대신 스트림은 명명된 이벤트(`response.output_text.delta`, `response.completed` 등)를 방출하므로, 에이전트는 청크를 정규식으로 파싱하지 않고도 라이프사이클 변경에 반응할 수 있습니다.
여기에도 도구 호출이 존재하며, 도구 정의 및 `function_call`/`function_call_output` 항목은 이전 형식 대신 Responses 사양에 따라 모양이 지정됩니다. DeepSeek의 구현 세부 사항이 사양을 넘어설 경우, api-docs.deepseek.com을 진실의 원천으로 간주하십시오.
언제 사용해야 하는가: 에이전트 방식 및 Codex 스타일 통합, 긴 다단계 워크플로우, 또는 서버 관리 대화 상태 및 유형화된 출력 항목이 오케스트레이션 코드를 단순화하는 모든 시스템입니다. 일반적인 채팅 완성에는 필요 이상의 복잡한 기능입니다.
세 가지 형식 나란히 비교
| OpenAI ChatCompletions | Anthropic Messages | DeepSeek Responses API | |
|---|---|---|---|
| 엔드포인트 | `api.deepseek.com`의 `POST /chat/completions` | Anthropic 호환 기본(`/anthropic`)의 `POST /v1/messages` | `api.deepseek.com`의 `POST /responses` |
| 요청 형태 | 단일 `messages` 배열, 시스템 프롬프트가 첫 메시지 | 최상위 `system` + `user`/`assistant` 메시지 교차 | 최상위 `instructions` + `input` 문자열 또는 항목 목록 |
| 출력 제한 | 선택적 최대 토큰 제한 | `max_tokens` 필수 | Responses 사양에 따른 선택적 제한 |
| 도구 정의 | 중첩: `parameters`를 가진 `function` 객체 | 평면: 도구별 `input_schema` | Responses 사양에 따른 평면 항목 |
| 도구 결과 | `role: "tool"` 메시지 | `tool_result` 콘텐츠 블록 | `function_call_output` 항목 |
| 스트리밍 | 균일한 `chat.completion.chunk` 델타, `[DONE]`으로 끝남 | 유형화된 이벤트: `message_start` → `content_block_delta` → `message_stop` | 의미론적 라이프사이클 이벤트 (`response.output_text.delta`, …) |
| 대화 상태 | 클라이언트 관리 (히스토리 재전송) | 클라이언트 관리 (히스토리 재전송) | 이전 응답 참조를 통한 서버 측 옵션 |
| 최적 사용처 | 기존 OpenAI 도구 및 프레임워크 | Claude 네이티브 도구 및 에이전트 (Claude Code) | 에이전트 루프, Codex 스타일 및 상태 저장 워크플로우 |
동일한 모델, 동일한 가격, 세 가지 계약. 차이점은 전적으로 와이어 수준에 있으며, 이는 기억에 의존하는 대신 경험적으로 확인하기 가장 쉬운 종류의 차이점입니다.
하나의 Apidog 프로젝트에서 세 가지 모두 테스트
동일한 프롬프트가 세 가지 다른 형태의 응답을 생성하는 것을 관찰하면 비교표로는 알 수 없는 구현 세부 사항을 파악할 수 있습니다. 반복 가능한 설정:
- 하나의 프로젝트에 세 개의 폴더를 생성합니다: `chat-completions`, `anthropic-messages`, `responses`. 각 폴더는 시나리오별(일반 완성, 도구 호출, 스트리밍)로 하나의 저장된 요청을 포함합니다.
- 환경 변수를 통해 자격 증명을 공유합니다. `{{DEEPSEEK_API_KEY}}`, `{{BASE_URL}}`, `{{ANTHROPIC_BASE}}`를 한 번 정의하면, 키를 교체하거나 `deepseek-v4-flash`로 전환하는 것이 한 필드 변경으로 가능해집니다.
- 동일한 프롬프트를 각 형식을 통해 전송하고 원시 본문을 비교합니다: `choices[0].message.content` 대 콘텐츠 블록 목록 대 유형화된 출력 항목.
- `stream: true`로 스트림을 검사합니다. 내장된 SSE 뷰는 차이점을 선명하게 보여줍니다: 익명 `[DONE]`으로 끝나는 청크, 명명된 메시지 이벤트, 응답 라이프사이클 이벤트. SSE 디버깅이 처음이라면 SSE로 API 응답 스트리밍하는 방법이 메커니즘을 설명합니다.
- 통합이 실제로 읽는 필드(콘텐츠 경로, 도구 호출 ID 위치, 완료 이유)에 대한 어설션을 추가하고, DeepSeek이 스냅샷 업데이트를 배포할 때마다 컬렉션을 다시 실행합니다.
세 개의 폴더 프로젝트는 살아있는 문서 역할도 합니다: "Messages 도구 스키마는 다시 어떻게 생겼더라?"라는 질문은 실제 캡처된 응답과 함께 저장된 요청이 됩니다.
마이그레이션 참고 사항
기존 코드를 V4 Pro로 옮기는 것은 의도적으로 지루하게 만들어졌으며, 그것이 핵심입니다.
OpenAI에서: `base_url`을 `https://api.deepseek.com`으로, API 키, 그리고 모델을 `deepseek-v4-pro`로 세 가지 값을 변경합니다. 메시지 구성, 도구 정의 및 스트리밍 핸들러는 그대로 유지됩니다. 배포 전에 두 가지 확인 사항: 핵심 사양을 넘어서는 매개변수가 예상대로 작동하는지 확인하고(추측하지 말고 테스트 컬렉션을 통해 실행), 응답 파싱이 `content` 옆에 `reasoning_content`가 나타나는 것을 허용하는지 확인하십시오.
Anthropic에서: 기본 URL을 Anthropic 호환 경로로 바꾸고, 키를 바꾸고, 모델을 설정합니다. Messages 형태가 그대로 유지되므로, 필수 `max_tokens`, 콘텐츠 블록, 유형화된 스트림 이벤트 등 사양을 준수하는 클라이언트는 로직 변경이 필요 없습니다. 환경 변수를 읽는 에이전트의 경우, 마이그레이션은 이전에 보여준 세 줄의 `export` 명령어입니다.
Responses API로: 이전 두 형식 중 어느 것도 기계적으로 번역되지 않으므로, 이것은 구성 변경이라기보다는 요청 레이어의 재작성입니다. 최신이기 때문이 아니라, 서버 측 상태 및 유형화된 출력 항목과 같이 이 API가 고유하게 제공하는 것을 원할 때 채택하십시오.
모든 방향에서 조언은 동일합니다: 구성을 마이그레이션한 다음, 신뢰하기 전에 회귀 테스트 컬렉션을 다시 실행하십시오. 이 가격이라면, 오후 동안의 검증 트래픽 비용은 그동안 마시는 커피보다 저렴합니다.
자주 묻는 질문
- 새로운 프로젝트는 어떤 형식을 선택해야 할까요? 가장 넓은 도구 지원을 위해 ChatCompletions를 기본값으로 사용하세요. 스택이 Claude-네이티브인 경우 Messages를 선택하세요. 다단계 에이전트를 구축하고 서버 관리 상태를 원한다면 Responses API를 선택하세요.
- Claude Code를 DeepSeek V4 Pro에 연결할 수 있나요? 네. `ANTHROPIC_BASE_URL`을 DeepSeek의 Anthropic 호환 엔드포인트로 설정하고, DeepSeek 키를 인증 토큰으로 사용하며, 모델을 `deepseek-v4-pro`로 설정하세요. 이것이 Messages 형식 지원의 실질적인 이점입니다.
- 도구 호출 및 구조화된 출력이 모든 형식에서 작동하나요? 모델은 둘 다 지원하며, 각 방언은 자체 사양의 형태로 도구 호출을 노출합니다 (중첩된 함수 객체, `input_schema` 도구 또는 Responses 스타일 항목). 배포 전에 테스트 컬렉션에서 각 인터페이스에 대해 특정 스키마를 확인하세요. 스키마 형태의 엣지 케이스는 호환되는 구현이 갈라지는 지점입니다.