DeepSeek API 연동 튜토리얼: 키, Base URL, 첫 호출 (2026)

DeepSeek API 연동 자체는 복잡하지 않습니다. 실제로 막히기 쉬운 것은 세 가지입니다. 키가 어느 플랫폼에 속하는지, Base URL을 빠짐없이 적었는지, 모델 이름이 현재 버전인지입니다. 많은 "호출 실패"는 모델 능력 문제가 아니라 자격 증명과 주소가 맞지 않아 생깁니다.

이 글은 가입, 충전, 키 생성부터 시작해 curl과 Python 첫 호출을 순서대로 완료하고, 스트리밍 출력, thinking 모드, max_tokens, 자주 발생하는 오류를 설명합니다. 한 번 따라 하면 기본적인 연동 경로를 실행할 수 있습니다.

안내: DeepSeek는 해당 권리자의 상표이며 이 글은 DeepSeek 공식과 소속 관계가 없습니다. 모델 이름, 파라미터, 한도는 버전에 따라 조정될 수 있습니다. 이 글은 2026년 10월 공식 문서의 일반적인 형태를 예로 들며 최종적으로는 공식 문서와 사이트 내 모델 가격을 기준으로 합니다.

1. 연동 전에 구분할 네 가지

API 연동 실패는 대부분 모델 능력 문제가 아니라 아래 네 가지 대상이 정렬되지 않은 것입니다.

대상	역할	가장 틀리기 쉬운 부분
계정	잔액, 청구, 키의 귀속을 결정	A 플랫폼 키에 B 플랫폼 주소를 설정
API 키	신원 증명	복사할 때 공백, 줄바꿈, 따옴표 포함
Base URL	요청이 향할 진입점	`/v1` 누락, 또는 공식 주소와 게이트웨이 주소 혼용
모델 이름	요청의 `model` 필드	오래된 글의 만료된 이름 사용

기억법은 간단합니다. 키와 Base URL은 반드시 쌍으로 존재해야 합니다. 공식 키에는 공식 진입점만, 게이트웨이 키에는 게이트웨이 진입점만 사용하세요. 섞으면 보통 곧바로 401이 반환됩니다.

2. 가입, 충전, 키 생성

공식 오픈 플랫폼을 예로 들면 순서는 다음과 같습니다.

DeepSeek 오픈 플랫폼을 열고 가입해 로그인합니다.
페이지 안내에 따라 필요한 검증을 마치고 충전 페이지로 이동합니다.
처음에는 소액을 충전해 입금을 확인한 뒤 배치 작업을 실행합니다.
API Keys 페이지에서 새 키를 만들고 이름에 용도를 분명히 적습니다. 예: deepseek-test, deepseek-prod.
키를 복사한 즉시 비밀번호 관리자나 서버 측 환경 변수에 저장합니다. 페이지를 닫으면 보통 전체 값을 다시 보여 주지 않습니다.
테스트와 운영용 키를 따로 만들고 예산이나 사용량 알림을 설정합니다.

ZSQH AI 게이트웨이를 쓴다면 흐름은 비슷합니다. 가입 페이지에서 계정을 만들고 콘솔에서 키를 생성·충전한 뒤 이 글 뒤쪽의 OpenAI 호환 방식으로 호출합니다. 양쪽에서 같은 키를 공유하지 마세요. 문제가 생겼을 때 잔액, 속도 제한, 설정 오류 중 무엇인지 구분하기 어려워집니다.

3. Base URL과 모델 이름: 코드 작성 전에 확인

공식 문서가 현재 제시하는 OpenAI 호환 진입점은 https://api.deepseek.com이고 채팅 완성 경로는 /chat/completions입니다. 일부 오래된 튜토리얼은 https://api.deepseek.com/v1을 적는데, 사용 가능 여부는 공식 문서의 현재 설명을 기준으로 해야 합니다. 확실하지 않다면 먼저 공식 예시의 주소로 실행하세요.

항목	공식 직접 연결	ZSQH AI 게이트웨이
Base URL	`https://api.deepseek.com`	`https://ai.zhongshangqihang.com/v1`
채팅 경로	`/chat/completions`	`/v1/chat/completions`
키 출처	공식 오픈 플랫폼	게이트웨이 콘솔
모델 이름	공식 문서 기준	사이트 내 모델 가격 기준
적합한 경우	DeepSeek만 사용하고 공식 접속·결제가 원활	통합 진입점, 멀티모델, 위안화 청구 필요

2026년 10월 기준 공식 문서에 나온 모델 이름은 deepseek-flash와 deepseek-v4-pro입니다. 오래된 글의 deepseek-chat, deepseek-reasoner는 더 이상 사용할 수 없을 수 있습니다. 기억에 의존해 모델 이름을 적지 말고 호출 전에 공식 문서나 사이트 가격 페이지와 대조하세요.

4. 첫 curl: 최소 요청부터 실행

먼저 thinking을 꺼서 변수를 줄이세요. 공식 진입점 예시입니다.

export DEEPSEEK_API_KEY="sk-여기의-키"

curl "https://api.deepseek.com/chat/completions" \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-flash",
    "messages": [{"role": "user", "content": "OK라고만 답하세요"}],
    "thinking": {"type": "disabled"},
    "max_tokens": 32
  }'

200이 반환되고 choices[0].message.content에 내용이 있으면 키, Base URL, 모델 이름 세 가지가 모두 맞은 것입니다. 게이트웨이를 쓴다면 URL만 https://ai.zhongshangqihang.com/v1/chat/completions로 바꾸고 게이트웨이 키로 교체하세요.

thinking은 DeepSeek의 확장 파라미터이며 모든 OpenAI 호환 서비스가 지원하는 것은 아닙니다. 게이트웨이가 지원하지 않으면 해당 필드를 빼거나 게이트웨이 문서의 대응 파라미터를 사용하세요.

5. Python 첫 호출: OpenAI SDK 사용

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com",  # 게이트웨이는 https://ai.zhongshangqihang.com/v1
)

resp = client.chat.completions.create(
    model="deepseek-flash",
    messages=[
        {"role": "system", "content": "당신은 한국어 기술 어시스턴트이며 간결하게 답합니다."},
        {"role": "user", "content": "벡터 데이터베이스가 무엇인지 세 문장으로 설명하세요."},
    ],
    max_tokens=512,
    extra_body={"thinking": {"type": "disabled"}},
)

print(resp.choices[0].message.content)
print(resp.usage)

OpenAI SDK는 thinking 필드를 인식하지 못하므로 extra_body로 전달합니다. 실행 후에는 usage를 먼저 보세요. 입력과 출력 토큰이 각각 얼마인지, 캐시 적중이 반환되는지, 추론 내용이 별도로 집계되는지 확인합니다. 이 데이터가 "빠른 것 같다"는 느낌보다 이후 비용과 타임아웃 설정에 더 유용합니다.

6. 스트리밍 출력과 reasoning_content

thinking은 기본적으로 켜져 있고 기본 강도는 high입니다. 켜면 응답에 reasoning_content가 나타나며 최종 본문 content와 같은 계층에 있습니다. 스트리밍 응답에서는 delta.reasoning_content로 블록 단위 반환됩니다.

stream = client.chat.completions.create(
    model="deepseek-flash",
    messages=[{"role": "user", "content": "CSV를 읽는 Python 예제를 작성하세요"}],
    stream=True,
    max_tokens=4096,
    reasoning_effort="high",
    extra_body={"thinking": {"type": "enabled"}},
)

reasoning, answer = [], []
for chunk in stream:
    if not chunk.choices:
        continue
    delta = chunk.choices[0].delta
    if getattr(delta, "reasoning_content", None):
        reasoning.append(delta.reasoning_content)
    if delta.content:
        answer.append(delta.content)

print("사고 과정: ", "".join(reasoning))
print("최종 답변: ", "".join(answer))

멀티턴 대화에서 요청에 tools가 포함되면 이전 턴의 reasoning_content를 완전히 되돌려 보내야 합니다. 그렇지 않으면 400이 반환될 수 있습니다. tools가 없으면 생략해도 되고 서버가 무시합니다. 최종 사용자에게 보여 줄 때는 사고 내용을 접어 두고 기본적으로 모두 펼치지 마세요.

7. max_tokens, temperature, thinking 설정

작업	thinking	권장 시작값	설명
연결 테스트	끔	max_tokens 32~128	짧은 응답만 필요
분류, 추출	끔	256~1024	구조화 출력으로 사고 비용 절감
고객지원, 작성	켬	1024~4096	결과에 따라 effort 조정
코드, 복잡한 추론	켬	4096 이상	사고 과정에 충분한 예산 확보

공식 문서 현재 기준 컨텍스트 길이는 1M 토큰이고 max_tokens 범위는 1~384K입니다. 설정하지 않으면 비thinking은 기본 8K, thinking은 기본 64K이며 reasoning_effort가 max일 때 기본 128K입니다. 이 수치는 조정될 수 있으므로 공식 문서를 기준으로 하세요.

thinking 모드에서는 temperature, presence_penalty, frequency_penalty가 적용되지 않습니다. 조정해도 오류가 나지 않지만 결과도 바뀌지 않습니다. max_tokens도 너무 낮추면 안 됩니다. 사고 내용이 출력 예산을 차지하므로 예산이 너무 작으면 본문을 쓰기 전에 잘릴 수 있습니다.

8. 401, 402, 429, 타임아웃 문제 해결

현상	흔한 원인	처리
401	키 오류, Bearer 누락, 키와 Base URL이 다른 플랫폼 소속	키를 다시 복사하고 요청 헤더와 진입점 일치 확인
402	계정 잔액 부족	충전 후 재시도, 코드 수정 전에 잔액 확인
429	요청 과다, 동시성 또는 QPS 초과	동시성 축소, 지수 백오프, 프로젝트별 키 분리
400/422	파라미터, 모델 이름, 컨텍스트가 유효하지 않음	오류 메시지를 보고 모델 이름과 max_tokens 확인
타임아웃	네트워크, 긴 출력, thinking 소요 시간	연결·읽기 타임아웃을 따로 설정하고 출력 제한
500/503	업스트림 오류 또는 과부하	잠시 기다린 뒤 백오프 재시도

429의 동시성 상한은 계정 단위로 집계되며 키마다 균등 배분되지 않습니다. 같은 계정의 여러 키가 할당량을 공유하므로 "키를 여러 개 만들면" 동시성 제한을 우회할 수 없습니다. 공식 문서에 따르면 10분 안에 추론이 시작되지 않으면 연결이 끊기므로 클라이언트가 이런 상황을 식별하고 재시도할 수 있어야 합니다.

9. 키 보안: 출시 전 최소 다섯 가지

키는 서버 측 환경 변수나 비밀 관리 서비스에만 두고 프런트엔드, 저장소, 로그에 쓰지 않습니다.
테스트, 스테이징, 운영에 각각 다른 키를 써서 문제 발생 시 빠르게 찾고 중지합니다.
잔액 알림이나 지출 상한을 설정해 이상 호출 시 먼저 손실을 막습니다.
로그에는 키 접두사나 지문만 기록하고 전체 값은 남기지 않습니다.
인사 변동이나 유출 의심 시 즉시 교체하고 최근 사용량 기록을 확인합니다.

10. 공식에서 게이트웨이로: 두 곳만 변경

이전할 때 base_url과 api_key를 먼저 바꾸고 모델 이름은 게이트웨이 가격 페이지에서 다시 확인하며 나머지 요청 본문은 최대한 유지합니다. 같은 실제 프롬프트 세트로 출력, 소요 시간, usage를 비교하고 3~7일 관찰한 뒤 운영으로 전환하세요. 공식 직접 연결을 대체 경로로 남겨 두면 문제가 생겼을 때 빠르게 롤백할 수 있습니다.

통합 진입점이나 멀티모델 청구가 필요하다면 ZSQH AI 게이트웨이에서 테스트 키를 만들 수 있고, 가격과 사용 가능 모델은 모델 가격에서 확인하세요.

Base URL에 /v1을 붙여야 하나요?

공식 문서의 현재 예시를 기준으로 하세요. 공식 OpenAI 호환 진입점은 https://api.deepseek.com으로 적혀 있고 채팅 경로는 /chat/completions입니다. 게이트웨이는 보통 /v1 접두사를 씁니다. 오래된 튜토리얼로 추측하지 말고 curl로 전체 주소를 한 번 호출해 보세요.

401은 키 오류인가요, 잔액 부족인가요?

401은 인증 실패이므로 키가 맞는지, Bearer가 붙었는지, 키와 Base URL이 같은 플랫폼 소속인지 먼저 확인합니다. 잔액 부족은 보통 402를 반환하므로 둘을 혼동하지 마세요.

첫 호출에서 thinking을 켜야 하나요?

먼저 끄고 가장 짧은 요청으로 경로를 확인하세요. 키, 주소, 모델 이름에 문제가 없다고 확인된 뒤 작업에 따라 켜고 낮은 reasoning_effort부터 테스트하세요.

max_tokens는 얼마로 설정하는 것이 좋나요?

먼저 작업에 충분한 값을 주고 실행된 뒤 조여 가세요. 분류와 추출은 수백에서 시작하고 긴 글과 코드는 수천을 남겨 두세요. thinking 모드에서는 사고 내용에 예산을 배정해야 하므로 너무 작으면 본문이 잘립니다.

공식 키를 게이트웨이 주소에 바로 쓸 수 있나요?

안 됩니다. 공식 키는 공식 진입점에만, 게이트웨이 키는 게이트웨이 진입점에만 대응합니다. 섞으면 보통 401이 반환됩니다. 진입점을 바꿀 때는 키와 Base URL을 쌍으로 교체하세요.

DeepSeek API 연동 튜토리얼: 키, Base URL, 첫 호출 (2026)

1. 연동 전에 구분할 네 가지

2. 가입, 충전, 키 생성

3. Base URL과 모델 이름: 코드 작성 전에 확인

4. 첫 curl: 최소 요청부터 실행

5. Python 첫 호출: OpenAI SDK 사용

6. 스트리밍 출력과 reasoning_content

7. max_tokens, temperature, thinking 설정

8. 401, 402, 429, 타임아웃 문제 해결

9. 키 보안: 출시 전 최소 다섯 가지

10. 공식에서 게이트웨이로: 두 곳만 변경

자주 묻는 질문

Base URL에 /v1을 붙여야 하나요?

401은 키 오류인가요, 잔액 부족인가요?

첫 호출에서 thinking을 켜야 하나요?

max_tokens는 얼마로 설정하는 것이 좋나요?

공식 키를 게이트웨이 주소에 바로 쓸 수 있나요?

One API for leading models

1. 연동 전에 구분할 네 가지

2. 가입, 충전, 키 생성

3. Base URL과 모델 이름: 코드 작성 전에 확인

4. 첫 curl: 최소 요청부터 실행

5. Python 첫 호출: OpenAI SDK 사용

6. 스트리밍 출력과 reasoning_content

7. max_tokens, temperature, thinking 설정

8. 401, 402, 429, 타임아웃 문제 해결

9. 키 보안: 출시 전 최소 다섯 가지

10. 공식에서 게이트웨이로: 두 곳만 변경

자주 묻는 질문

Base URL에 /v1을 붙여야 하나요?

401은 키 오류인가요, 잔액 부족인가요?

첫 호출에서 thinking을 켜야 하나요?

max_tokens는 얼마로 설정하는 것이 좋나요?

공식 키를 게이트웨이 주소에 바로 쓸 수 있나요?

One API for leading models

Read next