> ## Documentation Index
> Fetch the complete documentation index at: https://docs.laozhang.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Gemini 프로토콜: generateContent와 SDK 연동

> Gemini 네이티브 generateContent 엔드포인트를 cURL이나 Python SDK로 LaoZhang API에서 호출하고, 텍스트·이미지·PDF·오디오·MP4 비디오를 보내는 방법입니다.

애플리케이션이 이미 Gemini 형식으로 요청을 보낸다면 Gemini 네이티브 generateContent 엔드포인트를 쓰세요. Google Gen AI SDK나 요청의 대상을 `https://api.laozhang.ai`로 바꾸고 LaoZhang API 키를 사용하면 됩니다.

| 항목 | 내용 |
| - | - |
| 요청과 응답 | `generateContent`에 `contents`를 보내고 `candidates`를 읽습니다 |
| 형식 | Gemini Developer API 형식, `v1beta` 버전, 경로에 모델 ID |
| 모델 | [모델 및 가격](https://docs.laozhang.ai/ko/models.md)의 **Endpoints** 열에 Gemini가 표시된 모델 |
| 예제 모델 | `gemini-3.8-flash` |
| 미디어 입력 | 이미지, PDF, 오디오, MP4 비디오. 비디오는 [비디오 이해 API](https://docs.laozhang.ai/en/api-capabilities/video-understanding.md)를 참고하세요 |

엔드포인트는 다음과 같습니다.

```text theme={null}
POST https://api.laozhang.ai/v1beta/models/{model}:generateContent
```

애플리케이션이 이미 OpenAI 스타일 `messages`를 쓴다면 [OpenAI 프로토콜](https://docs.laozhang.ai/ko/api-reference/chat-completions.md)로 Gemini 모델을 호출하세요.

## 인증 정보와 모델 선택

[토큰 관리](https://api.laozhang.ai/token)에서 과금 방식을 사용량 우선(콘솔 표시: 按量优先, 권장) 또는 사용량 과금(按量计费)으로 설정해 모델 API 키(콘솔에서는 '토큰'이라고 부릅니다)를 만들고, 터미널에서 환경 변수로 설정하세요.

```bash theme={null}
export LAOZHANG_API_KEY="YOUR_LAOZHANG_API_KEY"
```

[모델 및 가격](https://docs.laozhang.ai/ko/models.md)의 **Endpoints** 열에 Gemini가 표시된 모델이 이 형식을 받습니다. 예제는 `gemini-3.8-flash`를 사용하며, 내 토큰 그룹에서 쓸 수 있는지는 [콘솔 가격 페이지](https://api.laozhang.ai/account/pricing)에서 확인하세요.

네이티브 Gemini 요청은 `Authorization: Bearer` 또는 `x-goog-api-key` 인증을 모두 받습니다. Google Gen AI SDK는 API 키 헤더를 자동으로 보냅니다.

## 텍스트 생성

> [tab] cURL
>
> ```bash theme={null}
> 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라고만 답하세요"}]
>     }]
>   }'
> ```
>
> Google의 API 키 헤더를 쓰려면 `Authorization` 헤더를 다음으로 바꾸세요.
>
> ```bash theme={null}
> -H "x-goog-api-key: $LAOZHANG_API_KEY"
> ```

> [tab] Python
>
> SDK를 설치합니다.
>
> ```bash theme={null}
> python -m pip install google-genai
> ```
>
> `base_url`은 호스트 루트로, `api_version`은 `v1beta`로 설정합니다. 버전과 모델 경로는 SDK가 붙여 주며, SDK의 타임아웃은 밀리초 단위입니다.
>
> ```python theme={null}
> 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)
> ```

답변에 `connected`가 들어 있어야 합니다. 이 엔드포인트에서는 Google SDK의 base URL에 `/v1`을 붙이거나 Vertex AI의 project/location/publisher 경로를 쓰지 마세요.

### 답변 스트리밍

답변을 스트리밍하려면 같은 본문을 `https://api.laozhang.ai/v1beta/models/gemini-3.8-flash:streamGenerateContent?alt=sse`로 보내세요. 각 서버 전송 이벤트에는 같은 `candidates` 구조의 부분 응답이 담겨 있습니다.

## 요청 구조

`contents`에는 메시지가 순서대로 들어갑니다. 각 메시지에는 `role`과 하나 이상의 `parts`가 있습니다.

| 필드 | 의미 |
| - | - |
| `contents` | 필수. 대화 메시지 배열 |
| `role` | 사용자 입력은 `user`, 모델 답변은 `model` |
| `parts` | 텍스트와 모델이 받는 미디어를 포함한 메시지 내용 |
| `text` | 텍스트 파트 |
| `inlineData` | `mimeType`과 Base64로 인코딩한 `data`가 있는 인라인 미디어 |
| `fileData` | `fileUri`와 `mimeType`으로 URL을 참조하는 미디어 |
| `systemInstruction` | 대화와 별도로 전달하는 지시문 |
| `generationConfig` | 모델별 생성 설정 |

REST JSON은 `inlineData`, `mimeType`처럼 camelCase를 씁니다. Python SDK 속성은 `inline_data`, `mime_type` 같은 이름을 쓰므로, 호출하는 인터페이스에 맞는 표기를 쓰세요. 선택 설정과 미디어 지원 여부는 모델마다 다릅니다.

### 이미지 보내기

`gemini-3.8-flash`처럼 이미지 입력을 받는 모델에는 같은 메시지에 텍스트 파트와 `inlineData` 파트를 함께 넣습니다. 다음 코드는 로컬의 `input.png`를 읽어 JSON 요청 파일을 만듭니다.

```python theme={null}
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")
```

이 파일을 요청 본문으로 보냅니다.

```bash theme={null}
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
```

MIME 타입은 실제 이미지와 일치해야 합니다. `data`에는 `data:image/png;base64,` 접두사 없이 순수 Base64만 넣습니다.

이미지를 설명하는 것과 이미지를 생성하는 것은 서로 다른 작업입니다. Gemini 이미지 모델로 이미지를 만들거나 편집하려면 [Nano Banana 개요](https://docs.laozhang.ai/ko/api-capabilities/nano-banana-image.md)를 보세요. OpenAI 형식으로 비전 모델에 이미지를 보내려면 [이미지 이해 API](https://docs.laozhang.ai/en/api-capabilities/vision-understanding.md)를 보세요.

## PDF와 오디오 파일 보내기

PDF와 오디오도 이미지처럼 `inlineData`에 넣으며 `mimeType`만 달라집니다.

| 파일 | `mimeType` | 모델이 할 수 있는 일 |
| - | - | - |
| PDF | `application/pdf` | 모든 페이지를 읽고 여러 페이지에 걸친 질문에 답변 |
| MP3 오디오 | `audio/mp3` | 영어나 중국어 음성을 받아쓰거나 요약하고, 내용에 대한 질문에 답변 |

아래 예제는 현재 디렉터리의 `invoice.pdf`를 읽습니다. 오디오는 파일 이름을 `audio.mp3`로, `mimeType`을 `audio/mp3`로 바꾸고 프롬프트를 조정하세요.

> [tab] cURL
>
> 요청 본문을 만듭니다.
>
> ```python theme={null}
> 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")
> ```
>
> 그런 다음 보냅니다.
>
> ```bash theme={null}
> 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
> ```

> [tab] Python SDK
>
> ```python theme={null}
> 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)
> ```

오디오는 토큰으로 과금되며 `usageMetadata.promptTokensDetails`에 `AUDIO`로 표시됩니다. 추가 추론 없이 받아쓰기만 필요하다면 [오디오 전사 API](https://docs.laozhang.ai/en/api-capabilities/audio-transcription.md)를 써도 됩니다.

## 비디오 이해

MP4 비디오도 `inlineData`에 넣고 `mimeType`을 `video/mp4`로 설정합니다. 공개 URL이나 공개 YouTube 비디오는 `fileData`로 전달하세요. 모델은 프레임과 오디오 트랙을 함께 읽습니다.

```json theme={null}
{"inlineData": {"mimeType": "video/mp4", "data": "<BASE64_DATA>"}}
```

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

전체 예제와 자주 하는 작업은 [비디오 이해 API](https://docs.laozhang.ai/en/api-capabilities/video-understanding.md) 페이지에 있습니다.

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

## 응답 읽기

텍스트 답변은 다음 구조이며 다른 메타데이터는 생략했습니다.

```json theme={null}
{
  "candidates": [{
    "content": {
      "role": "model",
      "parts": [{"text": "connected"}]
    },
    "finishReason": "STOP"
  }]
}
```

텍스트는 후보의 `content.parts`에서 읽으며 파트가 여러 개일 수 있습니다. Python SDK의 `response.text` 헬퍼가 텍스트를 모아 줍니다. 애플리케이션에 미디어, 도구 호출, 대화 기록이 필요하면 후보 콘텐츠 전체를 보관하세요.

응답에 텍스트가 없으면 `promptFeedback`, `finishReason`, 텍스트가 아닌 파트를 확인하세요. 콘텐츠 차단, 출력 제한, 도구 호출은 네트워크 오류와 다르게 처리해야 합니다. 사용량 상세는 있으면 `usageMetadata`에 나타나고, 계정에 청구된 금액은 [호출 로그](https://docs.laozhang.ai/en/faq/call-logs.md)에서 확인할 수 있습니다.

### 대화 이어 가기

`contents`에 이전 사용자 메시지, 모델의 전체 답변, 새 사용자 메시지를 차례로 보냅니다. Gemini에서는 모델 답변의 역할이 `assistant`가 아니라 `model`입니다.

모델 워크플로를 이어 갈 때는 반환된 파트를 그대로 보존하세요. `thoughtSignature`를 반환하는 모델이라면 서명을 해당 파트와 함께 바꾸지 않고 돌려보내세요.

도구 호출 모델은 각 `functionCall`에 맞는 `functionResponse`를 짝지어야 합니다. 텍스트 요약으로는 도구 결과 구조를 대신할 수 없습니다. 이 메시지 형식은 Google의 [generateContent 레퍼런스](https://ai.google.dev/api/generate-content)를 참고하세요.

## 오류 해결

* **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/`가 한 번만 들어 있어야 합니다.

타임아웃이나 일시적인 서버 오류가 났다면 재시도하기 전에 [호출 로그](https://api.laozhang.ai/log)를 확인하세요. 고객 지원에 문의할 때는 요청 시각, 모델, 인증 정보를 지운 오류 메시지를 함께 보내세요.

## 자주 묻는 질문

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

Google 계정이나 AI Studio API 키는 필요 없습니다. LaoZhang API 키만 있으면 되고, Gemini 텍스트 모델은 선불 잔액에서 토큰 사용량으로 과금됩니다. 2026년 10월 14일 기준 공개 가격이며 100만 토큰당입니다.

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

그 밖의 Gemini 모델과 긴 컨텍스트 구간 가격은 [모델 및 가격](https://docs.laozhang.ai/ko/models.md)에 있고, 요청별 청구 금액은 [호출 로그](https://docs.laozhang.ai/en/faq/call-logs.md)에서 볼 수 있습니다. 플랫폼 차원의 동시 요청 제한이나 스로틀링은 없습니다. `429`는 업스트림 용량에서 오는 것이니 [동시 요청과 429](https://docs.laozhang.ai/ko/faq/api-concurrency.md)를 참고하세요.

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

Gemini 모델을 `/v1/chat/completions`로 호출할 때는 다음과 같습니다.

* 이미지: `image_url`에 URL이나 Base64 데이터 URL을 보냅니다. [이미지 이해 API](https://docs.laozhang.ai/en/api-capabilities/vision-understanding.md)를 참고하세요.
* 비디오: `video_url`에 Base64 데이터 URL을 보냅니다. [OpenAI SDK로 호출하기](https://docs.laozhang.ai/en/api-capabilities/video-understanding.md)를 참고하세요.
* `file` 파트의 PDF와 `input_audio` 파트의 오디오는 버려집니다. 요청은 여전히 200을 반환하고, 모델은 파일을 보지 못한 채 답할 수 있습니다. 이런 파일은 이 페이지의 `inlineData`로 보내세요.

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

쓸 수 없습니다. Gemini 모델은 `/v1/responses`에서 400을 반환합니다. OpenAI SDK로는 Chat Completions를 호출하고, PDF, 오디오, 비디오, 비디오 URL은 이 페이지의 네이티브 엔드포인트를 쓰세요.

### Google File API를 지원하나요?

지원하지 않습니다. 다음은 모두 사용할 수 없습니다.

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

로컬 파일은 `inlineData`로, 공개 비디오는 `fileData` URL로 보내세요.

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

Gemini 텍스트 모델은 토큰으로 과금합니다. 이미지, PDF, 오디오, 비디오는 모두 입력 토큰으로 변환되며, `usageMetadata.promptTokensDetails`에 `IMAGE`, `AUDIO`, `VIDEO` 같은 유형별로 표시됩니다. 가격은 [모델 및 가격](https://docs.laozhang.ai/ko/models.md)에 있고, 요청별 청구 금액은 [호출 로그](https://docs.laozhang.ai/en/faq/call-logs.md)에서 확인할 수 있습니다.

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

* **Nano Banana Pro:** `gemini-3-pro-image`는 네이티브 `generateContent`로 호출할 수 있습니다. [Nano Banana Pro 이미지 생성](https://docs.laozhang.ai/ko/api-capabilities/nano-banana-pro-image.md)을 참고하세요.
* **Veo:** 2026년 9월 28일 기준 Veo는 공개 모델 카탈로그에 없으며, 네이티브 `predictLongRunning` 요청은 사용 가능한 채널이 없다는 오류를 반환합니다. 비디오 생성에는 [Wan 2.7](https://docs.laozhang.ai/ko/api-capabilities/wan-video-generation.md) 또는 [Seedance 2.0](https://docs.laozhang.ai/ko/api-capabilities/seedance2-video-generation.md)을 쓰세요.

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

AI Studio입니다. LaoZhang API는 Gemini 텍스트 모델과 Nano Banana 이미지 모델을 Vertex AI가 아니라 Google의 Gemini API(AI Studio)로 호출합니다. 따라서 다음과 같습니다.

* 모델 ID, 종료 일정, 안전 정책은 Google의 [지원 중단 안내](https://ai.google.dev/gemini-api/docs/deprecations) 등 [Gemini API 문서](https://ai.google.dev/gemini-api/docs)를 따릅니다.
* 요청은 Vertex 프로젝트나 리전 없이 AI Studio 방식의 `v1beta` 경로를 씁니다.
* 업스트림 장애가 의심되면 [AI Studio 상태 페이지](https://aistudio.google.com/status)에서 Gemini API 장애를 확인하세요.

## 관련 문서

* [비디오 이해 API](https://docs.laozhang.ai/en/api-capabilities/video-understanding.md)
* [Google generateContent 레퍼런스](https://ai.google.dev/api/generate-content)
* [Google Gen AI Python SDK](https://googleapis.github.io/python-genai/)
* [OpenAI 프로토콜: Chat Completions](https://docs.laozhang.ai/ko/api-reference/chat-completions.md)
* [모델 및 가격](https://docs.laozhang.ai/ko/models.md)
* [모델 접근 및 권한](https://docs.laozhang.ai/en/faq/model-availability.md)
* [API 연동 가이드](https://docs.laozhang.ai/ko/api-manual.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.