Gemini 4 Carbon APIの使い方：接続設定から初回応答の確認まで

モデルIDは gemini-4-carbon を指定し、Gemini APIの有料プロジェクトを使います。新規連携では、Googleが推奨するInteractions APIから始められます。接続確認の合格条件は、完了したインタラクションから利用可能なテキストを得ることです。HTTP 200だけでは十分ではありません。

Carbonは2026年11月10日に有料APIの開発者向けに公開されました。それ以前の限定アクセスに関する発表だけでは、現在の利用条件を把握できません。本記事は2026年11月13日時点の公式ドキュメントを確認し、プロジェクトとキーの選択から、検査できる応答を保存するところまで説明します。

以下の例はGoogleのネイティブAPIを使用し、Ofoxのエンドポイントは使いません。文書化されたリクエスト形式を確認し、合成データで応答パーサーをテストしましたが、本記事のために有料のCarbonリクエストを実行してはいません。例のプロンプトは読者が実行する確認用であり、性能測定の結果ではありません。モデル選びから始める場合は、Carbon・Hydrogen・Argonの比較を参照してください。

1. キーが正しい有料プロジェクトに属しているか確認する

必要なのは、Gemini APIを利用できるGoogleアカウント、AI StudioからアクセスできるGoogle Cloudプロジェクト、そのプロジェクトのAPIキー、有効なAPI課金設定です。この4つを分けて確認します。GeminiアプリやGoogle AI Ultraの契約だけで、アプリケーションが使用するプロジェクトのAPI課金が設定されるわけではありません。

1. Google AI Studioを開き、使用するプロジェクトを選びます。既存のCloudプロジェクトがある場合は必要に応じてインポートします。キー作成ボタンを表示させるためだけに、無関係なプロジェクトを作らないようにします。
2. そのプロジェクトのAPIキー管理からキーを作成または選択します。デプロイ記録には秘密のキーではなく、プロジェクト名またはIDを残します。ターミナルやサーバーが同じプロジェクトのキーを読み込むことも確認します。
3. AI Studioのプロジェクト課金設定で、同じプロジェクトの有料設定を完了します。アカウントによってPrepay、Prepay/Postpayの選択、移行期間中のPostpayなどの方式があります。Prepayでは最低5米ドル、または現地通貨の相当額の支払いが必要な場合があります。カードの登録だけで利用可能と判断せず、画面に表示される課金状態を確認してください。
4. 課金が有効で、必要な前払い残高が利用できることを確認します。リクエスト前にプロジェクトの割り当てと地域の利用条件も確認してください。有料プロジェクトにも制限があります。

出典はGoogleのAPIキーガイド（英語）と課金ガイド（英語）です。プロジェクトのインポートやキー作成ができない場合は、管理者に必要な権限を確認してもらいます。キーを公開したり、むやみに広い権限を付けたりして解決する問題ではありません。

2026年11月13日に取得した公式の英語画面です。開発者向け公開の確認資料であり、読者のアカウントの課金状態やAPI成功を示す画面ではありません。発表原文（英語）。

既存キーの問題は入力ミスとは限らない

AI Studioで新しく作成するキーは、現在authorization keyが既定です。現行文書では、制限のない standard key は拒否されますが、明示的に制限を設定したstandard keyは引き続き利用できます。古いキーをすべて無効と決めつけず、種類と制限を確認してください。

キーはサーバー側の環境変数かシークレット管理サービスに保存します。ローカルでは GEMINI_API_KEY を設定し、秘密の値をリポジトリにコミットしないようにします。スクリーンショット、問い合わせ、ブラウザーのJavaScriptにも載せません。以下の例は GEMINI_API_KEY を明示的に読み取ります。SDKの自動検出では GOOGLE_API_KEY が優先されるため、古い変数が残って別のプロジェクトを選ぶことを防ぐためです。

値を表示せず、変数が存在することだけを確認できます。

python3 -c 'import os; print("Key configured:", bool(os.environ.get("GEMINI_API_KEY")))'

True は値が設定されているという意味にすぎません。キーの有効性、所属プロジェクト、課金状態は検証しません。次のリクエストでその先を確認します。

2. Pythonで上限を決めた初回リクエストを送る

別のアプリに入っている古いSDKの影響を避けるため、専用環境を作成します。

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade 'google-genai>=2.34.0'
python -m pip show google-genai

Windows PowerShellでは .venv\Scripts\Activate.ps1 で有効化します。パッケージは google-genai、インポートは from google import genai です。旧パッケージの google-generativeai と置き換えないでください。基本的なInteractions対応と、フォアグラウンドでの自動継続に必要な最低バージョンは異なります。上の指定には現在のPythonの自動継続対応が含まれますが、この短いリクエストは単一ホップに収まる設定です。Interactions（英語）と長い出力のガイド（英語）を参照してください。

次を carbon_first_call.py として保存します。

import json
import os
from pathlib import Path
from google import genai

key = os.environ.get("GEMINI_API_KEY")
if not key:
    raise SystemExit("Set GEMINI_API_KEY for the intended paid project.")

client = genai.Client(api_key=key)
interaction = client.interactions.create(
    model="gemini-4-carbon",
    input="Return exactly three checklist items for reviewing an API integration.",
    store=False,
    generation_config={
        "thinking_level": "low",
        "max_output_tokens": 32768,
    },
)

payload = interaction.model_dump(mode="json")
Path("carbon-response.json").write_text(
    json.dumps(payload, indent=2), encoding="utf-8"
)
text = interaction.output_text or ""
print("Interaction:", interaction.id)
print("Status:", interaction.status)
print("Usage:", interaction.usage)
if interaction.status != "completed" or not text.strip():
    raise SystemExit("No completed text result; inspect carbon-response.json.")
print(text)

python carbon_first_call.py を実行します。有料リクエストが送信されます。 最初はPythonかRESTのどちらかを実行し、両方を自動的に連続実行して重複テストにしないでください。32,768トークンは思考と可視出力を合計した上限であり、請求額の予測でも、それだけの文章量を要求する設定でもありません。短いプロンプトと low の組み合わせで、複雑な調査ではなく接続を確認します。

成功時にはインタラクションID、completed、使用量、意味のある3項目のチェックリストが表示されます。状態だけでなく回答も読みます。完了していても、内容や形式の条件を満たさない場合があるためです。JSONは診断資料として保存しますが、後で顧客データを入力する場合は、応答ファイルも機密情報を含む可能性があるものとして扱います。

ここでは単発のリクエストなので store=False を設定しています。後からの取得やサーバー側の会話継続に使うための保存を無効にする指定であり、すべての事業者のログ方針を保証するものではありません。既定値は store=true です。バックグラウンド処理や previous_interaction_id に依存する例に、そのままコピーしないでください。

3. RESTで呼び出し、正しいフィールドからテキストを読む

RESTではクライアントが送る内容を確認しやすくなります。curl と、パーサー用のPython 3を用意し、次の本文を carbon-request.json に保存します。

{
  "model": "gemini-4-carbon",
  "input": "Return exactly three checklist items for reviewing an API integration.",
  "store": false,
  "generation_config": {
    "thinking_level": "low",
    "max_output_tokens": 32768
  }
}

Interactionsエンドポイントに送信します。

curl --silent --show-error --fail-with-body --max-time 900 \
  'https://generativelanguage.googleapis.com/v1beta/interactions' \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @carbon-request.json \
  --output carbon-response.json

サーバーからエラー本文が返った場合も、調査のためにファイルへ保存します。curlの終了コードが0以外なら、転送かHTTPリクエストの問題を調べ、回答を取得できたものとして進めないでください。900秒はクライアントの明示的な制限時間であり、Carbonが毎回15分かかるという意味ではありません。また、クライアントのタイムアウトだけではサーバー処理の停止は確認できません。状況を調べずに、課金される可能性のある処理をすぐ再送しないようにします。

output_text はSDKの便利なプロパティであり、REST応答のフィールドではありません。 RESTでは steps 内の model_output 項目にある text コンテンツを読みます。GenerateContentの candidates や、古い例の outputs を読むパーサーでは、有効な応答を空と誤認することがあります。

応答ファイルの隣に、次を inspect_carbon.py として保存します。

import json
import sys
from pathlib import Path


def extract_text(payload):
    return "".join(
        part.get("text", "")
        for step in payload.get("steps", [])
        if step.get("type") == "model_output"
        for part in step.get("content", [])
        if part.get("type") == "text"
    )


def inspect(path):
    payload = json.loads(Path(path).read_text(encoding="utf-8"))
    if "error" in payload:
        raise SystemExit("API error: " + json.dumps(payload["error"]))
    text = extract_text(payload)
    print("Interaction:", payload.get("id"))
    print("Status:", payload.get("status"))
    print("Usage:", json.dumps(payload.get("usage")))
    if payload.get("status") != "completed" or not text.strip():
        raise SystemExit("No completed text result; inspect the saved response.")
    print(text)


if __name__ == "__main__":
    inspect(sys.argv[1] if len(sys.argv) > 1 else "carbon-response.json")

python3 inspect_carbon.py carbon-response.json を実行します。最初のstepを最終回答と決めつけず、すべてのテキスト部分を結合します。未完了や追加アクションが必要な応答を成功と扱わない設計です。監視にも応用できますが、失敗を無制限の再試行につなげないでください。

このパーサーは、完了、空、エラー、複数stepの合成応答を使ってローカルで確認しました。検証対象は抽出と失敗処理であり、Googleの実APIにおける認証、可用性、遅延、品質を証明するものではありません。

4. 実際の仕事に使う前に設定を理解する

初回は、ツール、大きなファイル、長時間のエージェントループを含めません。接続が確認できてから1つずつ追加します。Carbon開発者ガイド（英語）で確認できる境界は以下のとおりです。

出力上限が小さい既存アプリの移行では、Googleは少なくとも32,768の思考・出力トークンを確保するよう案内しています。これは予算の配分であり、毎回上限まで消費するという意味ではありません。適切なら思考レベルを下げ、回答の長さから料金を推測せず使用量を確認します。料金条件と再計算できる比較はGemini 4の選択ガイドにまとめています。

長時間の処理に拡張する場合

max_output_tokens だけを増やして、他のコードを変えずに済むとは考えないでください。長い出力のガイド（英語）ではフォアグラウンド継続、ストリーミング、バックグラウンド実行を区別しています。新しいSDKはフォアグラウンドの複数ホップをまとめられますが、独自RESTクライアントでは requires_continuation を処理し、必要な継続情報を次のリクエストへ渡します。

バックグラウンド処理では保存を有効にし、IDを記録して、待機時間に上限を設けてポーリングします。queued と in_progress は処理中、completed は結果検証に進める状態です。incomplete、failed、cancelled は別々の終了状態です。requires_action はツールの実行が必要な状態で、最終回答ではありません。予算の増額や background=true は出力の長さを保証しません。本記事の初回呼び出し例は、この別途必要なジョブ制御を実装していません。

サーバー側の会話履歴では、previous_interaction_id が過去の会話を引き継ぎます。ただし tools、system_instruction、generation_config は継承されません。次のターンでも必要なら再送します。Interactionsは既定で応答を保存し、Googleの有料枠では既定の保存期間が55日で、短い期間も設定できます。コピーしたコードの設定をそのまま使うのではなく、意図して選んでください。

5. 失敗した段階から順に調べる

構造化されたエラーを読み、エンドポイント、正確なモデルID、プロジェクト識別子、SDKバージョン、時刻を記録します。キーは含めません。プロンプトや予算を変える前に、最初に失敗した段階を修正します。

Googleのトラブルシューティング（英語）でエラー分類を確認できます。Argon APIのエラー対処も経路、割り当て、応答を切り分ける参考になりますが、Argon固有の内容はCarbonと区別してください。ツール追加後に署名の検証エラーが出た場合は、履歴をむやみに削除せず、missing thought signatureの診断を使って該当するプロトコルの問題を調べます。

既存のGeminiクライアントを移行する

正常に動く基準を残し、変更は1つずつ行います。GoogleのネイティブGenerateContent APIは引き続きサポートされています。新規プロジェクトにInteractionsが推奨されるからといって、動作中のクライアントをすべて直ちに置き換える必要はありません。

移行する場合は、リクエスト形式と応答パーサーを一緒に更新します。モデル名だけを gemini-4-carbon に変え、まだ candidates を読む実装では不十分です。思考レベル、明示的キャッシュ、古いサンプリングの前提を見直し、タイムアウトと出力上限も確認します。JavaScriptのInteractionsでは generation_config、thinking_level、max_output_tokens はsnake_caseです。GenerateContentの設定の大文字・小文字をそのまま持ち込まないでください。

ツールや顧客ファイルを戻す前に、同じ無害な確認用プロンプトを実行します。その後、合格条件が分かっている代表的な仕事を1つ検証します。接続確認の成功だけでは、多段階の本番エージェントの信頼性は証明できません。

この例をOfox経由で使えるか

本記事の発行元はOfoxですが、例はGoogleのネイティブ認証情報とエンドポイントを使っています。2026年11月13日の公開catalogスナップショットにはCarbonの掲載がありませんでした。これは日付付きの観察結果であり、すべてのアカウントや将来の経路で非対応という証明ではありません。Ofox経由のCarbon呼び出しは検証しておらず、Base URLを変えるだけで動作するとも主張しません。

Ofox連携では、正確なモデルの現在の提供状況と対応プロトコルを確認してから、Ofox Gemini APIドキュメントに従ってエンドポイント、認証、リクエストを設定します。OfoxのキーとGoogleのキーは分けます。Gemini互換の経路があることは、GoogleのInteractionsエンドポイントやCarbonの全機能への対応を意味しません。

Ofox経路のエラーは、Ofoxのエラー処理ガイドと実際の応答で調べます。Googleの課金アカウント、Ofox残高、アプリの契約は別物です。一方の残高で他方のリクエストを支払うことはできません。

初回呼び出しの確認記録を残す

設定完了とする前に、秘密を含めず次の証拠を保存します。

• 正確なモデル、エンドポイント、SDKバージョン、プロジェクト識別子。
• インタラクションID、状態、使用量を含む応答。
• 3項目の要求を満たした、抽出済みの可視テキスト。
• そのリクエストの思考レベル、出力予算、保存設定。
• 発生したエラーと、それを解消した具体的な修正。

これでアクセス、プロトコル、出力を切り分ける基準ができます。ツールや大きなプロンプトを追加した際、基準の呼び出しは通るのに新しい処理だけが失敗するなら、変更した部分を調べます。キーの再作成、課金プロジェクトの変更、エージェント全体の再実行を繰り返す必要はありません。