Gemini 네이티브

Gemini generateContent 요청과 BeatAPI 키 하나로 Gemini 4 Argon, Gemini 4 Carbon, Gemini 3.8 Flash, Gemini 3.1 Pro를 호출합니다.

• 현재 모든 Gemini 모델에 POST /v1beta/models/{model}:generateContent를, 스트리밍에는 :streamGenerateContent?alt=sse를 사용합니다.
• 텍스트·이미지 입력, 텍스트 출력, 스트리밍, 함수 호출, 사고.
• 키는 x-goog-api-key 헤더나 Bearer 토큰으로 보내세요.
• 모델은 본문이 아니라 URL에 지정합니다.

API Explorer에서 이 엔드포인트를 엽니다. BeatAPI API 키를 입력하고 전송하세요. 실제 호출이며 본인 잔액에서 과금됩니다.

모델

URL의 {model} 자리에 다음 ID 중 하나를 넣으세요.

• 가격은 할인이 적용된 기본 등급입니다. 롱 컨텍스트 등급, 캐시 입력 요금, 캐시 쓰기는 이 표에 없습니다. 가격표를 참고하세요.
• —는 카탈로그에서 해당 수치를 공개하지 않는다는 뜻입니다.

이 계열의 이전 ID도 계속 동작하며 레거시 모델에 나와 있습니다.

빠른 시작

키는 BEATAPI_API_KEY에 보관하고 브라우저 코드에는 절대 넣지 마세요. 모델 ID는 URL에 들어가므로 본문에는 model 필드가 없습니다. 아래는 요청 예시이며 실제로 기록된 모델 출력이 아닙니다.

candidates[0].content.parts[0].text에서 답변을 읽은 다음 candidates[0].finishReason과 usageMetadata를 확인하세요. HTTP 200만으로는 답변이 작업 요구를 충족한다고 볼 수 없으니 애플리케이션에서 검증하세요. 텍스트 요청은 바로 반환되므로 /v1/tasks를 폴링하지 마세요.

curl --request POST \
  --url https://direct.beatapi.io/v1beta/models/gemini-3.8-flash:generateContent \
  --header "x-goog-api-key: $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Design a resilient webhook retry strategy for a payments API."
        }
      ]
    }
  ]
}'

엔드포인트와 인증

POST https://direct.beatapi.io/v1beta/models/{model}:generateContent

스트리밍은 POST /v1beta/models/{model}:streamGenerateContent?alt=sse를 호출하세요. 키는 x-goog-api-key 헤더나 Authorization: Bearer <key>에 넣으며 둘 다 동작합니다.

:countTokens는 사용할 수 없으며 404를 반환합니다.

요청 파라미터

아래는 효과가 있는 필드입니다. 다른 Gemini 필드(generationConfig.thinkingConfig, generationConfig.responseMimeType, generationConfig.responseSchema, generationConfig.seed, safetySettings, toolConfig, cachedContent)는 요청에서 받지만 효과가 없으니 의존하지 마세요.

[
  {
    "role": "user",
    "parts": [
      { "text": "What is in this image?" },
      { "inlineData": { "mimeType": "image/png", "data": "<base64>" } }
    ]
  }
]

{
  "parts": [{ "text": "Answer in one short paragraph." }]
}

{
  "temperature": 0.7,
  "topP": 0.95,
  "maxOutputTokens": 2048,
  "stopSequences": ["END"]
}

[
  {
    "functionDeclarations": [
      {
        "name": "get_weather",
        "description": "Get the current weather for a city.",
        "parameters": {
          "type": "object",
          "properties": { "city": { "type": "string" } },
          "required": ["city"]
        }
      }
    ]
  }
]

응답

스트리밍하지 않는 호출은 JSON 객체 하나를 반환합니다. 아래는 축약한 예시입니다.

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "Retry with exponential backoff and jitter, and make every handler idempotent."
          }
        ]
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 19,
    "candidatesTokenCount": 16,
    "totalTokenCount": 120,
    "thoughtsTokenCount": 85
  }
}

응답 필드

스트리밍

:streamGenerateContent?alt=sse를 호출하세요. 모든 이벤트는 candidates 객체를 담은 data: {...} 한 줄이며, 스트리밍하지 않는 답변과 형식이 같습니다.

• 마지막 이벤트에는 finishReason이 있습니다(예: "STOP").
• 응답은 text/event-stream입니다. 모델 호출 전에 발생한 실패는 스트림 이벤트가 아니라 HTTP 상태와 함께 일반 JSON 오류로 반환됩니다.
• 명시적인 시간 제한을 설정하고, 스트리밍 응답은 안전하게 다시 연결하세요.

data: {"candidates":[{"content":{"role":"model","parts":[{"text":"Retry"}]},"index":0}]}
data: {"candidates":[{"content":{"role":"model","parts":[{"text":" with backoff"}]},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":19,"candidatesTokenCount":16,"totalTokenCount":120,"thoughtsTokenCount":85}}

오류

HTTP 오류 요약

Gemini 네이티브 엔드포인트의 오류 형식은 {"error": {"message", "type": "beatapi_error", "code"}} 하나입니다. 코드는 error.code에 있고, 요청 id는 message로 끝나며, retryable 필드는 없습니다. 오류를 참고하세요.

전체 코드 표와 재시도 정책: 오류.

참고

• Gemini 모델은 Chat Completions, Responses, Anthropic Messages에서도 응답합니다. 다른 Gemini 페이지를 참고하세요.
• 사고 토큰은 출력 토큰으로 과금됩니다. 답변만이 아니라 사고와 답변을 합친 만큼 출력 한도를 잡으세요.
• API 키는 신뢰할 수 있는 서버에 두고, 응답의 요청 ID를 기록하며, 429, 500, 503만 재시도하세요.