DEV Community

Cover image for ChatCompletions 대 Anthropic Messages 대 Responses API: DeepSeek V4 Pro의 세 가지 API 형식 테스트
Rihpig
Rihpig

Posted on Originally published at apidog.com

ChatCompletions 대 Anthropic Messages 대 Responses API: DeepSeek V4 Pro의 세 가지 API 형식 테스트

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 필드로 제공하는 세 가지 사고 모드입니다.

지금 Apidog 사용해 보기

핵심은 모델 사양보다 하나의 모델이 세 가지 API 방언을 지원한다는 점입니다. V4 Pro는 OpenAI ChatCompletions, Anthropic Messages, DeepSeek Responses API 요청을 모두 처리합니다. 따라서 기존 OpenAI SDK 코드, Claude 기반 에이전트, Codex 스타일 에이전트 루프를 같은 모델 가중치에 연결할 수 있습니다.

이 글에서는 세 가지 형식을 실제 요청 단위로 비교합니다. 각 형식의 요청 본문, 응답 구조, 스트리밍 이벤트, 도구 호출 차이를 확인하고, 하나의 Apidog 프로젝트에서 동일한 프롬프트를 테스트하는 방법까지 다룹니다. 계정 설정과 첫 호출이 필요하다면 먼저 DeepSeek V4 API 사용 방법을 확인하세요.

요약

  • deepseek-v4-pro는 https://api.deepseek.com에서 GA 되었으며, deepseek-v4-flash는 더 낮은 가격으로 같은 인터페이스를 공유합니다.
  • 지원 형식은 세 가지입니다.
    • OpenAI ChatCompletions
    • Anthropic Messages
    • DeepSeek Responses API
  • 사양은 1M 컨텍스트, 최대 384K 출력, 도구 호출, 구조화된 출력, reasoning_content를 포함한 세 가지 사고 모드입니다.
  • 가격은 입력 토큰 $0.435/M(캐시 미스), $0.003625/M(캐시 히트), 출력 토큰 $0.87/M입니다.
  • 형식마다 시스템 프롬프트 위치, max_tokens 요구 사항, 도구 스키마, 스트리밍 이벤트 구조가 다릅니다.
  • {{DEEPSEEK_API_KEY}}와 형식별 기본 URL을 환경 변수로 관리하면 하나의 Apidog 프로젝트에서 세 형식을 비교할 수 있습니다.

하나의 모델이 세 가지 방언을 지원하는 이유

세 가지 형식은 생태계 호환성을 위한 전략입니다.

  • ChatCompletions: 가장 널리 사용되는 형식입니다. 기존 SDK와 프레임워크는 base_url만 바꿔 V4 Pro를 호출할 수 있습니다.
  • Anthropic Messages: Claude 기반 도구와 에이전트에 적합합니다. Messages 형식을 이미 사용하는 팀은 요청 로직을 크게 바꾸지 않고 DeepSeek을 테스트할 수 있습니다.
  • Responses API: 상태 저장과 다단계 작업이 필요한 에이전트 워크플로우를 위한 인터페이스입니다.

V4 Pro는 애그리게이터에도 등록되어 있습니다(OpenRouter의 deepseek-v4-pro-0813 페이지). 다만 이 글의 비교 대상은 DeepSeek 자체 API입니다. V4 제품군 전반을 먼저 살펴보려면 DeepSeek V4 사용 방법을 참고하세요.

형식 1: OpenAI ChatCompletions

기존 OpenAI ChatCompletions 형식과 동일한 구조입니다. 시스템 프롬프트는 role: "system" 메시지로 전달하고, 대화는 messages 배열에 넣습니다.

Python 요청 

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)
Enter fullscreen mode Exit fullscreen mode

구현 체크리스트

  1. base_url을 https://api.deepseek.com으로 변경합니다.
  2. 모델을 deepseek-v4-pro 또는 deepseek-v4-flash로 설정합니다.
  3. 기존 messages 구조와 도구 정의를 유지합니다.
  4. 사고 모드를 사용할 경우 content 외에 reasoning_content 필드도 파싱할 수 있게 처리합니다.
  5. 스트리밍에서는 chat.completion.chunk 델타와 마지막 data: [DONE] 이벤트를 처리합니다.

도구 호출은 OpenAI 형식의 중첩된 function 객체를 사용합니다. 기존 OpenAI SDK, LangChain 스타일 프레임워크, 내부 ChatCompletions 래퍼를 사용 중이라면 이 형식이 가장 빠른 마이그레이션 경로입니다.

요청 구조는 Apidog로 ChatGPT API 테스트하기와 유사하며, 호스트와 모델만 바꾸면 됩니다.

형식 2: Anthropic Messages

Anthropic Messages 형식은 대화 API처럼 보이지만, ChatCompletions와는 몇 가지 중요한 차이가 있습니다.

  1. 시스템 프롬프트는 messages 배열이 아니라 최상위 system 필드에 넣습니다.
  2. max_tokens는 선택 사항이 아니라 필수입니다.
  3. 도구 정의는 중첩된 function 객체가 아닌 평면 구조의 name, description, input_schema를 사용합니다.
  4. 도구 호출은 tool_use 콘텐츠 블록으로 반환되고, 도구 결과는 사용자 메시지의 tool_result 블록으로 전달합니다.

Python 요청 

import os
import anthropic

client = anthropic.Anthropic(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com/anthropic",  # 현재 경로는 DeepSeek 문서에서 확인
)

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)
Enter fullscreen mode Exit fullscreen mode

응답과 스트리밍 처리

응답 본문은 단일 문자열이 아니라 콘텐츠 블록 목록입니다.

for block in message.content:
    if block.type == "text":
        print(block.text)
Enter fullscreen mode Exit fullscreen mode

스트리밍은 균일한 텍스트 청크 대신 다음과 같은 유형화된 SSE 이벤트를 사용합니다.

message_start
content_block_delta
message_stop
Enter fullscreen mode Exit fullscreen mode

인증과 호환 엔드포인트의 최신 세부 사항은 DeepSeek API 문서에서 확인하세요.

Claude 기반 에이전트 연결

환경 변수를 읽는 도구는 다음처럼 설정할 수 있습니다.

export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
export ANTHROPIC_AUTH_TOKEN=$DEEPSEEK_API_KEY
export ANTHROPIC_MODEL=deepseek-v4-pro
Enter fullscreen mode Exit fullscreen mode

Claude Code처럼 Anthropic 환경 변수를 사용하는 도구를 연결할 때 유용합니다. 팀이 이미 Anthropic Messages 구조를 사용 중이라면, Claude Opus 5 API 가이드와 같은 요청 형태를 유지하면서 DeepSeek과 Claude를 A/B 테스트할 수 있습니다.

형식 3: DeepSeek Responses API

Responses API는 에이전트 워크플로우에 초점을 둔 최신 인터페이스입니다. ChatCompletions처럼 messages 배열을 보내는 대신, 최상위 instructions와 input을 사용합니다.

  • instructions: 시스템 수준 지시문
  • input: 문자열 또는 유형화된 항목 목록
  • previous_response_id: 이전 응답을 참조하는 상태 저장형 후속 요청에 사용

curl 요청 

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
  }'
Enter fullscreen mode Exit fullscreen mode

Responses API를 선택할 이유

1. 서버 측 상태 참조

매 요청마다 전체 대화 기록을 재전송하는 대신, 이전 응답 ID를 참조할 수 있습니다.

{
  "model": "deepseek-v4-pro",
  "previous_response_id": "resp_previous_id",
  "input": "Now summarize the highest-priority breaking change."
}
Enter fullscreen mode Exit fullscreen mode

2. 유형화된 출력 항목

출력은 단일 메시지가 아니라 추론, 텍스트, 도구 호출 같은 유형화된 항목 목록으로 도착할 수 있습니다. 에이전트는 항목 타입별로 처리 로직을 분리할 수 있습니다.

3. 의미론적 스트리밍 이벤트

스트리밍은 단순 텍스트 델타가 아니라 응답 수명 주기를 나타내는 명명된 이벤트를 사용합니다.

response.output_text.delta
response.completed
Enter fullscreen mode Exit fullscreen mode

도구 정의와 function_call/function_call_output 항목도 Responses 사양을 따릅니다. 구현 세부 사항이 불명확하면 api-docs.deepseek.com을 기준으로 확인하세요.

이 형식은 일반 챗봇보다 다음과 같은 경우에 적합합니다.

  • Codex 스타일 에이전트
  • 다단계 작업 수행
  • 서버 관리 대화 상태가 필요한 워크플로우
  • 텍스트, 도구 호출, 추론 항목을 분리해 오케스트레이션해야 하는 시스템

세 가지 형식 나란히 비교

항목 OpenAI ChatCompletions Anthropic Messages DeepSeek Responses API
엔드포인트 POST /chat/completions Anthropic 호환 기본 URL(/anthropic)의 POST /v1/messages POST /responses
요청 형태 messages 배열, 시스템 프롬프트는 첫 메시지 최상위 system + user/assistant 메시지 최상위 instructions + input
출력 제한 선택적 최대 토큰 제한 max_tokens 필수 Responses 사양에 따른 선택적 제한
도구 정의 function 객체 내부의 parameters 도구별 평면 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 네이티브 도구와 에이전트 에이전트 루프, Codex 스타일, 상태 저장 워크플로우

같은 모델과 같은 가격을 사용하더라도, 실제 통합에서는 와이어 형식의 차이가 중요합니다. 특히 도구 호출, 스트리밍, 응답 파싱 코드는 형식별로 별도 검증이 필요합니다.

하나의 Apidog 프로젝트에서 세 가지 모두 테스트하기

동일한 프롬프트를 세 형식으로 보내고 원시 응답을 비교하면 문서만 읽을 때 놓치기 쉬운 구현 차이를 확인할 수 있습니다.

1. 폴더 구조 만들기

한 프로젝트에 다음 폴더를 생성합니다.

deepseek-v4-pro/
├── chat-completions/
│   ├── basic-completion
│   ├── tool-calling
│   └── streaming
├── anthropic-messages/
│   ├── basic-completion
│   ├── tool-calling
│   └── streaming
└── responses/
    ├── basic-completion
    ├── tool-calling
    └── streaming
Enter fullscreen mode Exit fullscreen mode

2. 환경 변수 정의하기

다음 변수는 환경에 한 번만 저장합니다.

DEEPSEEK_API_KEY
BASE_URL
ANTHROPIC_BASE
MODEL
Enter fullscreen mode Exit fullscreen mode

예시 값은 다음과 같습니다.

DEEPSEEK_API_KEY={{your_key}}
BASE_URL=https://api.deepseek.com
ANTHROPIC_BASE=https://api.deepseek.com/anthropic
MODEL=deepseek-v4-pro
Enter fullscreen mode Exit fullscreen mode

MODEL만 deepseek-v4-flash로 바꾸면 같은 요청 컬렉션으로 두 모델을 비교할 수 있습니다.

3. 같은 프롬프트로 응답 경로 비교하기

세 요청에 동일한 작업을 보냅니다.

Explain idempotency keys in two sentences.
Enter fullscreen mode Exit fullscreen mode

그다음 형식별 응답 경로를 확인합니다.

형식 대표 텍스트 경로
ChatCompletions choices[0].message.content
Messages content[0].text 또는 콘텐츠 블록 순회
Responses 유형화된 output 항목에서 텍스트 추출

4. 스트리밍을 반드시 별도로 검증하기

각 요청에서 stream: true를 활성화하고 SSE 이벤트를 비교합니다.

  • ChatCompletions: 텍스트 델타 + [DONE]
  • Messages: message_start, content_block_delta, message_stop
  • Responses: response.output_text.delta, response.completed 등

SSE 디버깅이 처음이라면 SSE로 API 응답 스트리밍하는 방법을 참고하세요.

5. 회귀 테스트용 어설션 추가하기

각 요청에 다음 항목을 검증하는 어설션을 추가합니다.

  • 응답 콘텐츠 경로가 존재하는가
  • 도구 호출 ID가 예상 위치에 있는가
  • 완료 이유가 반환되는가
  • 스트리밍 종료 이벤트가 도착하는가
  • reasoning_content가 존재해도 파서가 실패하지 않는가

모델 스냅샷 업데이트나 SDK 업데이트 후에는 이 컬렉션을 다시 실행하세요. 저장된 요청과 실제 응답은 팀의 살아있는 통합 문서가 됩니다.

마이그레이션 참고 사항

OpenAI에서 마이그레이션

변경할 값은 기본적으로 세 가지입니다.

client = OpenAI(
    api_key="YOUR_DEEPSEEK_API_KEY",
    base_url="https://api.deepseek.com",
)

model = "deepseek-v4-pro"
Enter fullscreen mode Exit fullscreen mode

기존 메시지 구성, 도구 정의, 스트리밍 핸들러는 유지할 수 있습니다. 다만 배포 전에 다음을 확인하세요.

  1. 핵심 사양 외 파라미터가 예상대로 동작하는지 테스트합니다.
  2. reasoning_content가 추가되어도 응답 파서가 실패하지 않는지 확인합니다.
  3. 도구 호출과 스트리밍 회귀 테스트를 실행합니다.

Anthropic에서 마이그레이션

Anthropic Messages 형식을 이미 사용 중이면 요청 본문은 유지할 수 있습니다.

export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
export ANTHROPIC_AUTH_TOKEN=$DEEPSEEK_API_KEY
export ANTHROPIC_MODEL=deepseek-v4-pro
Enter fullscreen mode Exit fullscreen mode

다만 다음 Messages 규칙은 계속 지켜야 합니다.

  • max_tokens 필수
  • 시스템 프롬프트는 최상위 system
  • 응답은 콘텐츠 블록 목록
  • 스트리밍은 유형화된 이벤트

Responses API로 마이그레이션

ChatCompletions나 Messages 요청을 Responses API로 기계적으로 변환할 수는 없습니다. 요청 계층을 새로 설계해야 합니다.

따라서 단지 최신 API라는 이유로 전환하기보다, 다음 기능이 필요할 때 선택하는 편이 좋습니다.

  • previous_response_id 기반 상태 참조
  • 유형화된 출력 항목
  • 에이전트 중심 스트리밍 이벤트
  • 다단계 도구 호출 오케스트레이션

어떤 경로를 선택하든, 구성 변경 후에는 실제 회귀 테스트 컬렉션을 실행한 뒤 통합을 신뢰하세요.

자주 묻는 질문

새 프로젝트에서는 어떤 형식을 선택해야 하나요?

가장 넓은 도구 지원이 필요하면 ChatCompletions를 기본값으로 선택하세요. Claude 네이티브 스택이면 Messages가 적합합니다. 다단계 에이전트와 서버 관리 상태가 필요하면 Responses API를 선택하세요.

Claude Code를 DeepSeek V4 Pro에 연결할 수 있나요?

가능합니다. ANTHROPIC_BASE_URL을 DeepSeek의 Anthropic 호환 엔드포인트로 설정하고, DeepSeek API 키를 인증 토큰으로 사용하며, 모델을 deepseek-v4-pro로 설정하세요.

도구 호출과 구조화된 출력은 모든 형식에서 지원되나요?

모델은 둘 다 지원합니다. 다만 도구 호출 구조는 형식마다 다릅니다.

  • ChatCompletions: 중첩된 function 객체
  • Messages: input_schema 기반 도구 정의
  • Responses: function_call 및 function_call_output 항목

배포 전에는 각 인터페이스의 실제 요청과 응답을 테스트 컬렉션에서 검증하세요. 호환 구현은 보통 스키마의 엣지 케이스에서 차이가 드러납니다.

Top comments (0)