> ## 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 API（generateContent）の使い方

> GeminiネイティブのgenerateContentエンドポイントを、LaoZhang API経由でcURLまたはPython SDKから呼び出し、テキスト、画像、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/ja/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/ja/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/ja/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が付加します。タイムアウトの単位はミリ秒です。
>
> ```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のベースURLに `/v1` を付けたり、このエンドポイントでVertex AIのプロジェクト・ロケーション・パブリッシャーのパスを使ったりしないでください。

### 回答をストリーミングする

回答をストリーミングするには、同じ本文を `https://api.laozhang.ai/v1beta/models/gemini-3.8-flash:streamGenerateContent?alt=sse` に送ります。各server-sent eventには、同じ `candidates` 構造の部分的なレスポンスが入ります。

## リクエストの構造

`contents` には、メッセージが順番に入ります。各メッセージには `role` と、1つ以上の `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/ja/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",
>         ),
>         "この音声を文字起こしし、そのあと1文で要約してください。",
>     ],
> )
> 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`、メッセージのロール、メディアのエンコード、エラーに挙げられた任意の設定を確認してください。
* **テキストのないレスポンス：** candidates、finish reason、ブロックのフィードバック、テキスト以外のコンテンツを確認してください。
* **「Cannot fetch content from the provided URL」の400：** 画像や動画のURLを直接ダウンロードできません。ログイン不要で、サイトの `robots.txt` にブロックされていない公開の直リンクを使うか、`inlineData` でファイルを送ってください。
* **413：** リクエスト本文が大きすぎます。リクエスト全体を20MB以内に収め、大きなファイルは `fileData` でリンクを渡してください。
* **ファイルのアップロードでWebページまたは404が返る：** File APIは利用できません。代わりに `inlineData` か `fileData` のURLを使ってください。
* **cURLでは動くがSDKでは失敗する：** SDKのベースURLとAPIバージョンを確認してください。最終的なURLには、`/v1beta/models/` が1回だけ含まれるはずです。

タイムアウトや一時的なサーバーエラーが出たときは、再試行する前に[呼び出しログ](https://api.laozhang.ai/log)を確認してください。サポートに連絡するときは、リクエストの時刻、モデル、認証情報を伏せたエラーを添えてください。

## よくある質問

### Gemini APIの料金は？ Googleアカウントは必要？

Googleアカウントも、AI StudioのAPIキーも不要です。LaoZhang APIのキーだけで利用でき、Geminiのテキストモデルは、プリペイド残高からトークン単位で課金されます。2026年10月14日時点の公開価格で、1Mトークンあたりの金額です。

* `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/ja/models.md)に、リクエストごとの課金額は[呼び出しログ](https://docs.laozhang.ai/en/faq/call-logs.md)にあります。同時リクエストにプラットフォーム側の上限はなく、スロットリングもありません。`429` が出るのは上流の処理能力によるものです。[同時リクエストと429](https://docs.laozhang.ai/ja/faq/api-concurrency.md)を参照してください。

### OpenAI互換のエンドポイントで送れるメディアは？

`/v1/chat/completions` でGeminiモデルを使う場合は次のとおりです。

* 画像：`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/ja/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/ja/api-capabilities/nano-banana-pro-image.md)を参照してください。
* **Veo：** 2026年9月28日時点で、Veoは公開モデルカタログに載っておらず、ネイティブの `predictLongRunning` リクエストは利用可能なチャネルがないというエラーを返します。動画生成には[Wan 2.7](https://docs.laozhang.ai/ja/api-capabilities/wan-video-generation.md)か[Seedance 2.0](https://docs.laozhang.ai/ja/api-capabilities/seedance2-video-generation.md)を使ってください。

### AI StudioとVertex AIのどちらですか？

AI Studioです。LaoZhang APIは、GeminiのテキストモデルとNano Bananaの画像モデルを、Vertex AIではなくGoogleのGemini API（AI Studio）経由で呼び出しています。そのため、次のようになります。

* モデルID、提供終了日、安全ポリシーは、Googleの[deprecationsページ](https://ai.google.dev/gemini-api/docs/deprecations)など、[Gemini APIドキュメント](https://ai.google.dev/gemini-api/docs)に従います。
* リクエストは、AI Studio形式の `v1beta` パスを使い、Vertexのプロジェクトやロケーションは使いません。
* 上流の障害が疑われるときは、Gemini APIのインシデントについて[AI Studioのステータスページ](https://aistudio.google.com/status)を確認してください。

## 関連ドキュメント

* [動画理解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/ja/api-reference/chat-completions.md)
* [モデルカタログと料金](https://docs.laozhang.ai/ja/models.md)
* [モデルへのアクセスと権限](https://docs.laozhang.ai/en/faq/model-availability.md)
* [API接続ガイド](https://docs.laozhang.ai/ja/api-manual.md)


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