Gemini 프로토콜: generateContent와 SDK 연동

POST https://api.laozhang.ai/v1beta/models/{model}:generateContent

​

인증 정보와 모델 선택

export LAOZHANG_API_KEY="YOUR_LAOZHANG_API_KEY"

​

텍스트 생성

curl --fail-with-body --max-time 120 \
  "https://api.laozhang.ai/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{"text": "connected라고만 답하세요"}]
    }]
  }'

-H "x-goog-api-key: $LAOZHANG_API_KEY"

python -m pip install google-genai

import os
from google import genai

client = genai.Client(
    api_key=os.environ["LAOZHANG_API_KEY"],
    http_options={
        "base_url": "https://api.laozhang.ai",
        "api_version": "v1beta",
        "timeout": 120_000,
    },
)
response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents="connected라고만 답하세요",
)
print(response.text)

​

답변 스트리밍

​

요청 구조

​

이미지 보내기

import base64
import json
from pathlib import Path

request = {
    "contents": [{
        "role": "user",
        "parts": [
            {"text": "이 이미지에 있는 물체를 설명해 주세요."},
            {"inlineData": {
                "mimeType": "image/png",
                "data": base64.b64encode(Path("input.png").read_bytes()).decode("ascii"),
            }},
        ],
    }],
}
Path("gemini-request.json").write_text(json.dumps(request), encoding="utf-8")

curl --fail-with-body --max-time 120 \
  "https://api.laozhang.ai/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @gemini-request.json

​

PDF와 오디오 파일 보내기

import base64
import json
from pathlib import Path

request = {
    "contents": [{
        "role": "user",
        "parts": [
            {"inlineData": {
                "mimeType": "application/pdf",
                "data": base64.b64encode(Path("invoice.pdf").read_bytes()).decode("ascii"),
            }},
            {"text": "청구서 번호, 결제 금액, 결제 기한은 무엇인가요?"},
        ],
    }],
}
Path("gemini-file-request.json").write_text(json.dumps(request), encoding="utf-8")

curl --fail-with-body --max-time 120 \
  "https://api.laozhang.ai/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @gemini-file-request.json

import os
from pathlib import Path
from google import genai
from google.genai import types

client = genai.Client(
    api_key=os.environ["LAOZHANG_API_KEY"],
    http_options={
        "base_url": "https://api.laozhang.ai",
        "api_version": "v1beta",
        "timeout": 120_000,
    },
)
response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents=[
        types.Part.from_bytes(
            data=Path("audio.mp3").read_bytes(),
            mime_type="audio/mp3",
        ),
        "이 오디오를 받아쓴 다음 한 문장으로 요약해 주세요.",
    ],
)
print(response.text)

​

비디오 이해

{"inlineData": {"mimeType": "video/mp4", "data": "<BASE64_DATA>"}}

{"fileData": {"fileUri": "https://www.youtube.com/watch?v=9hE5-98ZeCg", "mimeType": "video/mp4"}}

• 로컬 비디오를 보내거나 비디오 URL을 분석합니다.
• 비디오를 타임스탬프가 있는 챕터로 나누거나 구조화된 JSON으로 반환합니다.
• videoMetadata로 구간을 자르거나 프레임 레이트를 바꿉니다.
• 비디오를 비교하거나, 답변을 스트리밍하거나, OpenAI SDK로 호출합니다.

​

응답 읽기

{
  "candidates": [{
    "content": {
      "role": "model",
      "parts": [{"text": "connected"}]
    },
    "finishReason": "STOP"
  }]
}

​

대화 이어 가기

​

오류 해결

• 401: API 키와 인증 헤더를 확인하세요. 계정 관리용 AccessToken이 아니라 모델 API 키를 써야 합니다.
• 404 또는 모델을 찾을 수 없음: v1beta, 정확한 모델 ID, 토큰 그룹의 네이티브 Gemini 접근 권한을 확인하세요.
• 400: 오류에 나온 contents, parts, 메시지 역할, 미디어 인코딩, 선택 설정을 점검하세요.
• 텍스트가 없는 응답: 후보, 종료 이유, 차단 피드백, 텍스트가 아닌 콘텐츠를 확인하세요.
• “Cannot fetch content from the provided URL”이 있는 400: 이미지나 비디오 URL을 직접 내려받을 수 없는 경우입니다. 로그인이 필요 없고 사이트의 robots.txt가 막지 않는 공개 직접 링크를 쓰거나, inlineData로 파일을 보내세요.
• 413: 요청 본문이 너무 큽니다. 전체 요청을 20MB 이하로 유지하고, 큰 파일은 fileData로 링크를 전달하세요.
• 파일 업로드가 웹 페이지나 404를 반환: File API는 사용할 수 없습니다. inlineData나 fileData URL을 대신 쓰세요.
• cURL은 되는데 SDK는 실패: SDK의 base URL과 API 버전을 확인하세요. 최종 URL에는 /v1beta/models/가 한 번만 들어 있어야 합니다.

​

자주 묻는 질문

​

Gemini API 요금은 얼마이고 Google 계정이 필요한가요?

• gemini-4-argon: 입력 $2, 출력 $10
• gemini-3.8-flash: 입력 $0.75, 출력 $3.75
• gemini-2.5-flash: 입력 $0.3, 출력 $2.4

​

OpenAI 호환 엔드포인트로 어떤 미디어를 보낼 수 있나요?

• 이미지: image_url에 URL이나 Base64 데이터 URL을 보냅니다. 이미지 이해 API를 참고하세요.
• 비디오: video_url에 Base64 데이터 URL을 보냅니다. OpenAI SDK로 호출하기를 참고하세요.
• file 파트의 PDF와 input_audio 파트의 오디오는 버려집니다. 요청은 여전히 200을 반환하고, 모델은 파일을 보지 못한 채 답할 수 있습니다. 이런 파일은 이 페이지의 inlineData로 보내세요.

​

Gemini 모델에서 Responses API를 쓸 수 있나요?

​

Google File API를 지원하나요?

• /upload/v1beta/files 업로드 엔드포인트
• files/... 참조
• SDK의 client.files.upload()

​

미디어 입력은 어떻게 과금되나요?

​

Veo나 Nano Banana Pro를 네이티브로 호출할 수 있나요?

• Nano Banana Pro: gemini-3-pro-image는 네이티브 generateContent로 호출할 수 있습니다. Nano Banana Pro 이미지 생성을 참고하세요.
• Veo: 2026년 9월 28일 기준 Veo는 공개 모델 카탈로그에 없으며, 네이티브 predictLongRunning 요청은 사용 가능한 채널이 없다는 오류를 반환합니다. 비디오 생성에는 Wan 2.7 또는 Seedance 2.0을 쓰세요.

​

Google 모델은 AI Studio와 Vertex AI 중 어디에서 실행되나요?

• 모델 ID, 종료 일정, 안전 정책은 Google의 지원 중단 안내 등 Gemini API 문서를 따릅니다.
• 요청은 Vertex 프로젝트나 리전 없이 AI Studio 방식의 v1beta 경로를 씁니다.
• 업스트림 장애가 의심되면 AI Studio 상태 페이지에서 Gemini API 장애를 확인하세요.

​

관련 문서

• 비디오 이해 API
• Google generateContent 레퍼런스
• Google Gen AI Python SDK
• OpenAI 프로토콜: Chat Completions
• 모델 및 가격
• 모델 접근 및 권한
• API 연동 가이드