딥시크 웹챗은 써봤는데, 딥시크 API로 직접 뭘 해보려니 어디서부터 시작해야 할지 막막한 분이 많습니다. API 키는 어떻게 만들고, 모델은 뭘 골라야 하고, 비용은 얼마나 나오는지. 2026년 9월 기준 DeepSeek V4 API의 발급부터 실제 호출, 에이전트 연결까지 한 번에 정리합니다.
웹챗이랑 뭐가 다른가요
DeepSeek 웹사이트에서 대화하는 것과 API를 쓰는 것은 완전히 다릅니다.
- 웹챗: 브라우저에서 바로 질문하고 답을 받습니다. 무료이고 간편하지만, 자동화가 안 됩니다.
- API: 내 코드나 도구에서 DeepSeek 모델을 직접 호출합니다. 반복 작업을 자동화하거나, Codex 같은 에이전트에 연결할 수 있습니다. 사용한 토큰만큼 비용이 발생합니다.
정리하면, 한두 번 질문할 거면 웹챗으로 충분합니다. 반복 작업을 맡기거나 다른 도구에 연결하려면 API가 필요합니다.
딥시크 API 키 발급
DeepSeek Platform(platform.deepseek.com)에 가입한 뒤, API keys 페이지에서 키를 만듭니다.
- 오른쪽 상단 Create new API key 클릭
- 이름을 입력하고 Create API key 클릭
- 생성된 키(
sk-로 시작)를 바로 복사해서 안전한 곳에 저장
키는 생성 직후 한 번만 보입니다. 놓치면 새로 만들어야 합니다. 계정당 최대 100개까지 보유할 수 있고, 외부에 노출된 키는 DeepSeek가 자동으로 비활성화합니다.
사용할 수 있는 딥시크 V4 API 모델
2026년 9월 기준 DeepSeek V4 API에서 쓸 수 있는 모델은 세 가지입니다.
| 모델 ID | 특징 |
|---|---|
deepseek-v4-flash | 빠르고 저렴한 기본 모델 |
deepseek-v4-pro | 더 정교한 추론이 필요할 때 |
deepseek-v4-flash-vision-exp | 이미지 입력이 가능한 실험 모델 |
세 모델 모두 OpenAI 호환 API(https://api.deepseek.com)와 Anthropic 호환 API(https://api.deepseek.com/anthropic) 두 가지 방식으로 호출할 수 있습니다.
Pro와 Flash, 어떤 걸 써야 하나
단순하게 나누면 이렇습니다.
- Flash: 대부분의 일상적인 작업에 충분합니다. 속도가 빠르고 가격이 Pro의 1/3 수준입니다.
- Pro: 복잡한 코드 생성, 긴 문서 분석, 까다로운 추론이 필요할 때 씁니다. 동시 처리 한도(500)가 Flash(2,500)보다 낮습니다.
- Vision(실험): 이미지를 함께 보내야 할 때만 씁니다. 가격은 Flash와 같지만 실험 단계라 안정성은 확인이 필요합니다.
처음이라면 Flash로 시작하고, 결과가 부족할 때만 Pro로 바꿔보는 게 낫습니다.
딥시크 API 가격: 현재 토큰 단가
아래는 공식 가격 페이지 기준 100만 토큰당 달러 단가입니다. 피크/오프피크 시간대에 따라 가격이 달라집니다.
| 항목 | Flash (오프피크 / 피크) | Pro (오프피크 / 피크) |
|---|---|---|
| 입력: 캐시 히트 | $0.007 / $0.014 | $0.022 / $0.044 |
| 입력: 캐시 미스 | $0.22 / $0.44 | $0.66 / $1.32 |
| 출력 | $0.66 / $1.32 | $1.98 / $3.96 |
| 동시 처리 한도 | 2,500 | 500 |
Vision 실험 모델의 가격은 Flash와 동일합니다.
캐시 히트란? 같은 시스템 프롬프트나 앞부분 대화를 반복 호출하면 DeepSeek가 자동으로 캐시를 적용해 입력 비용을 크게 낮춰줍니다. 자동화 작업에서 같은 지시를 반복 보내는 경우 실제 비용은 표의 캐시 미스 단가보다 훨씬 낮아집니다.
간단한 첫 호출
API 키가 있으면 터미널에서 바로 테스트할 수 있습니다. DeepSeek API는 OpenAI 호환 형식이라 구조가 거의 같습니다.
bash curl https://api.deepseek.com/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \ -d '{ "model": "deepseek-v4-pro", "messages": [ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Hello!"} ], "thinking": {"type": "enabled"}, "reasoning_effort": "high", "stream": false }'
model 값만 deepseek-v4-flash로 바꾸면 Flash 모델로 전환됩니다. thinking을 disabled로 바꾸면 추론 과정 없이 바로 답변만 받습니다.
OpenAI·Anthropic SDK로 연결하는 방법
DeepSeek는 별도 SDK가 없어도 됩니다. 이미 쓰고 있는 OpenAI나 Anthropic SDK에서 base URL만 바꾸면 그대로 작동합니다.
OpenAI Python SDK 예시:
“`python from openai import OpenAI
client = OpenAI( api_key=”sk-…”, base_url=”https://api.deepseek.com” )
response = client.chat.completions.create( model=”deepseek-v4-flash”, messages=[{“role”: “user”, “content”: “안녕하세요”}] ) “`
Anthropic 호환 방식:
Anthropic SDK를 쓴다면 base URL을 https://api.deepseek.com/anthropic으로 지정합니다. OpenAI 어댑터가 reasoning 상태를 제대로 넘기지 못하는 도구에서는 오히려 Anthropic 방식이 더 안정적일 수 있습니다.
Thinking, Vision, 도구 호출
Thinking(추론 과정)
V4의 세 모델 모두 Thinking을 지원하며, 기본값은 켜져 있습니다. 응답에서 reasoning_content에 추론 과정이, content에 최종 답변이 담겨 옵니다.
reasoning_effort는 low, high, max 세 단계입니다. medium이나 xhigh를 보내도 오류는 나지 않지만 실제로는 high로 처리됩니다.
주의할 점이 있습니다. Thinking을 켜면 temperature, top_p 같은 샘플링 파라미터는 효과가 없습니다. 보내도 무시됩니다.
Vision(이미지 입력)
이미지를 보내려면 반드시 deepseek-v4-flash-vision-exp 모델을 써야 합니다. 일반 Flash나 Pro에 이미지를 넣으면 작동하지 않습니다. 2026년 8월 21일 공개된 실험 모델이라 안정성은 지켜봐야 합니다.
도구 호출(Function Calling)
세 모델 모두 Function Calling을 지원합니다. V4에서는 Thinking 상태에서도 도구를 호출할 수 있어서, 추론 중에 외부 함수를 부르고 결과를 받아 다시 추론을 이어가는 다단계 루프가 가능합니다.
실제 비용은 얼마나 나올까
Flash 모델 기준으로 간단히 계산해보겠습니다.
하루에 시스템 프롬프트 500토큰 + 사용자 메시지 500토큰을 보내고, 답변 1,000토큰을 받는 호출을 100번 한다고 가정합니다.
- 입력: 100,000토큰 × $0.22/1M = $0.022
- 출력: 100,000토큰 × $0.66/1M = $0.066
- 하루 합계: 약 $0.088 (약 120원)
같은 시스템 프롬프트를 반복 사용하면 캐시 히트가 적용돼 입력 비용이 1/30 수준으로 떨어집니다. 개인 자동화 수준이라면 월 비용이 커피 한 잔 값을 넘기기 어렵습니다.
Pro 모델은 같은 사용량 기준 약 3배입니다. 필요한 호출만 Pro로 보내고 나머지는 Flash로 처리하는 것이 비용을 아끼는 방법입니다.
Codex 등 에이전트에 연결하기
OpenAI Codex CLI: 공식 지원
DeepSeek는 Codex용 공식 설정 스크립트를 제공합니다. 터미널에서 한 줄이면 됩니다.
bash bash <(curl -fsSL https://cdn.deepseek.com/api-docs/codex-deepseek-setup-en.sh)
스크립트를 실행하면 Flash, Pro, Vision 중 모델을 고르고, Codex 설정 파일이 자동으로 만들어집니다. 핵심 설정은 세 가지입니다.
toml model = "deepseek-v4-flash" base_url = "https://api.deepseek.com/" wire_api = "responses"
Codex에서는 Chat Completions가 아니라 Responses API를 쓰는 것이 현재 정석입니다. 최소 Codex 버전은 0.144.0입니다.
보안상 API 키는 설정 파일에 직접 쓰기보다 환경 변수로 관리하는 편이 낫습니다.
bash export DEEPSEEK_API_KEY="sk-..."
Cursor, Continue 등 다른 에이전트
OpenAI 호환 API를 지원하는 도구라면 대부분 연결 자체는 가능합니다. base_url을 https://api.deepseek.com으로, 모델명을 deepseek-v4-flash 등으로 지정하면 됩니다.
다만 “연결된다”와 “모든 기능이 완벽히 작동한다”는 다른 이야기입니다. 특히 Thinking과 Tool Calling을 함께 쓰는 agent loop에서 reasoning_content 처리 방식 차이로 400 오류가 발생하는 사례가 보고되고 있습니다.
| 도구 | 연결 상태 | 주의점 |
|---|---|---|
| Codex CLI | 공식 지원 | MCP·멀티에이전트 일부 버그 보고 |
| Cursor | 비공식 BYOK | Agent/tool loop에서 reasoning_content 문제 |
| Continue | 가능 | Agent loop 400 오류 보고 |
| 기타 OpenAI 호환 | 대체로 가능 | thinking 상태 보존 필요 |
자주 걸리는 오류와 주의점
API 키가 작동하지 않을 때: 키를 만든 직후 복사하지 않았거나, 외부에 노출돼 자동 비활성화됐을 수 있습니다. API keys 페이지에서 상태를 확인하고, 문제가 있으면 새로 발급하세요.
Thinking 모드에서 temperature 설정이 무시될 때: 정상입니다. Thinking이 켜져 있으면 temperature, top_p 등 샘플링 파라미터가 효과 없이 무시됩니다. 창의적인 출력이 필요하면 Thinking을 끄세요.
이미지를 보냈는데 오류가 날 때: 일반 Flash나 Pro 모델에 이미지를 넣으면 안 됩니다. 반드시 deepseek-v4-flash-vision-exp를 지정해야 합니다.
피크 시간대 비용 2배: DeepSeek는 피크/오프피크 시간대에 따라 가격이 달라집니다. 자동화 작업이라면 오프피크 시간에 실행되도록 스케줄을 잡는 것만으로 비용을 절반으로 줄일 수 있습니다.
Codex에서 고급 기능이 작동하지 않을 때: DeepSeek V4와 Codex의 연결 자체는 공식 지원이지만, MCP callable tools 노출 문제나 멀티에이전트 위임 버그가 일부 버전에서 보고되고 있습니다. Codex 버전을 최신으로 유지하고, 문제가 생기면 GitHub Issues를 확인하세요.
