
Gemini 4 Carbon API — выбор Google для самых сложных задач разработки. Google создала модель для многошаговой отладки и агентной разработки с длинным горизонтом и говорит, что она тратит больше токенов, чем Argon, на исследование, рассуждение и циклы проверки. Это руководство подключает gemini-4-carbon (страница модели) к агенту разработки через OpenAI-совместимый эндпоинт PoYo. Агент стримит вывод, может прочитать большой фрагмент репозитория, останавливается по жёсткому лимиту ходов и бюджета в долларах и знает, когда передать работу Argon.
Если вы ещё не отправляли первый запрос, начните с руководства по Gemini 4 Carbon API.
Что API даёт агенту разработки
| Параметр | Gemini 4 Carbon в PoYo |
|---|---|
| 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 |
| Контекстное окно | 1M токенов: текст, изображения, аудио, видео, PDF |
| Максимальный вывод на ответ | 64K токенов |
| Стриминг | "stream": true; последний чанк содержит finish_reason и usage |
| Цена | $1.60 за вход / $8.00 за выход / $0.08 за чтение из кэша за 1M токенов (320 / 1,600 / 16 кредитов) |
| Ограничения частоты | В документации PoYo сказано, что LLM-эндпоинты сейчас не ограничены по частоте |
| Ошибки | 400 некорректные поля, 401 неверный ключ, 402 недостаточно кредитов, 404 неизвестная модель; 429 / 500 / 502 / 503 повторяйте с задержкой |
Документация Chat Completions описывает такие поля запроса: model, messages (строковый content с ролями system, user или assistant), max_tokens, stream, temperature, top_p, stop, n и поля штрафов. Агент ниже использует только их.
Вызов инструментов: что задокументировано сейчас
PoYo документирует tools для Anthropic Messages и для Responses. Для моделей Gemini tools и объявления функций не задокументированы ни в Chat Completions, ни в Gemini Native. Responses для gemini-4-carbon недоступен.
Поэтому этот агент не отправляет массив tools. Вместо этого он использует протокол JSON-действий в обычном содержимом сообщений. Системный промпт перечисляет допустимые действия, модель отвечает одним JSON-объектом за ход, а ваш код выполняет это действие и отправляет результат обратно следующим сообщением пользователя. Это работает с любой чат-моделью. Когда PoYo задокументирует нативный вызов функций для Gemini, вы сможете заменить парсер на настоящие вызовы инструментов и оставить остальной цикл как есть.
Есть и выигрыш в безопасности: модель может запросить только четыре действия, которые вы написали сами. Произвольную команду оболочки она выполнить не может.
Репозиторий в длинном контексте: 1M на входе, 64K на выходе
Окно в 1M токенов позволяет отправить большую часть репозитория уже на первом ходу, а не получать файлы по одному. В таблице Google к запуску есть повод этим воспользоваться: Carbon набирает 96.2% на GraphWalks при 256K–1M токенов против 84.2% у Argon. Цикл определяют три ограничения:
- Каждый ход заново отправляет всю историю. Снимок оплачивается при каждом вызове заново. Снимок на 300K токенов за 12 ходов — это минимум 3.6M входных токенов, то есть $5.76 при $1.60 за 1M ещё до какого-либо вывода.
- Вывод ограничен 64K на ответ. Просите один файл на действие
write_file, а не переписывание всего репозитория в одном ответе. - Измеряйте число токенов, а не угадывайте. В PoYo не задокументирован эндпоинт токенизатора. Возьмите
usage.prompt_tokensиз первого вызова, а затем подстройтеMAX_SNAPSHOT_CHARSпод нужный бюджет токенов.
Кэширование. В таблице цен PoYo есть ставка чтения из кэша для Carbon ($0.08 за 1M против $1.60 за новый вход), а Google оценивает кэшированный вход со скидкой 95%. В документации PoYo не описаны ни параметр запроса для кэширования, ни поле usage с кэшированными токенами для моделей Gemini. Этот цикл не отправляет параметров кэширования и закладывает в бюджет каждый токен промпта по полной ставке входа. Сохранение системного промпта и снимка неизменным префиксом ничего не стоит, а ваш счёт покажет, были ли какие-то чтения оплачены по ставке кэша.
Ограниченный агентный цикл на 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 | Один неуправляемый ответ | max_tokens, для Carbon не больше 64,000 |
MAX_RESULT_CHARS | Огромные логи тестов, раздувающие все последующие ходы | Обрезка до того, как результат попадёт в историю |
usage is None → остановка | Скрытые расходы, которые невозможно измерить | PoYo документирует usage в последнем чанке стрима |
402 не повторяется | Лавина повторов при нулевом балансе | Коды ошибок PoYo |
Google тарифицирует вывод Carbon вместе с токенами мышления, поэтому ход может стоить больше выходных токенов, чем видно в JSON. Именно поэтому бюджет опирается на completion_tokens и никогда не считает полученные символы. Оценка считает весь вход некэшированным, так что это оценка сверху того, что выставит PoYo. Сверьте её со своей панелью на первых нескольких запусках.
Проверка худшего случая консервативна. При истории на 300K токенов ещё один ход стоит минимум $0.48 за вход плюс до $0.128 за вывод при max_tokens 16K. При бюджете $2.00 цикл останавливается перед вызовом, который мог бы превысить лимит.
Когда переходить на Gemini 4 Argon
Argon принимает тот же запрос и стоит столько же за входной и выходной токен. Google называет её «идеальным выбором для большинства задач разработки ПО и работы со знаниями» с более быстрыми ответами и меньшим расходом токенов на ход. Направляйте в неё работу через run_agent(task, model=ARGON), когда:
- Задача рутинная. Мелким исправлениям, изменениям в одном файле и написанию тестов дополнительные токены проверки Carbon не нужны.
- Один ответ должен превышать 64K токенов. Carbon ограничивает вывод 64K. Гораздо больший лимит вывода Argon описан в нашем руководстве по Argon.
- Нужна дешёвая первая попытка. Сначала запустите Argon и эскалируйте в Carbon, только если тесты всё ещё падают. Именно так работает маршрутизатор из статьи Gemini 4 Carbon API vs Gemini 4 Argon API.
Оставьте Carbon для поиска первопричин на уровне всего репозитория и циклов с интенсивной работой в терминале. В таблице Google Carbon набирает 65.2% на Terminal-Bench 4.0 (AA) против 57.1% у Argon и 9.6% на SWE-sweep против 4.3%. В посте Google о доступности также предлагается разделение: Carbon — для ролей архитектуры, координации и аудита, в паре с более быстрыми и лёгкими моделями для параллельной работы. В этом цикле это означает один запуск планировщика на Carbon, который распределяет файлы между исполнителями на Argon.
Бюджеты для обеих моделей — в статье о ценах Gemini 4 Carbon API. Если для агента вы рассматриваете других вендоров, см. Gemini 4 Carbon API vs Claude Opus 5.5 API vs GPT-6 Astra API.
Часто задаваемые вопросы
Поддерживает ли Gemini 4 Carbon API вызов функций в PoYo?
В текущей документации PoYo tools и объявления функций для моделей Gemini не описаны ни в Chat Completions, ни в Gemini Native. Инструменты задокументированы для Anthropic Messages и Responses. В этом руководстве используется протокол JSON-действий в содержимом сообщений, которому нужны только задокументированные поля.
Можно ли использовать OpenAI Python SDK с Gemini 4 Carbon API?
Да. Создайте OpenAI(api_key=..., base_url="https://api.poyo.ai/v1") и передайте model="gemini-4-carbon" в chat.completions.create. Стриминг работает с stream=True, а последний чанк содержит usage.
Какой максимальный вывод и контекстное окно у Gemini 4 Carbon API?
1M токенов контекста и до 64K выходных токенов на ответ. Задавайте max_tokens не больше 64,000.
Как ограничить затраты на Gemini 4 Carbon API в агентном цикле?
Ограничьте число ходов, ограничьте max_tokens на ход, обрезайте результаты инструментов и останавливайтесь, когда уже потраченная сумма плюс худший сценарий следующего хода превысили бы бюджет. Считайте расходы как usage.prompt_tokens × $1.60 и usage.completion_tokens × $8.00 за 1M токенов в PoYo.
Поддерживает ли Gemini 4 Carbon API кэширование контекста?
В PoYo для Carbon указана цена чтения из кэша $0.08 за 1M токенов (16 кредитов). В документации сейчас не описаны ни параметр запроса для кэширования, ни поле usage с кэшированными токенами для моделей Gemini, поэтому закладывайте в бюджет промпты по полной ставке входа и проверяйте в счёте списания по ставке кэша.
Когда агенту разработки использовать Gemini 4 Argon вместо Carbon?
Используйте Argon для рутинной разработки, для любого одиночного ответа длиннее 64K токенов и как более дешёвую первую попытку перед эскалацией в Carbon. Обе стоят $1.60 / $8.00 за 1M токенов в PoYo, но, по словам Google, Argon расходует меньше токенов на ход.