DeepSeek V4.1 Flash · API

빠른 시작

두 단계면 됩니다: 요청 보내기 → 스트리밍으로 답변 받기. YOUR_API_KEY를 내 키로 바꾸면 아래 명령을 그대로 실행할 수 있습니다. 엔드포인트가 OpenAI Chat Completions와 같으므로 기존 OpenAI 코드는 base_url과 model만 바꾸면 됩니다.

1단계 · 요청 보내기

curl https://kovapi.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek-v4.1-flash", "messages": [{"role": "user", "content": "광합성을 한 문장으로 설명해 줘"}]}'

응답(HTTP 200)

{
  "id": "chatcmpl-7f3c9a1e2b4d6f8a",
  "object": "chat.completion",
  "created": 1791281400,
  "model": "deepseek-v4.1-flash",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "광합성은 식물이 햇빛을 이용해 이산화탄소와 물을 당으로 바꾸고 산소를 내보내는 과정입니다.",
        "reasoning_content": "..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 186,
    "total_tokens": 204,
    "prompt_tokens_details": {"cached_tokens": 0},
    "completion_tokens_details": {"reasoning_tokens": 144}
  }
}

message.content는 답변이고 message.reasoning_content는 사고 과정입니다. usage는 이 요청에 과금되는 토큰 수이며, 사고 토큰은 completion_tokens에 포함되어 출력 요금으로 과금됩니다.

2단계 · 스트리밍으로 받기(권장)

curl -N https://kovapi.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek-v4.1-flash", "stream": true, "messages": [{"role": "user", "content": "광합성을 한 문장으로 설명해 줘"}]}'

스트림은 표준 SSE입니다. 각 청크의 본문은 choices[0].delta.content에 담기고, 마지막 청크에는 usage가 담기며, 스트림은 data: [DONE]으로 끝납니다. 답변이 길거나 모델이 먼저 생각해야 할 때는 스트리밍을 쓰세요. 비스트리밍 요청은 약 10분이 지나면 연결이 끊깁니다.

Python(OpenAI SDK)

from openai import OpenAI

client = OpenAI(base_url="https://kovapi.com/v1", api_key="YOUR_API_KEY")

# 1. 질문 하나에 답변 하나
resp = client.chat.completions.create(
    model="deepseek-v4.1-flash",
    messages=[{"role": "user", "content": "광합성을 한 문장으로 설명해 줘"}],
)
print(resp.choices[0].message.content)

# 2. 스트리밍
stream = client.chat.completions.create(
    model="deepseek-v4.1-flash",
    messages=[{"role": "user", "content": "광합성을 한 문장으로 설명해 줘"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

인증

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

콘솔에서 API 키를 만들면 시작할 수 있습니다.

사양 한눈에 보기

요청 파라미터

POST /v1/chat/completions의 요청 본문(JSON)이며, OpenAI Chat Completions와 같습니다. 자주 쓰는 파라미터와 이 모델에서의 실제 동작은 다음과 같습니다:

그 밖의 OpenAI 파라미터(stop, seed, user 등)는 보낸 그대로 모델에 전달되며, 적용 여부는 모델에 따라 다릅니다.

가격

토큰 단위로 과금하며, 아래 요금(100만 토큰당)은 실시간으로 반영됩니다. 성공한 요청의 실제 사용량만 과금하고, 실패, 시간 초과, 거부된 요청은 과금하지 않습니다. 1크레딧 = $0.005.

예를 들어 입력 2,000 토큰, 출력 1,000 토큰(사고 포함)인 요청 한 건은 약 $0.0004입니다.

사고(Thinking)

기본적으로 먼저 생각한 뒤 답하며, 사고 과정은 message.reasoning_content로 반환됩니다(스트리밍에서는 delta.reasoning_content).

"thinking": {"type": "disabled"}를 보내면 사고를 끄고 바로 답합니다. 더 빠르고 출력 토큰도 적습니다.

사고 토큰은 usage.completion_tokens에 포함되어 출력 요금으로 과금됩니다(일부 모델은 completion_tokens_details.reasoning_tokens에 따로 표시합니다).

프롬프트 캐싱

별도의 파라미터는 필요 없습니다. 반복되는 긴 접두어(같은 시스템 프롬프트, 대화의 앞부분)는 모델 제공사가 자동으로 캐시할 수 있으며, 캐시에 적중한 부분은 더 낮은 캐시 요금으로 과금됩니다. 캐시 여부와 적중량은 모델 제공사가 정합니다. 바뀌지 않는 내용을 메시지 맨 앞에 두면 적중률을 높일 수 있습니다.

캐시에 적중한 토큰 수는 usage.prompt_tokens_details.cached_tokens로 반환되며, 이 부분은 캐시 적중 요금으로, 나머지 입력은 입력 요금으로 과금됩니다.

도구 호출(Function Calling)

tools에 JSON Schema로 함수를 정의하세요. 모델이 함수를 호출하기로 하면 finish_reason: "tool_calls"를 돌려주며, message.tool_calls에 함수 이름과 인자(JSON 문자열)가 담깁니다.

curl https://kovapi.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek-v4.1-flash", "messages": [{"role": "user", "content": "지금 상하이 날씨를 알려 줘"}], "tools": [{"type": "function", "function": {"name": "get_weather", "description": "Current weather of a city", "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]}}}]}'

함수를 실행한 뒤 그 결과를 role: "tool" 메시지로(해당 tool_call_id와 함께) 대화에 덧붙여 다시 요청하면, 모델이 이를 바탕으로 최종 답변을 줍니다. tool_choice에는 auto, none, required 또는 특정 함수를 지정할 수 있습니다.

웹 검색

요청에 "web_search": true를 넣으세요(또는 tools에 {"type": "web_search"} 항목을 넣어도 됩니다). 게이트웨이가 먼저 대화 내용을 바탕으로 실시간 웹 검색을 하고 최대 5개의 결과를 링크와 함께 참고 자료로 모델에 넘기면, 모델이 이를 바탕으로 답하면서 출처를 표시합니다. 검색 자체는 무료이며, 참고 자료는 입력 토큰으로 과금됩니다.

curl https://kovapi.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek-v4.1-flash", "web_search": true, "messages": [{"role": "user", "content": "오늘 주요 기술 뉴스를 알려 줘"}]}'

안정성과 자동 재시도

• 요청에서 오류나 시간 초과가 나거나 용량이 가득 차면, 게이트웨이는 응답을 돌려주기 시작하기 전에 자동으로 재시도합니다. 따로 재시도할 필요가 없고, 두 번 과금되지도 않습니다.
• 스트리밍은 출력을 시작한 뒤에는 자동으로 재시도하지 않습니다. 중간에 끊기면 끊기기 전까지 생성된 사용량만큼 과금됩니다(과금과 환불 참고).
• 모델이 가득 차면 게이트웨이가 Retry-After와 함께 429를 돌려줍니다. 그 초만큼 기다린 뒤 다시 시도하세요. 실패한 요청은 과금되지 않습니다. 모델별 상태는 서비스 상태에서 볼 수 있습니다.

오류와 환불

오류는 error 객체(message, type, code, param)로 돌아옵니다. HTTP 상태 코드와 code로 판단하고, message 문구로는 판단하지 마세요. 실패한 요청은 과금되지 않으며, 전체 목록은 오류 코드에 있습니다.

스트리밍이 출력을 시작한 뒤 실패하면 상태 코드는 바뀌지 않습니다. 오류는 error가 담긴 데이터 줄로 오거나, 스트림이 그냥 끝납니다(data: [DONE] 없이). 이런 경우 중단된 것으로 처리하세요.