KovAPIKovAPI
POST https://kovapi.com/v1/chat/completions

Gemini 4 Neon Beta는 텍스트 대화, 스트리밍, Low / Medium / High 세 단계 사고(기본값은 Google과 같은 High, xhigh는 아직 사용 불가)와 함께 이미지 입력, 함수 호출, JSON 구조화 출력을 지원합니다. OpenAI SDK로 사용하며 사고 토큰은 출력으로 과금합니다.

📥 컨텍스트 창 (최대 입력):공식 창은 입력·출력이 공유하는 1,048,576 토큰이며 한 번의 응답은 기본 최대 65,536 토큰입니다. Beta 기간에는 아주 긴 작업을 나누세요.

플레이그라운드에서 사용해 보기 →

빠른 시작

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

1단계 · 요청 보내기

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

응답(HTTP 200)

JSON
{
  "id": "chatcmpl-7f3c9a1e2b4d6f8a",
  "object": "chat.completion",
  "created": 1791281400,
  "model": "gemini-4-neon",
  "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
curl -N https://kovapi.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemini-4-neon", "stream": true, "messages": [{"role": "user", "content": "광합성을 한 문장으로 설명해 줘"}]}'

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

Python(OpenAI SDK)

Python
from openai import OpenAI

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

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

# 2. 스트리밍
stream = client.chat.completions.create(
    model="gemini-4-neon",
    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)

인증

Header
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

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

사양 한눈에 보기

컨텍스트 창~1,000,000 토큰
요청당 최대 출력65,536 토큰
입력텍스트, 이미지
사고low / medium / high를 선택하며 기본값은 high입니다. 모든 단계의 토큰 단가는 같으며 xhigh는 아직 사용할 수 없습니다.
도구 호출지원(OpenAI tools 형식)
JSON 출력지원(response_format)
웹 검색지원(web_search: true, 검색 자체는 무료)
엔드포인트/v1/chat/completions
스트리밍지원(stream: true, SSE)
과금 방식토큰 단위: 입력, 출력(사고 포함), 캐시 적중에 각각 요금 적용, 실패하면 과금되지 않음

요청 파라미터

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

파라미터타입필수설명
modelstring예모델 ID: gemini-4-neon.
messagesarray예대화 메시지 배열입니다. 각 메시지에는 role(system, user, assistant, tool 중 하나)과 content가 있습니다. content는 문자열이거나 text와 image_url 파트로 이루어진 배열입니다(이미지 입력, 아래 참고). 여러 턴에 걸친 대화는 이전 메시지를 순서대로 모두 보내세요.
streamboolean아니오true면 SSE로 스트리밍하며, 마지막 청크에 usage가 담깁니다. 기본값은 false입니다.
max_tokensinteger아니오사고를 포함한 요청 출력 길이이며 한 번의 응답은 기본 최대 65,536 토큰입니다. 비용 관리를 위해 프롬프트에서도 길이를 제한하세요.
temperature / top_pnumber아니오샘플링 파라미터이며, 보낸 그대로 모델에 전달됩니다(temperature는 0~2). 먼저 생각하는 모델은 이 값을 따르지 않을 수 있습니다.
reasoning_effortstring아니오low / medium / high를 선택하며 기본값은 high입니다. 단가는 같으며 xhigh를 보내면 과금 없이 400을 반환합니다.
tools / tool_choicearray / string아니오OpenAI 표준 형식의 함수 호출입니다. 모델이 함수를 호출할 때는 finish_reason: "tool_calls"와 함께 tool_calls를 돌려줍니다. 자세한 내용은 아래를 보세요.
response_formatobject아니오{"type": "json_object"}를 보내면 모델이 올바른 JSON만 출력합니다. 프롬프트에도 JSON으로 답하라는 것과 필요한 필드를 적어 주세요.
web_searchboolean아니오true면 먼저 웹 검색을 하고 그 결과를 참고 자료로 모델에 넘깁니다. 자세한 내용은 아래를 보세요.

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

가격

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

종류100만 토큰당 가격(USD)100만 토큰당 크레딧
입력$0.90180
출력(사고 포함)$4.50900
캐시 적중$0.0459

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

사고(Thinking)

reasoning_effort를 low, medium 또는 high로 설정합니다. 생략하면 high입니다.

usage.completion_tokens는 사고와 답변을 포함하므로 사고 토큰을 다시 더하지 마세요.

세 단계의 단가는 같습니다. 사고 강도가 높으면 출력 토큰을 더 소비합니다.

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

JSON · reasoning_effort
{
  "model": "gemini-4-neon",
  "messages": [{"role": "user", "content": "광합성을 한 문장으로 설명해 줘"}],
  "reasoning_effort": "medium"
}

프롬프트 캐싱

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

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

이미지 입력

content 배열에 image_url 파트를 넣으세요. base64 data URI(data:image/png;base64,...)를 권장하며, 이 방식은 항상 읽을 수 있습니다. 공개 이미지 링크는 먼저 내려받아야 해서 가끔 가져오지 못하거나 시간이 초과될 수 있습니다. 이미지는 모델 제공사의 규칙에 따라 입력 토큰으로 환산됩니다.

curl
curl https://kovapi.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemini-4-neon", "messages": [{"role": "user", "content": [{"type": "text", "text": "이 이미지에 무엇이 있는지 알려 줘"}, {"type": "image_url", "image_url": {"url": "data:image/png;base64,iVBORw0KGgo..."}}]}]}'

도구 호출(Function Calling)

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

curl
curl https://kovapi.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemini-4-neon", "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 또는 특정 함수를 지정할 수 있습니다.

Beta 제공 범위

  • 텍스트 대화, 스트리밍, 세 단계 사고, 이미지 입력, 함수 호출, JSON 구조화 출력을 검증했습니다.
  • 공식 컨텍스트는 약 100만 토큰이며 입력과 출력이 공유합니다. 아주 긴 작업은 나누어 실행하세요.
  • 실패 요청은 과금하지 않으며 출력 후 중단은 실제 사용량으로 정산합니다.

오류와 환불

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

HTTPcode원인조치
400invalid_messages / invalid_role / invalid_max_tokens채팅 요청의 messages가 없거나 비어 있거나 형식이 잘못되었거나, role이 허용된 값이 아니거나, max_tokens가 양의 정수가 아닙니다. 문제가 된 필드는 param에 표시됩니다.param이 가리키는 필드를 고치세요.
400model_not_found모델 ID의 철자가 틀렸거나, model이 없거나, 이 엔드포인트에서 쓸 수 없는 모델입니다(예: 이미지 엔드포인트에 채팅 모델을 지정한 경우).GET /v1/models 또는 API 레퍼런스에 있는 모델 ID를 쓰세요.
400max_tokens_too_small추론 모델이 max_tokens를 모두 사고에 써서 답변을 쓰지 못했습니다(비스트리밍 채팅).max_tokens를 늘린 뒤 다시 시도하세요.
4xxinvalid_request모델 제공사가 요청을 거부했습니다(예: 컨텍스트가 너무 길거나 지원하지 않는 파라미터). 상태 코드와 message는 모델 제공사가 보낸 그대로 전달되며, code는 모델 제공사가 준 값입니다.message에 적힌 대로 요청을 고치세요.
401invalid_api_key키가 없거나, 삭제되었거나, 비활성화되었습니다. 계정이 비활성화된 경우에도 나옵니다.콘솔의 「API Keys」 페이지에서 이 키를 확인하세요.
402insufficient_quota이 요청의 크레딧을 예약하기에 잔액이 부족합니다. 게이트웨이는 요청에 들 수 있는 최대 비용을 먼저 예약하므로, 동시 호출이 몰릴 때도 이 오류가 날 수 있습니다.동시 호출이 몰린 경우라면 몇 초 기다린 뒤 다시 시도하고, 그렇지 않으면 충전하세요.
403permission_denied이 모델이 키의 모델 허용 목록에 없습니다.허용 목록에 있는 모델을 쓰거나, 콘솔에서 허용 목록을 수정하세요.
429rate_limit_exceeded이 키에 설정한 분당 요청 수를 넘었습니다(최근 60초 기준). Retry-After 헤더는 붙지 않습니다.몇 초 기다린 뒤 다시 시도하거나, 콘솔에서 이 키의 한도를 올리세요.
429rate_limit_exceeded이 모델이 가득 차서 요청을 보내지 못했습니다. 채팅 엔드포인트에서만 나오며, 이미지와 영상 작업은 거절되지 않고 대기열에서 기다립니다. OpenAI 호환 엔드포인트는 Retry-After를 붙입니다.Retry-After의 초만큼 기다린 뒤 다시 시도하세요.
502upstream_timeout업스트림이 시간 초과되었습니다. 첫 토큰이 너무 늦게 오는 경우도 포함됩니다.다시 시도하세요. 긴 답변에는 stream: true를 쓰세요.
502upstream_unavailable업스트림에 오류가 났거나 잠시 쓸 수 없습니다.잠시 후 다시 시도하세요.
502upstream_busy모델 제공사가 요청 빈도를 제한하고 있습니다. 모델 제공사의 429는 그대로 전달되지 않고 이 502로 바뀌어 돌아옵니다.잠시 후 다시 시도하세요.
502empty_completion모델 제공사가 빈 내용을 돌려주었습니다. 요청 내용에 대한 판정이 아닙니다.다시 시도하세요.
503model_maintenance모델이 점검 중이라 요청을 받지 않습니다. 점검 중에는 다른 모델이 대신 답변하지도 않습니다.점검이 끝나면 다시 시도하세요. 진행 상황은 서비스 상태에서 볼 수 있습니다.

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