Gemini API 接続ガイド：Google互換呼び出しと大規模コンテキスト対応

1. 概要

当サイトでは Google Gemini API と互換性のある接続を提供しており、generateContent およびストリーミング生成の両方に対応しています。Google GenAI SDK や Gemini 互換クライアントを使用しているプロジェクトであれば、リクエスト先を当サイトのゲートウェイに変更し、APIキーを当サイトで発行した sk- から始まるキーに置き換えるだけで接続可能です。

現在利用可能な Gemini シリーズのモデルは、モデル一覧ページに準じます（gemini-3.7-flash、gemini-3.6-flash、gemini-3.5-flash、gemini-3.5-flash-lite など）。モデルの詳細なリストや単価は GET /v1/models から確認できます。

2. インターフェースアドレス

メソッド	パス	説明
POST	/v1beta/models/{model}:generateContent	Gemini 生成エンドポイント、リクエストボディは generateContent ペイロード
POST	/v1beta/models/{model}:streamGenerateContent?alt=sse	ストリーミング生成 (SSE)
GET	/v1/models	モデルと単価の一覧（認証不要）

ゲートウェイURL: https://www.relay-api.com。モデル名はURLパスの {model} 部分に指定します（/v1beta/models/{model}:generateContent、Google公式仕様に準拠）。

3. 認証方法

当サイトの他インターフェースと同様に、発行された sk- で始まるキーを使用します：

Authorization: Bearer sk-あなたのキー

また、x-api-key ヘッダー、および Google 公式の x-goog-api-key: sk-あなたのキー ヘッダーにも対応しています。

4. クイックスタート (curl)

4.1 非ストリーミング

curl -X POST https://www.relay-api.com/v1beta/models/gemini-3.7-flash:generateContent \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-あなたのキー" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [{"text": "Gemini APIについて一言で説明して"}]
      }
    ],
    "generationConfig": {
      "temperature": 0.7,
      "maxOutputTokens": 512
    }
  }'

4.2 システムプロンプトの使用 (systemInstruction)

curl -X POST https://www.relay-api.com/v1beta/models/gemini-3.7-flash:generateContent \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk-あなたのキー" \
  -d '{
    "model": "gemini-3.5-flash",
    "systemInstruction": {
      "parts": [{"text": "あなたは熟練のAPIエンジニアです。簡潔に回答してください。"}]
    },
    "contents": [
      {"role": "user", "parts": [{"text": "ストリーミングと非ストリーミングの使い分け方は？"}]}
    ]
  }'

5. リクエストパラメータ

フィールド	型	必須	説明
model	string	はい	モデル名（slug）、例：gemini-3.7-flash
contents	array	はい	会話内容、要素は {role, parts[]}；role は user または model
contents[].parts	array	はい	内容ブロック、通常は {text}
systemInstruction	object	いいえ	システムプロンプト、構造は {parts: [{text}]}
generationConfig.temperature	number	いいえ	サンプリング温度、デフォルト 1.0
generationConfig.topP	number	いいえ	コアサンプリング
generationConfig.topK	int	いいえ	Top-K サンプリング
generationConfig.maxOutputTokens	int	いいえ	最大出力トークン数
generationConfig.stopSequences	array	いいえ	停止シーケンス
stream	bool	いいえ	ストリーミングの有無、デフォルト false

6. レスポンス構造

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [{"text": "Gemini APIはテキスト、マルチモーダル入力、ストリーミング出力をサポートしています。"}]
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 16,
    "candidatesTokenCount": 20,
    "totalTokenCount": 36
  }
}

フィールド	説明
candidates[].content.parts[].text	モデルが生成したテキスト
candidates[].finishReason	終了理由：STOP / MAX_TOKENS / SAFETY / RECITATION
usageMetadata.promptTokenCount	入力トークン数（課金対象）
usageMetadata.candidatesTokenCount	出力トークン数（課金対象）
usageMetadata.totalTokenCount	合計トークン数

7. ストリーミング出力

リクエストボディに "stream": true を含めると、サーバーは SSE 形式で逐次データを返します：

data: {"candidates": [{"content": {"parts": [{"text": "Gemini"}]}, "index": 0}]}

data: {"candidates": [{"content": {"parts": [{"text": " APIはストリーミング"}]}, "index": 0}]}

data: {"candidates": [{"content": {"parts": [{"text": "対応です。"}]}, "index": 0, "finishReason": "STOP"}]}

クライアント側で各 data: 行をパースし、candidates[0].content.parts[0].text を結合してください。最後のチャンクの finishReason が STOP になれば生成完了です。

8. エラーコード一覧

HTTP ステータス	意味	対処法
400	リクエスト形式エラー	リクエストボディとモデル名を確認
401	APIキー無効または不足	Authorization / x-api-key ヘッダーを確認
403	キー停止、残高不足、または権限外	チャージまたは権限を確認
404	モデルまたはエンドポイント未存在	モデルのslugを確認
429	リクエスト過多	少し時間を置いて再試行
500	サーバー内部エラー	後ほど再試行、解決しない場合はサポートへ連絡

エラーレスポンスは {"code": ステータスコード, "message": "エラー内容", "data": null} 形式で返されます。

9. 互換性について

• Google GenAI SDK (google-genai) はカスタムエンドポイント設定により接続可能です。
• generateContent をターゲットとするあらゆる Gemini 互換クライアントをサポートしています。
• 利用可能なモデル名は GET /v1/models で返される slug に準じます。