Google Gemini API

Google Gemini API は Google のネイティブ生成 AI プロトコルです。クライアントが既に Google GenAI SDK 仕様に従って開発されている場合、Base URL と API Key を RouteAPI に切り替えるだけで、リクエスト構造を書き直すことなく直接使用できます。

プロトコル概要

Gemini API は、モデル名を URL パスに埋め込むというユニークな設計を使用しています。リクエストボディは contents 配列で会話を表現し、各メッセージの役割は user または model（assistant ではないことに注意）です。レスポンス構造は candidates 配列でラップされ、安全フィルタリングと複数候補生成をサポートしています。

利用シーン:

シーン	説明
Google GenAI SDK	google-generativeai Python / Node.js SDK、base_url を変更するだけ
Gemini REST クライアント	既に Gemini REST API 用に開発されたアプリケーション
マルチモーダルアプリケーション	画像、ビデオ、オーディオ入力のネイティブサポートが必要なシーン
Google AI Studio エクスポート	AI Studio からエクスポートされたコードは直接移行可能

クライアントが OpenAI プロトコルのみをサポートしている場合は、Chat Completions を使用してください。RouteAPI は内部で必要なフォーマット変換を行いますが、クライアントがネイティブにサポートするプロトコルを優先することで、最高の互換性が得られます。

エンドポイント形式

Gemini API のエンドポイント設計は独特です：モデル名が URL パスに直接埋め込まれます。

POST /v1beta/models/{model}:generateContent

完全なアドレスの例:

https://api.routeapi.ai/v1beta/models/gemini-1.5-pro:generateContent

ストリーミングエンドポイント:

https://api.routeapi.ai/v1beta/models/gemini-1.5-pro:streamGenerateContent

{model} 部分を実際のモデル名（gemini-1.5-pro、gemini-1.5-flash、gemini-2.0-flash-exp など）に置き換えます。コロン前のモデル名とコロン後のメソッド名の間にスペースはありません。

リクエストヘッダー:

Authorization: Bearer sk-your-routeapi-token
Content-Type: application/json

すべてのプロトコルで同じ RouteAPI Token を使用します。Token はサーバー側に保存し、ブラウザ、モバイルデバイス、または公開リポジトリに公開しないでください。

リクエスト形式

フィールド	型	必須	説明
contents	array	はい	会話コンテンツリスト、最低1つ
generationConfig	object	いいえ	生成設定パラメータ
safetySettings	array	いいえ	安全フィルタリング設定
systemInstruction	object	いいえ	システム指示、独立したフィールド
tools	array	いいえ	関数呼び出しツール定義
toolConfig	object	いいえ	ツール呼び出し設定

基本リクエスト例:

{
  "contents": [
    {
      "role": "user",
      "parts": [
        { "text": "RouteAPI を一文で紹介してください" }
      ]
    }
  ],
  "generationConfig": {
    "temperature": 0.7,
    "maxOutputTokens": 1024
  }
}

contents 構造の特殊性

Gemini API は3層のネスト構造を使用します:

1. contents 配列に複数のメッセージが含まれる
2. 各メッセージには role と parts フィールドがある
3. parts 配列に実際のコンテンツブロックが含まれる

主な違い:

• role は user または model のみ（assistant ではない）
• コンテンツは parts 配列に配置する必要があり、各要素は part オブジェクト
• マルチモーダル parts をサポート：テキスト、画像、ビデオ、オーディオを同じメッセージの parts に混在可能

{
  "contents": [
    {
      "role": "user",
      "parts": [
        { "text": "この画像を分析してください" },
        {
          "inlineData": {
            "mimeType": "image/jpeg",
            "data": "base64エンコードされた画像データ..."
          }
        }
      ]
    },
    {
      "role": "model",
      "parts": [
        { "text": "これは...を示す画像です" }
      ]
    }
  ]
}

generationConfig パラメータ

パラメータ	型	説明
temperature	number	サンプリング温度、範囲 0 から 2、デフォルト 1.0
topP	number	nucleus sampling パラメータ、デフォルト 0.95
topK	integer	確率が最も高い K 個のトークンからのみサンプリング
maxOutputTokens	integer	最大出力トークン数
stopSequences	array	カスタム停止シーケンス、最大5個
candidateCount	integer	生成する候補の数、デフォルト 1
responseMimeType	string	レスポンス形式、例 "application/json"
responseSchema	object	出力構造を制約する JSON Schema

例:

{
  "generationConfig": {
    "temperature": 0.9,
    "topP": 0.95,
    "topK": 40,
    "maxOutputTokens": 2048,
    "stopSequences": ["END", "STOP"]
  }
}

systemInstruction

システム指示は独立したフィールドで、contents には含まれません:

{
  "systemInstruction": {
    "parts": [
      { "text": "あなたは厳密な技術アシスタントで、回答は簡潔に保ちます。" }
    ]
  },
  "contents": [
    {
      "role": "user",
      "parts": [{ "text": "API ゲートウェイとは何かを説明してください" }]
    }
  ]
}

safetySettings

コンテンツ安全フィルタリングレベルを制御:

{
  "safetySettings": [
    {
      "category": "HARM_CATEGORY_HARASSMENT",
      "threshold": "BLOCK_MEDIUM_AND_ABOVE"
    },
    {
      "category": "HARM_CATEGORY_HATE_SPEECH",
      "threshold": "BLOCK_MEDIUM_AND_ABOVE"
    }
  ]
}

一般的なカテゴリ: HARM_CATEGORY_HARASSMENT、HARM_CATEGORY_HATE_SPEECH、HARM_CATEGORY_SEXUALLY_EXPLICIT、HARM_CATEGORY_DANGEROUS_CONTENT。

しきい値オプション: BLOCK_NONE、BLOCK_LOW_AND_ABOVE、BLOCK_MEDIUM_AND_ABOVE、BLOCK_ONLY_HIGH。

マルチモーダルコンテンツ

Gemini API はマルチモーダル入力をネイティブにサポートし、parts 配列の異なるタイプを通じて実現します。

テキスト

{ "text": "これはテキストコンテンツです" }

インライン画像（base64）

{
  "inlineData": {
    "mimeType": "image/jpeg",
    "data": "/9j/4AAQSkZJRgABAQAAAQ..."
  }
}

サポートされる画像形式: image/jpeg、image/png、image/webp、image/heic、image/heif。

画像 URL（fileData）

{
  "fileData": {
    "mimeType": "image/jpeg",
    "fileUri": "https://example.com/image.jpg"
  }
}

ビデオとオーディオ

{
  "fileData": {
    "mimeType": "video/mp4",
    "fileUri": "gs://bucket-name/video.mp4"
  }
}

ビデオサポート: video/mp4、video/mpeg、video/mov など。 オーディオサポート: audio/wav、audio/mp3、audio/aac など。

混合マルチモーダル例

{
  "contents": [
    {
      "role": "user",
      "parts": [
        { "text": "このビデオとこの画像の関連性を分析してください" },
        {
          "fileData": {
            "mimeType": "video/mp4",
            "fileUri": "gs://my-bucket/video.mp4"
          }
        },
        {
          "inlineData": {
            "mimeType": "image/jpeg",
            "data": "base64..."
          }
        }
      ]
    }
  ]
}

レスポンス形式

標準レスポンス

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "RouteAPI は複数の AI モデルプロバイダーを統一管理する API ゲートウェイです。"
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE"
        }
      ]
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 12,
    "candidatesTokenCount": 18,
    "totalTokenCount": 30
  }
}

レスポンスフィールド説明

フィールド	説明
candidates	候補レスポンス配列、デフォルトは1つ
candidates[].content	生成されたコンテンツ、リクエストの contents 要素と同じ構造
candidates[].content.role	常に "model"
candidates[].finishReason	完了理由
candidates[].safetyRatings	安全評価の詳細
usageMetadata	トークン使用統計

finishReason の値

値	意味
STOP	モデルが自然に終了
MAX_TOKENS	maxOutputTokens 制限に達した
SAFETY	安全フィルタートリガーによりブロック
RECITATION	コンテンツ重複検出によりブロック
OTHER	その他の理由

usageMetadata フィールド

フィールド	説明
promptTokenCount	入力トークン数
candidatesTokenCount	出力トークン数（すべての候補の合計）
totalTokenCount	合計トークン数
cachedContentTokenCount	キャッシュヒットトークン数（コンテキストキャッシングを使用した場合）

ストリーミング出力

streamGenerateContent エンドポイントを使用してストリーミングレスポンスを実装:

POST /v1beta/models/{model}:streamGenerateContent

ストリーミングレスポンスは SSE（Server-Sent Events）形式を使用し、各イベントは JSON オブジェクトです:

data: {"candidates":[{"content":{"parts":[{"text":"RouteAPI"}],"role":"model"},"finishReason":""}],"usageMetadata":{"promptTokenCount":12,"candidatesTokenCount":1,"totalTokenCount":13}}

data: {"candidates":[{"content":{"parts":[{"text":" は"}],"role":"model"},"finishReason":""}],"usageMetadata":{"promptTokenCount":12,"candidatesTokenCount":3,"totalTokenCount":15}}

data: {"candidates":[{"content":{"parts":[{"text":"API ゲートウェイ"}],"role":"model"},"finishReason":""}],"usageMetadata":{"promptTokenCount":12,"candidatesTokenCount":5,"totalTokenCount":17}}

data: {"candidates":[{"content":{"parts":[{"text":""}],"role":"model"},"finishReason":"STOP","safetyRatings":[{"category":"HARM_CATEGORY_HARASSMENT","probability":"NEGLIGIBLE"}]}],"usageMetadata":{"promptTokenCount":12,"candidatesTokenCount":18,"totalTokenCount":30}}

ストリーミングの特徴:

• 各チャンクは完全な JSON オブジェクトで、完全な candidates 構造を含む
• finishReason が空文字列の場合は継続、値がある場合は完了
• 最後のチャンクには完全な safetyRatings と最終的な usageMetadata が含まれる
• ストリーミングレスポンスには明示的な [DONE] マーカーがなく、finishReason で完了を判断

関数呼び出し（Function Calling）

Gemini API は関数呼び出しをサポートし、モデルが外部ツールを呼び出すことを可能にします。

ツール定義

{
  "tools": [
    {
      "functionDeclarations": [
        {
          "name": "get_weather",
          "description": "指定された都市の現在の天気を照会します。都市名は日本語のフル名を使用します。",
          "parameters": {
            "type": "object",
            "properties": {
              "city": {
                "type": "string",
                "description": "都市名、例: 東京"
              },
              "unit": {
                "type": "string",
                "enum": ["celsius", "fahrenheit"]
              }
            },
            "required": ["city"]
          }
        }
      ]
    }
  ]
}

関数呼び出しレスポンス

モデルが関数呼び出しリクエストを返す:

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "functionCall": {
              "name": "get_weather",
              "args": {
                "city": "東京",
                "unit": "celsius"
              }
            }
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP"
    }
  ]
}

関数結果を返す

関数実行結果を新しい user メッセージとして返す:

{
  "contents": [
    {
      "role": "user",
      "parts": [{ "text": "東京の現在の天気はどうですか？" }]
    },
    {
      "role": "model",
      "parts": [
        {
          "functionCall": {
            "name": "get_weather",
            "args": { "city": "東京", "unit": "celsius" }
          }
        }
      ]
    },
    {
      "role": "user",
      "parts": [
        {
          "functionResponse": {
            "name": "get_weather",
            "response": {
              "content": "東京、晴れ、気温 23 度、湿度 45%。"
            }
          }
        }
      ]
    }
  ]
}

OpenAI フォーマットとの比較

構造差異比較表

項目	Gemini API	OpenAI Chat Completions
エンドポイント形式	/v1beta/models/{model}:generateContent	/v1/chat/completions
モデル指定	URL パス内	リクエストボディの model フィールド
会話配列フィールド	contents	messages
メッセージ構造	role + parts 配列	role + content 文字列/配列
役割名	user / model	user / assistant / system
システム指示	systemInstruction オブジェクト	messages 内の role: "system"
レスポンスラッパー	candidates 配列	choices 配列
レスポンスコンテンツの場所	candidates[0].content.parts[0].text	choices[0].message.content
完了理由フィールド	finishReason	finish_reason
使用統計フィールド	usageMetadata	usage

パラメータマッピング表

Gemini API	OpenAI Chat Completions	備考
generationConfig.temperature	temperature	Gemini 上限 2、OpenAI も 2
generationConfig.topP	top_p	命名スタイルが異なる
generationConfig.topK	対応なし	OpenAI はサポートなし
generationConfig.maxOutputTokens	max_tokens / max_completion_tokens	フィールド名が異なる
generationConfig.stopSequences	stop	名前が異なる
generationConfig.candidateCount	n	意味は同じ
generationConfig.responseMimeType	response_format.type	制御方法が異なる
generationConfig.responseSchema	response_format.json_schema	階層が異なる
safetySettings	対応なし	OpenAI はコンテンツモデレーション API を使用
tools[].functionDeclarations	tools[].function	ラッパーレベルが異なる
toolConfig	tool_choice	フィールド名と構造が異なる

移行時の注意事項

OpenAI から Gemini API に移行する際は、以下の順序で確認:

1. モデル名を URL パスに移動: /v1beta/models/gemini-1.5-pro:generateContent
2. messages を contents に改名、各メッセージの構造を role + parts 配列に変更
3. すべての assistant 役割を model に変更
4. content フィールドを parts 配列に変更、テキストコンテンツを { "text": "..." } でラップ
5. システムプロンプトを messages 配列から systemInstruction オブジェクトに移動
6. 生成パラメータを generationConfig オブジェクトにラップし、フィールド名を調整（例: maxOutputTokens、stopSequences）
7. レスポンス解析を candidates[0].content.parts[0].text からコンテンツを抽出するように変更
8. ストリーミングエンドポイントを streamGenerateContent に変更、各チャンクは完全な JSON
9. ツール定義を functionDeclarations ラッパーに変更、パラメータフィールドを parameters に変更

役割名対応

Gemini	OpenAI	Claude
user	user	user
model	assistant	assistant
独立した役割なし	system	独立した役割なし
独立した役割なし	tool	独立した役割なし

Gemini と Claude はどちらもシステム指示をトップレベルフィールドに昇格させ、メッセージ役割としては扱いません。

完全な例

基本会話（curl）

curl https://api.routeapi.ai/v1beta/models/gemini-1.5-pro:generateContent \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          { "text": "RouteAPI を一文で紹介してください" }
        ]
      }
    ],
    "generationConfig": {
      "temperature": 0.7,
      "maxOutputTokens": 1024
    }
  }'

基本会話（Python SDK）

Google GenAI Python SDK を使用、client_options のみ変更:

import os
import google.generativeai as genai
from google.api_core.client_options import ClientOptions

# RouteAPI エンドポイントを設定
genai.configure(
    api_key=os.environ["ROUTEAPI_KEY"],
    transport="rest",
    client_options=ClientOptions(
        api_endpoint="https://api.routeapi.ai/v1beta"
    )
)

model = genai.GenerativeModel("gemini-1.5-pro")

response = model.generate_content(
    "RouteAPI を一文で紹介してください",
    generation_config={
        "temperature": 0.7,
        "max_output_tokens": 1024
    }
)

print(response.text)
print(f"入力トークン: {response.usage_metadata.prompt_token_count}")
print(f"出力トークン: {response.usage_metadata.candidates_token_count}")

画像入力例（Python SDK）

import os
import google.generativeai as genai
from google.api_core.client_options import ClientOptions
from PIL import Image

genai.configure(
    api_key=os.environ["ROUTEAPI_KEY"],
    transport="rest",
    client_options=ClientOptions(
        api_endpoint="https://api.routeapi.ai/v1beta"
    )
)

model = genai.GenerativeModel("gemini-1.5-pro")

image = Image.open("screenshot.jpg")

response = model.generate_content(
    ["この画像にはどのような UI コントロールがありますか？", image],
    generation_config={"max_output_tokens": 2048}
)

print(response.text)

ストリーミング出力例（Python SDK）

import os
import google.generativeai as genai
from google.api_core.client_options import ClientOptions

genai.configure(
    api_key=os.environ["ROUTEAPI_KEY"],
    transport="rest",
    client_options=ClientOptions(
        api_endpoint="https://api.routeapi.ai/v1beta"
    )
)

model = genai.GenerativeModel("gemini-1.5-pro")

response = model.generate_content(
    "API ゲートウェイとは何かを段階的に説明してください",
    stream=True
)

for chunk in response:
    print(chunk.text, end="", flush=True)

print()

互換性に関する注意

• パラメータの実際のサポート範囲は、選択したモデルとアップストリームサービスの機能によって異なります。一部の高度な機能（コンテキストキャッシング、コード実行など）は、まずテスト環境で検証することをお勧めします。
• 明示的に 0 または false を渡されたオプションパラメータは、ユーザーが明示的に設定したものとして扱われ、デフォルト値として破棄されません。
• 本番環境ではモデル ID を固定し、一時的なエイリアスや表示名に依存しないでください。
• 各リクエストのモデル ID、ステータスコード、トークン使用量を記録し、レイテンシーとコストの異常のトラブルシューティングを容易にします。
• fileUri で gs:// プロトコルを使用する場合は、ファイルがアップストリームからアクセス可能であることを確認するか、inlineData を使用して直接送信してください。
• エラーレスポンス形式は OpenAI/Claude と異なる場合があります。詳細は エラー処理 を参照してください。