
Gemini 4 Carbon APIは、Googleが最も難しいコーディング作業向けに位置づけるモデルです。Googleはこれをマルチステップのデバッグと長期のエージェント型コーディングのために構築し、探索、推論、検証ループの実行にArgonより多くのトークンを使うとしています。このガイドでは、PoYoのOpenAI互換エンドポイントを通じて gemini-4-carbon(モデルページ)をコーディングエージェントに組み込みます。このエージェントは出力をストリーミングし、リポジトリの大きな部分を読み込み、ターン数と金額の厳格な上限で停止し、作業をArgonに渡すべきタイミングを判断します。
まだ最初のリクエストを送っていない場合は、Gemini 4 Carbon APIガイドから始めてください。
APIがコーディングエージェントに提供するもの
| 項目 | PoYoのGemini 4 Carbon |
|---|---|
| モデルID | gemini-4-carbon |
| ここで使うエージェント用エンドポイント | POST https://api.poyo.ai/v1/chat/completions(OpenAI SDK、base_url="https://api.poyo.ai/v1") |
| ネイティブの代替 | POST /v1beta/models/gemini-4-carbon:generateContent と :streamGenerateContent |
| コンテキストウィンドウ | 100万トークン:テキスト、画像、音声、動画、PDF |
| 1レスポンスあたりの最大出力 | 64Kトークン |
| ストリーミング | "stream": true。最後のチャンクに finish_reason と usage が含まれる |
| 料金 | 100万トークンあたり入力$1.60 / 出力$8.00 / キャッシュ読み取り$0.08(320 / 1,600 / 16クレジット) |
| レート制限 | PoYoのドキュメントによれば、LLMエンドポイントには現在レート制限がない |
| エラー | 400 不正なフィールド、401 キーの誤り、402 クレジット不足、404 不明なモデル。429 / 500 / 502 / 503 はバックオフ付きで再試行 |
Chat Completionsのドキュメントに記載されているリクエストフィールドは、model、messages(system、user、assistant のロールを持つ文字列の content)、max_tokens、stream、temperature、top_p、stop、n、およびペナルティ関連のフィールドです。以下のエージェントはこれらだけを使います。
ツール呼び出し:現在ドキュメント化されている範囲
PoYoはAnthropic MessagesとResponsesについて tools をドキュメント化しています。Geminiモデルについては、Chat CompletionsでもGemini Nativeでも、tools や関数宣言はドキュメント化されていません。gemini-4-carbon ではResponsesは利用できません。
そのため、このエージェントは tools 配列を送りません。代わりに、通常のメッセージ内容の中でJSONアクションプロトコルを使います。システムプロンプトで許可するアクションを列挙し、モデルは1ターンにつき1つのJSONオブジェクトで応答します。コードがそのアクションを実行し、結果を次のuserメッセージとして返します。この方法はどのチャットモデルでも機能します。PoYoがGeminiのネイティブな関数呼び出しをドキュメント化したら、パーサーを本物のツール呼び出しに置き換え、ループの残りはそのまま使えます。
安全面の利点もあります。モデルが要求できるのは、自分で書いた4つのアクションだけです。任意のシェルコマンドは実行できません。
長いコンテキストでのリポジトリ入力:入力1M、出力64K
1Mトークンのウィンドウがあれば、ファイルを1つずつ取得する代わりに、最初のターンでリポジトリの大部分を送れます。Googleの発表時の表は、それを使う理由を示しています。256K〜1MトークンのGraphWalksで、Carbonは96.2%、Argonは84.2%です。ループの設計には3つの制約が関わります。
- 毎ターン、履歴全体が再送されます。 スナップショットは呼び出しごとに再び課金されます。300Kトークンのスナップショットを12ターン送ると少なくとも360万入力トークンになり、出力を除いても100万トークンあたり$1.60で$5.76です。
- 出力は1レスポンスあたり64Kが上限です。 1回の応答でリポジトリ全体を書き換えさせるのではなく、
write_fileアクションごとに1ファイルを要求してください。 - トークン数は推測せず測定してください。 PoYoにはトークナイザーのエンドポイントがドキュメント化されていません。最初の呼び出しの
usage.prompt_tokensを読み取り、目標とするトークン予算に合わせてMAX_SNAPSHOT_CHARSを調整します。
キャッシュ。 PoYoの料金表にはCarbonのキャッシュ読み取り料金(新規入力の$1.60に対し100万トークンあたり$0.08)があり、Googleはキャッシュされた入力を95%オフにしています。PoYoのドキュメントには、Geminiモデル向けのキャッシュ用リクエストパラメーターや、キャッシュされたトークンのusageフィールドは記載されていません。このループはキャッシュ用のパラメーターを送らず、すべてのプロンプトトークンを通常の入力料金で予算計上します。システムプロンプトとスナップショットを変わらないプレフィックスとして保つことに費用はかからず、キャッシュ料金で課金された読み取りがあったかどうかは請求書で確認できます。
Pythonでの上限ありエージェントループ
import json
import os
import subprocess
import time
from pathlib import Path
from openai import OpenAI, APIStatusError
client = OpenAI(api_key=os.environ["POYO_API_KEY"], base_url="https://api.poyo.ai/v1")
CARBON, ARGON = "gemini-4-carbon", "gemini-4-argon"
PRICE_IN, PRICE_OUT = 1.60, 8.00 # PoYo USD per 1M tokens, same for both (2026-11-16)
MAX_TURNS = 12
BUDGET_USD = 2.00
MAX_TOKENS_PER_TURN = 16_000 # Carbon allows up to 64,000
MAX_SNAPSHOT_CHARS = 400_000 # tune against usage.prompt_tokens
MAX_RESULT_CHARS = 20_000
REPO = Path("./my-repo").resolve()
SYSTEM = """You are a coding agent working in a Python repository.
Reply with exactly one JSON object and nothing else. Allowed actions:
{"action": "read_file", "path": "<relative path>"}
{"action": "write_file", "path": "<relative path>", "content": "<full file content>"}
{"action": "run_tests"}
{"action": "done", "summary": "<what changed and why>"}"""
def snapshot() -> str:
parts, total = [], 0
for p in sorted(REPO.rglob("*.py")):
block = f"### {p.relative_to(REPO)}\n{p.read_text(encoding='utf-8', errors='replace')}\n"
if total + len(block) > MAX_SNAPSHOT_CHARS:
break
parts.append(block)
total += len(block)
return "".join(parts)
def safe_path(rel: str) -> Path:
p = (REPO / rel).resolve()
if not p.is_relative_to(REPO):
raise ValueError("path outside repository")
return p
def execute(action: dict) -> str:
kind = action.get("action")
if kind == "read_file":
return safe_path(action["path"]).read_text(encoding="utf-8", errors="replace")
if kind == "write_file":
safe_path(action["path"]).write_text(action["content"], encoding="utf-8")
return "written"
if kind == "run_tests":
r = subprocess.run(["pytest", "-q"], cwd=REPO, capture_output=True, text=True, timeout=600)
return f"exit={r.returncode}\n{r.stdout}\n{r.stderr}"
raise ValueError(f"unknown action {kind!r}")
def call(model: str, messages: list):
"""One streamed turn. Returns (text, usage, finish_reason)."""
for attempt in range(4):
try:
stream = client.chat.completions.create(
model=model, messages=messages, max_tokens=MAX_TOKENS_PER_TURN, stream=True
)
text, usage, finish = [], None, None
for chunk in stream:
if chunk.choices:
choice = chunk.choices[0]
if choice.delta and choice.delta.content:
text.append(choice.delta.content)
print(choice.delta.content, end="", flush=True)
finish = choice.finish_reason or finish
if getattr(chunk, "usage", None):
usage = chunk.usage
return "".join(text), usage, finish
except APIStatusError as e:
if e.status_code in (429, 500, 502, 503) and attempt < 3:
time.sleep(2 ** attempt)
continue
raise # 400, 401, 402, 404: fix the request or the account, don't retry
def parse(text: str) -> dict:
t = text.strip()
if t.startswith("```"):
t = t.strip("`").removeprefix("json").strip()
return json.loads(t)
def run_agent(task: str, model: str = CARBON) -> dict:
messages = [
{"role": "system", "content": SYSTEM},
{"role": "user", "content": f"Repository snapshot:\n{snapshot()}\n\nTask: {task}"},
]
spent, last_prompt = 0.0, 0
for turn in range(1, MAX_TURNS + 1):
# Worst case for the next turn: at least last turn's input plus a full output
worst_next = last_prompt / 1e6 * PRICE_IN + MAX_TOKENS_PER_TURN / 1e6 * PRICE_OUT
if spent + worst_next > BUDGET_USD:
return {"status": "budget_stop", "turns": turn - 1, "spent_usd": round(spent, 4)}
text, usage, finish = call(model, messages)
if usage is None:
raise RuntimeError("no usage in stream; stopping so the budget stays enforceable")
spent += usage.prompt_tokens / 1e6 * PRICE_IN + usage.completion_tokens / 1e6 * PRICE_OUT
last_prompt = usage.prompt_tokens
messages.append({"role": "assistant", "content": text})
if finish == "length":
messages.append({"role": "user", "content": "Reply was cut off. Send one shorter JSON action."})
continue
try:
action = parse(text)
except json.JSONDecodeError:
messages.append({"role": "user", "content": "Reply with exactly one JSON object."})
continue
if action.get("action") == "done":
return {"status": "done", "summary": action.get("summary"), "turns": turn, "spent_usd": round(spent, 4)}
try:
result = execute(action)
except Exception as e: # report the failure to the model instead of crashing
result = f"error: {e}"
messages.append({"role": "user", "content": f"Result of {action.get('action')}:\n{result[:MAX_RESULT_CHARS]}"})
return {"status": "max_turns", "turns": MAX_TURNS, "spent_usd": round(spent, 4)}
if __name__ == "__main__":
print(run_agent("tests/test_parser.py::test_unicode fails. Find the root cause and fix it."))
Path.is_relative_to にはPython 3.9以降が必要です。write_file はファイルを上書きするため、エージェントはリポジトリのコピーかブランチに対して実行してください。
費用ガードの仕組み
| ガード | 防ぐもの | 数値の出どころ |
|---|---|---|
MAX_TURNS | done を呼ばずに続くループ | 任意に設定。12は出発点 |
BUDGET_USD と最悪ケースのチェック | 次の呼び出しで上限を超える支出 | ストリームの最後のチャンクの usage.prompt_tokens と usage.completion_tokens(PoYoの$1.60 / $8.00で計算) |
MAX_TOKENS_PER_TURN | 暴走した1回の応答 | max_tokens。Carbonでは最大64,000 |
MAX_RESULT_CHARS | 巨大なテストログによるその後の全ターンの肥大化 | 結果を履歴に入れる前に切り詰める |
usage is None → 停止 | 測定できない見えない支出 | PoYoはストリームの最後のチャンクに usage があるとドキュメント化している |
402 は再試行しない | 残高ゼロでの再試行の嵐 | PoYoのエラーコード |
GoogleはCarbonの出力を思考トークン込みで課金するため、1ターンで表示されたJSONより多くの出力が課金されることがあります。そのため予算計算では completion_tokens を使い、受信した文字数は決して数えません。この見積もりはすべての入力をキャッシュなしとして数えているので、PoYoが課金する額の上限値になります。最初の数回の実行では、ダッシュボードと照合してください。
最悪ケースのチェックは保守的です。履歴が300Kトークンの場合、もう1ターン実行すると少なくとも入力で$0.48、加えて max_tokens が16Kなら最大$0.128の出力がかかります。予算が$2.00なら、ループは上限を超えうる呼び出しの前に停止します。
Gemini 4 Argonにフォールバックすべき場面
Argonは同じリクエストを受け付け、入力・出力トークンの単価も同じです。Googleはこれを「大半のソフトウェアエンジニアリングとナレッジワークに最適な選択肢」と呼び、応答が速くターンあたりのトークン消費が少ないとしています。次の場合は run_agent(task, model=ARGON) でArgonに振り分けてください。
- タスクが定型的な場合。 小さな修正、単一ファイルの変更、テストの作成には、Carbonの追加の検証トークンは必要ありません。
- 1つのレスポンスが64Kトークンを超える必要がある場合。 Carbonの出力上限は64Kです。Argonのはるかに大きな出力上限についてはArgonガイドで解説しています。
- 安価な最初の試行が欲しい場合。 まずArgonを実行し、テストがまだ失敗する場合にだけCarbonにエスカレーションします。Gemini 4 Carbon API vs Gemini 4 Argon APIのルーターがこれを行います。
Carbonは、リポジトリ全体にわたる根本原因の特定と、ターミナルを多用するループに使ってください。Googleの表では、Terminal-Bench 4.0 (AA)でCarbonは65.2%(Argonは57.1%)、SWE-sweepでは9.6%(同4.3%)です。Googleの提供開始の記事も役割分担を提案しています。設計、調整、監査の役割にはCarbonを使い、並列作業には高速で軽量なモデルを組み合わせる方法です。このループで言えば、Carbonのプランナーを1回実行してArgonのワーカーにファイルを割り当てることになります。
両モデルの予算はGemini 4 Carbon APIの料金記事にあります。エージェントに他社のモデルも検討している場合は、Gemini 4 Carbon API vs Claude Opus 5.5 API vs GPT-6 Astra APIを参照してください。
よくある質問
PoYoのGemini 4 Carbon APIは関数呼び出しに対応していますか?
PoYoの現在のドキュメントでは、Chat CompletionsとGemini NativeのいずれでもGeminiモデルの tools や関数宣言はドキュメント化されていません。ツールがドキュメント化されているのはAnthropic MessagesとResponsesです。このガイドでは、ドキュメント化されたフィールドだけで済む、メッセージ内容でのJSONアクションプロトコルを使っています。
Gemini 4 Carbon APIでOpenAI Python SDKを使えますか?
はい。OpenAI(api_key=..., base_url="https://api.poyo.ai/v1") を作成し、chat.completions.create に model="gemini-4-carbon" を渡します。ストリーミングは stream=True で動作し、最後のチャンクに usage が含まれます。
Gemini 4 Carbon APIの最大出力とコンテキストウィンドウは?
コンテキストは100万トークン、出力は1レスポンスあたり最大64Kトークンです。max_tokens は64,000以下に設定してください。
エージェントループでGemini 4 Carbon APIの費用を抑えるには?
ターン数を制限し、ターンごとの max_tokens を制限し、ツールの結果を切り詰め、これまでの支出に最悪ケースの次のターンを加えると予算を超える場合は停止します。支出は、PoYoの100万トークンあたりの料金で usage.prompt_tokens × $1.60 と usage.completion_tokens × $8.00 から計算します。
Gemini 4 Carbon APIはコンテキストキャッシュに対応していますか?
PoYoはCarbonのキャッシュ読み取り料金を100万トークンあたり$0.08(16クレジット)と掲載しています。ドキュメントには現在、Geminiモデル向けのキャッシュ用リクエストパラメーターやキャッシュされたトークンのusageフィールドが記載されていないため、プロンプトは通常の入力料金で予算計上し、キャッシュ料金での課金があるかどうかは請求書で確認してください。
コーディングエージェントでCarbonではなくGemini 4 Argonを使うべきなのはどんなときですか?
定型的なコーディング、64Kトークンを超える必要がある単一レスポンス、そしてCarbonにエスカレーションする前の安価な最初の試行にはArgonを使ってください。PoYoではどちらも100万トークンあたり$1.60 / $8.00ですが、GoogleによればArgonはターンあたりのトークン消費が少なくなります。