DeepSeek API 사용법: OpenAI SDK로 현행 Pro·Flash 호출하기

DeepSeek API는 OpenAI SDK의 Chat Completions 형식으로 호출할 수 있다. base_url, API 키, 모델명을 DeepSeek에 맞추고 추가 옵션은 지원 여부를 확인한다. 현재 모델 ID는 deepseek-v4-pro와 deepseek-flash다. 예전 deepseek-v4-flash는 퇴역해 요청하면 V4.1-Flash로 연결되고 Flash 단가로 청구되니, 새 코드에는 deepseek-flash를 쓴다. (모델·가격)

Pro와 Flash 중 무엇을 쓸까

새 프로젝트와 짧은 요약·분류는 단가가 낮은 deepseek-flash부터 시험합니다. 이미 Pro로 검증한 작업은 결과 품질·응답 시간·토큰 사용량·재시도 횟수를 비교한 뒤 전환합니다. 모델별 차이와 가격 구조는 DeepSeek V4 정리에 있다.

첫 호출

1. DeepSeek API 플랫폼에서 키를 만들고 잔액을 충전한다. API 호출은 이 잔액에서 빠진다.
2. PowerShell에서 키를 환경 변수에 넣는다. 창을 닫으면 사라지니 새 창에서는 다시 넣는다.

$env:DEEPSEEK_API_KEY="YOUR_API_KEY"

3. Python 설치를 확인하고 SDK를 설치한다.

python --version
python -m pip install -U openai

4. 아래 코드를 메모장에 붙여 first_deepseek.py로 저장한다. 파일 형식을 ’모든 파일’로 골라 .txt가 붙지 않게 한다. 그리고 python first_deepseek.py로 실행한다.

import os
from openai import OpenAI

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

response = client.chat.completions.create(
    model="deepseek-flash",
    messages=[{"role": "user", "content": "다음 문장을 한 줄로 요약해줘: 회의는 금요일 오전 10시이며 준비물은 지난달 판매 보고서다."}],
    extra_body={"thinking": {"type": "disabled"}},
)
print(response.choices[0].message.content)
print(response.choices[0].finish_reason, response.usage)

답에 “금요일 오전 10시”와 “지난달 판매 보고서”가 모두 있으면 성공이다. 문구는 매번 조금 다를 수 있다. 종료 사유(finish_reason)가 length면 출력 한도에 걸려 잘린 답이니 다음 단계에 쓰지 않는다.

• KeyError: DEEPSEEK_API_KEY → 실행 중인 Python에 해당 환경 변수가 없다. 실행하는 창에서 설정했는지 확인한다.
• No module named openai → 실행 중인 Python에서 패키지를 찾지 못했다. 설치 여부와 Python 환경을 확인하고 python -m pip로 설치한다.

이 예제는 짧은 요약이므로 Flash의 추론을 끕니다. 복잡한 요청은 thinking을 enabled로 바꾸고 reasoning_effort="high"를 지정해 결과와 사용량을 비교합니다. 추론을 켠다고 모든 작업의 품질이 좋아지는 것은 아닙니다. 설정 방법과 도구 호출 때의 규칙은 DeepSeek Thinking Mode 사용법에 있다.

오류가 날 때

코드	원인	조치
401	API 키가 틀림	키를 다시 복사한다. 앞뒤 공백을 확인한다
402	잔액 부족	플랫폼에서 충전한다
422	파라미터 오류	추가한 옵션을 빼고 기본 예제로 다시 보낸다
429	요청 한도 초과	잠시 기다렸다가 간격을 두고 보낸다

(오류 코드) 401이면 요청에 전달한 API 키를 확인하고, 422이면 응답 메시지가 지적한 파라미터를 고친다.

인증이나 파라미터 오류는 같은 요청을 반복해도 풀리지 않는다. 원인을 고친 뒤 보낸다. 재시도에는 횟수와 대기 시간 상한을 둔다.

deepseek-chat과 deepseek-reasoner는 7월 24일 완전히 퇴역했다. 예전 코드에서 모델 오류가 나면 모델 ID부터 바꾼다. (V4 출시 안내)

입력비 줄이기: Context Caching

Context Caching은 따로 켤 필요 없이 기본으로 동작한다. 이미 저장된 캐시 접두 단위 전체와 일치하는 앞부분을 재사용하면 캐시 적중 요율이 적용된다. 일부 문장이 같다는 것만으로 적중이 보장되지는 않는다. (Context Caching)

100만 토큰당(오프피크)	캐시 미적중	캐시 적중
deepseek-flash	$0.15	$0.003
deepseek-v4-pro	$0.66	$0.022

9월 29일 가격표 기준이다. 한국 시간 평일 1013시, 1519시(피크, 중국 공휴일 제외)에는 두 배다.

1. 매번 같은 내용을 앞에 둔다. 시스템 규칙과 긴 문서를 먼저, 바뀌는 질문·날짜·사용자 ID는 뒤에 둔다. 바뀌는 값이 맨 앞에 있으면 뒤의 공통 문서까지 캐시가 빗나간다.
2. 두 번째 요청이 빗나가도 정상이다. 공통 부분이 캐시로 저장된 뒤 세 번째 요청부터 적중하기도 한다.
3. 적중 여부는 응답의 usage로 본다.

print(response.usage.prompt_cache_hit_tokens, response.usage.prompt_cache_miss_tokens)

적중이 계속 0이면 공통 부분의 파일 순서·날짜·도구 정의가 요청마다 바뀌지 않았는지 본다. 캐시는 몇 초 뒤 만들어지고, 안 쓰면 몇 시간~며칠 사이에 지워진다. 캐시에 적중해도 질문과 출력 비용은 그대로 든다.

답을 JSON으로 받으려면

요청에 response_format={"type": "json_object"}를 넣고, 프롬프트에 “json”이라는 단어와 원하는 JSON 예시를 함께 적는다. 출력이 길면 중간에 잘려 JSON이 깨질 수 있으니 max_tokens를 넉넉히 준다. 받은 뒤에는 코드로 파싱해 필수 항목이 있는지 확인한다. (JSON Output)

답을 조금씩 받으려면(스트리밍)

긴 답을 기다리지 않고 화면에 바로 보여 주려면 요청에 stream=True를 넣고, 받은 조각마다 choices[0].delta.content를 이어 붙인다. 추론을 켠 요청은 reasoning_content 조각이 먼저 오니 둘을 나눠 처리한다. 화면에 답을 그대로 보여 줄 때는 추론 조각을 따로 두거나 숨긴다.

다른 도구에 연결하기

Claude Code처럼 Anthropic 형식을 쓰는 도구는 https://api.deepseek.com/anthropic으로 연결한다. thinking과 기본 도구 호출은 되지만 document·search_result 블록 같은 일부 필드는 지원하지 않으니 Anthropic 호환표에서 확인한다. 키는 서버 환경 변수에 두고 웹 페이지 코드에 넣지 않는다. 저장소에 커밋한 키는 파일을 지워도 기록에 남으니 폐기하고 새로 만든다.