EvoLinkでGemini 3.8 Flashを使う方法：本番導入ガイド

クイックスタート

curl https://direct.evolink.ai/v1/chat/completions \
  -H "Authorization: Bearer $EVOLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "messages": [
      {"role": "user", "content": "Return three rollout risks for an AI API migration."}
    ],
    "max_tokens": 500
  }'

必要なもの

• EvoLinkのアカウントと、環境変数に保存したAPIキー。ソース管理にコミットしないこと。
• HTTPSでJSONリクエストを送れるクライアント、またはカスタムbase_urlを設定できるOpenAI互換SDK。
• 小規模で代表的な評価セットと、測定可能な受け入れルール。
• モデルID、ステータス、レイテンシ、トークン使用量、リトライ、アプリケーション側の採用可否を記録するログ。
• ロールアウト期間中のフォールバックモデル。例えばGemini 3.7 Flash。

Gemini 3.8 Flashはテキスト、画像、動画、音声、PDFの入力を受け付け、テキストを返します。Googleは入力コンテキスト1,048,576トークン、最大出力65,536トークンと公表しています。これらの上限は容量であって、すべてのリクエストを埋める理由ではありません。

APIサーフェスを選ぶ

EvoLinkはGeminiワークロード向けに、2つの実用的なリクエスト形式を提供しています。

OpenAI互換のPython例

OpenAIのPythonパッケージをインストールし、EvoLinkに向けます。

pip install openai

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["EVOLINK_API_KEY"],
    base_url="https://direct.evolink.ai/v1",
)

response = client.chat.completions.create(
    model="gemini-3.8-flash",
    messages=[
        {
            "role": "system",
            "content": "Answer with concise, testable recommendations.",
        },
        {
            "role": "user",
            "content": "Review this deployment plan and identify missing rollback gates.",
        },
    ],
    max_tokens=800,
)

print(response.choices[0].message.content)

最初のリクエストはシンプルに保ってください。ツール、ロングコンテキスト、ストリーミングを追加する前に、認証、ルートへのアクセス、レスポンスのパース、usageフィールドを確認します。

Geminiネイティブのリクエスト例

curl "https://direct.evolink.ai/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "Authorization: Bearer $EVOLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{"text": "Create a five-step canary checklist for this API release."}]
    }],
    "generationConfig": {
      "maxOutputTokens": 800,
      "thinkingConfig": {"thinkingLevel": "medium"}
    }
  }'

Thinking levelと移行ルール

古いGeminiクライアントを移行する場合は、以下を監査してください。

HTTP 200が返るだけでは不十分です。移行後に、構造化出力、tool引数、マルチターンの状態、拒否時の挙動を再検証してください。

コンテキストを浪費しないマルチモーダル入力

このモデルはテキスト、画像、動画、音声、PDFを理解できますが、1Mトークンのウィンドウがあるからといって、大きなペイロードがすべて有用になるわけではありません。コンテキストは意図的に構築してください。

• 判断に必要なドキュメントのセクションやメディアのセグメントだけを含める。
• 安定したsystem instruction、リポジトリのガイダンス、ツールスキーマは一貫したプレフィックスに置き、キャッシュが効く余地を作る。
• アーカイブ全体を添付する前に、関連する証拠を検索して取り出す。
• タスクに見合った出力バジェットを設定する。65,536トークンの最大値はあくまで上限です。
• 入力トークンとキャッシュ読み取りトークンを別々に記録し、「ロングコンテキスト」が避けられる支出を隠さないようにする。

繰り返し使う長いドキュメントでは、安定したプロンプトプレフィックスに対するキャッシュヒットの挙動を比較してください。Googleの導入価格でのキャッシュ読み取り単価は2026年12月31日まで100万トークンあたり$0.075ですが、EvoLinkでの請求はご自身のライブアカウントで確認する必要があります。

本番ロールアウトの5段階

1. アクセスと価格を確認する

権限を絞ったテスト用キーを作成し、アカウントで利用可能なルートにモデルが表示されることを確認し、小さなリクエストを送り、その結果のusageまたは請求レコードを確認します。公開されているモデルページが裏付けるのは提供の意図であって、アカウント固有の呼び出し経路ではありません。

2. リクエスト契約を検証する

まず同期リクエストをテストします。次にストリーミング、構造化出力、ツール、ロングコンテキスト、マルチモーダル入力を、それぞれ別のケースとしてテストします。こうすることで、プロトコルの失敗とモデル品質の失敗を切り分けられます。

3. 固定した評価セットをリプレイする

同じthinking levelで、3.8 Flashと現行のベースラインを比較します。初回成功率、採用された成果物、出力トークンとthinkingトークン、キャッシュヒット、有効なtool call、レイテンシ、人手修正、フォールバック率を測定します。

4. 観測可能なトラフィックでカナリアを流す

小さな割合、またはリスクの低いワークロード種別から始めます。選択したモデルIDと評価コホートをすべてのトレースに付与します。HTTPの成功率の集計だけを根拠にした自動昇格は避けてください。

5. 文書化したゲートで昇格またはロールバックする

事前に定めた品質・コスト・レイテンシの閾値をクリアした場合にのみ昇格します。重大エラー、採用タスク1件あたりのコスト、レイテンシのいずれかが上限を超えたら、以前のモデル値に戻してロールバックします。

本番に必要なエラーハンドリング

レート制限、上流の利用不可、トランスポートのタイムアウトといった一時的な失敗に限り、上限付きのリトライを使います。不正なペイロードや非対応のパラメータを、そのままリトライしてはいけません。

推奨する挙動：

• 一時的な失敗は、指数バックオフとジッターを付けてリトライする。
• 最大試行回数とエンドツーエンドの期限を設定する。
• アプリケーションが副作用を生み得る箇所では、冪等性の戦略を再利用する。
• リクエストIDとサニタイズ済みのエラーボディを記録する。APIキーや機微なプロンプトは絶対に記録しない。
• 期限またはエラー閾値に達したら、テスト済みのフォールバックへルーティングする。
• 400系エラーの繰り返しは、待てば解消する容量問題ではなく、修正すべき契約の問題として扱う。

可観測性チェックリスト

すべてのリクエストで以下を記録します。

• アプリケーションの機能と評価コホート
• リクエストしたモデルIDと実際に提供されたモデルID
• プロトコルとエンドポイントのファミリー
• thinking levelと出力上限
• 返される場合は入力・出力・thinking・キャッシュ読み取りの各トークン
• レイテンシ、ステータス、エラー種別、リトライ回数
• tool callの妥当性またはスキーマ検証の結果
• アプリケーションでの採用可否、レビュアーによる修正、フォールバックの結果

このデータがあることで、統合APIゲートウェイは不透明なプロキシではなく、モデル選択を支える基盤になります。複数のGeminiルートを1つのクライアントの裏側に置きながら、どのルートが価値を生んでいるかを把握できます。

よくある設定ミス

• モデルIDとしてgemini-3.8-flashではなくgemini-3-8-flashを送る。
• OpenAI互換エンドポイントでGeminiネイティブのcontentsを使う。
• minimalが暗黙にlowへダウングレードされることに依存する、thinkingBudgetとthinkingLevelを併用する、無視されるサンプリング制御に依存する、roleがmodelのメッセージで会話を終える。
• 検索や関連性フィルタなしにコンテキストウィンドウを埋める。
• Googleの公開単価がEvoLinkアカウントのライブ単価と同一だと想定する。
• レスポンスの形式と請求を確認せず、1回のHTTP 200で成功と宣言する。
• 測定済みのフォールバック経路なしに本番デフォルトを切り替える。

FAQ

Gemini 3.8 FlashのモデルIDは何ですか？

EvoLinkのどのエンドポイントを使うべきですか？

OpenAIのPython SDKは使えますか？

thinking levelはどれから始めるべきですか？

Gemini 3.8 Flashは画像、動画、音声、PDFに対応していますか？

はい、入力モダリティとして対応しています。出力はテキストで、画像・音声・ライブストリームの生成は提供していません。

3.8 Flashは3.7 Flashより安いですか？

Googleの導入価格期間中は、料金表の上では安くありません。入力、出力、キャッシュ読み取りの単価は同一です。Googleは3.8がより多くのトークンを使うと説明しているため、採用タスク1件あたりの総コストで比較してください。

連携が本番対応できていることをどう確認しますか？

呼び出しの成功とその請求レコードを確認し、使用する各プロトコル機能をテストし、固定した評価セットをリプレイし、実トラフィックでカナリアを流し、明示的なロールバックを保持してください。

すべてのGeminiルートを比較するにはどこを見ればよいですか？

出典と検証メモ

• Google：Gemini 3.8 Flash 発表
• Google AI for Developers：Gemini 3.8 Flash モデル
• Google AI for Developers：Gemini API 料金
• Google Cloud：Gemini 3.8 Flash ガイダンス
• EvoLink：Gemini ネイティブ API クイックスタート
• EvoLink：Gemini ネイティブ API リファレンス
• EvoLink：Gemini OpenAI 互換クイックスタート