채팅 완성 API (Chat Completions)

DeepSeek 모델에 대화를 보내고 응답을 받는 핵심 API예요. 대화 전체를 messages 배열로 넘기면 모델이 그 대화에 이어질 답을 생성해 줘요. 방식은 OpenAI의 Chat Completions와 호환되기 때문에, 기존에 OpenAI SDK를 쓰던 코드에서 base_url만 바꾸면 그대로 쓸 수 있어요.

출처: https://api-docs.deepseek.com/api/create-chat-completion

엔드포인트는 POST https://api.deepseek.com/chat/completions예요. 요청 본문(body)에 필요한 것부터 살펴볼게요.

요청 파라미터

model (string, 필수) — 사용할 모델 ID예요. 가능한 값은 deepseek-v4-flash, deepseek-v4-pro예요.
messages (array, 필수, 최소 1개) — 지금까지의 대화 목록이에요. 항목마다 role과 content를 담아요. 역할은 system, user, assistant, tool 네 가지가 있어요. system 메시지는 내용을 담는 content가 필수고, 참가자 구분이 필요하면 이름을 적는 name을 붙일 수 있어요.
thinking (object, 선택) — 생각(thinking) 모드와 일반 모드를 전환해요. type은 enabled 또는 disabled를 받고 기본값은 enabled예요. enabled로 두면 thinking 모드로 동작해요.
reasoning_effort (string, 선택) — 추론 강도를 정해요. low, high, max를 받고 기본값은 high예요. 호환성을 위해 medium과 xhigh는 high로 매핑돼요.
max_tokens (integer, 선택) — 생성할 최대 토큰 수예요. 입력 토큰과 생성 토큰의 합은 모델 컨텍스트 길이로 제한돼요.
response_format (object, 선택) — 모델이 출력할 형식을 지정해요. {"type": "json_object"}로 설정하면 JSON 출력이 켜져서 모델이 생성하는 메시지가 유효한 JSON임을 보장해요.
stop (object, 선택) — 생성을 멈출 시퀀스로 최대 16개까지 지정할 수 있어요.
stream (boolean, 선택) — true로 주면 응답을 스트리밍으로 받아요.
tools (array, 선택) — 모델이 호출할 수 있는 도구 목록이에요. 현재는 함수(function)만 지원되고 최대 128개까지 넣을 수 있어요. 각 함수는 type(현재 function만), 이름을 담은 function.name, 기능을 설명하는 function.description, 함수가 받는 파라미터를 JSON Schema로 기술한 function.parameters로 구성돼요. parameters를 생략하면 빈 파라미터 목록을 가진 함수가 돼요. function.strict를 true로 주면 도구 호출이 항상 정의한 JSON Schema를 따르도록 강제하는 strict 모드(Beta)로 동작해요.
tool_choice (object, 선택) — 모델이 어떤 도구를 호출할지 제어해요.

유의할 점이 하나 있어요. response_format으로 JSON 출력을 쓸 때는 시스템 또는 사용자 메시지에서 모델에게 JSON으로 만들라고 직접 지시해야 해요. 그 지시가 없으면 모델이 토큰 한도까지 공백만 생성하다가 멈춘 것처럼 오래 걸리는 요청이 될 수 있어요. 그리고 finish_reason="length"면 생성이 max_tokens를 넘었거나 컨텍스트 한도를 넘어 메시지가 중간에 잘렸다는 뜻이에요.

응답

성공하면 200으로 chat completion object를 돌려줘요. 주요 필드는 이래요.

id — 이 채팅 완성의 고유 식별자.
choices — 생성된 선택지 목록. 각 선택지는 finish_reason, index, 그리고 생성된 메시지 message를 담아요.
message.content — 모델이 생성한 답변 내용(없을 수 있음).
message.reasoning_content — thinking 모드에서만 나타나요. 최종 답변 전에 모델이 진행한 추론 내용이에요.
message.tool_calls — 모델이 생성한 도구 호출 목록.
created — 생성된 Unix 타임스탬프(초).
model — 사용된 모델.
usage.total_tokens — 요청에서 사용된 전체 토큰 수(프롬프트 + 완성). completion_tokens_details.reasoning_tokens에는 추론에 쓰인 토큰 수가 들어가요.

더 알아보기

첫 API 호출부터 차근히 보려면 «DeepSeek API 첫 호출» 문서를 봐요.
Thinking 모드와 추론 강도 조절은 «Thinking 모드» 문서에서 다뤄요.
함수를 호출하는 방법은 «도구 호출 (Tool Calls)» 문서를 봐요.
JSON을 깔끔하게 받는 법은 «JSON 출력» 문서를 봐요.