Gemini 3.8 Flash · API

빠른 시작

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

1단계 · 요청 보내기

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

응답(HTTP 200)

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

message.content는 답변입니다. usage는 이 요청에 과금되는 토큰 수이며, 그중 prompt_tokens_details.cached_tokens는 캐시에 적중해 캐시 요금으로 과금되는 부분입니다.

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

curl -N https://nezhagate.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemini-3.8-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://nezhagate.com/v1", api_key="YOUR_API_KEY")

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

# 2. 스트리밍
stream = client.chat.completions.create(
    model="gemini-3.8-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.0048입니다.

사고(Thinking)

동적 사고: 질문마다 얼마나 생각할지 모델이 스스로 정해, 쉬운 질문은 빠르게 답하고 어려운 질문은 더 깊이 생각합니다. 별도의 파라미터는 필요 없습니다. 사고 토큰도 출력 한도에 포함되므로 max_tokens를 너무 작게 잡지 마세요.

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

프롬프트 캐싱

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

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

이미지 입력

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

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

웹 검색

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

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

안정성과 자동 재시도

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

오류와 환불

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

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