Gemini API 接続ガイド：Google互換呼び出しと超長文コンテキスト

1. 概要

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

現在利用可能な Gemini シリーズのモデルは「モデル広場（Model Marketplace）」に準拠します（例：gemini-3.7-flash、gemini-3.6-flash、gemini-3.5-flash、gemini-3.5-flash-lite など）。モデルの詳細リストと単価は GET /v1/models から取得できます。

2. APIエンドポイント

メソッド	パス	説明
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（/v1beta/models/{model}:generateContent、Google公式仕様に準拠）に組み込みます。リクエストボディは generateContent ペイロードです。

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	はい	モデルスラグ（例: 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	リクエスト形式エラー（contentsの欠如、モデル非存在など）	リクエストボディとモデル名を確認
401	APIキーが無効または未入力	Authorization / x-api-key ヘッダーを確認
403	キーの停止、残高不足、または該当モデルへのアクセス権なし	チャージまたは権限を確認
404	モデルまたはエンドポイントが存在しません	モデルスラグを確認
429	リクエスト過多	バックオフして再試行
500	内部サーバーエラー	しばらく待ってから再試行。改善しない場合はサポートへ連絡

エラーレスポンスの本体は、常に {"code": ステータスコード, "message": "エラー内容", "data": null} という構造になっています。

9. 互換性について

• Google GenAI SDK（google-genai）は、カスタムエンドポイントを指定することで接続可能です。
• generateContent をターゲットとするあらゆる Gemini 互換クライアントをサポートしています。
• モデル名は GET /v1/models が返すスラグを使用してください。

Base URL について：当サイトは /v1beta/models/... と /v1beta/v1beta/models/...（および /v1/... と /v1/v1/...）の両方を受け付けるため、クライアント側で /v1 や /v1beta を自動付与するかどうかは問いません。ドメインのルートURL、または /v1beta を含むURLのどちらでも利用可能です。モデルIDは、管理コンソールの「トークン」ページ右上にある「モデルID」からコピーしてください。