Как подключить Gemini 4 Carbon API и проверить первый ответ

Укажите точный ID gemini-4-carbon и используйте проект с платным доступом к Gemini API. Для новой интеграции Google рекомендует Interactions API. Проверка считается успешной, когда взаимодействие завершено и получен пригодный текст: одного HTTP 200 недостаточно.

Carbon стал доступен платящим API-разработчикам 10 ноября 2026 года. Более раннее объявление об ограниченном доступе уже не описывает все текущие условия. Мы сверили документацию 13 ноября 2026 года. Ниже — путь от выбора проекта и ключа до сохранённого ответа, который можно проверить.

Примеры обращаются к нативному API Google, а не к конечной точке Ofox. Мы проверили документированный формат запросов и протестировали разбор ответов на синтетических данных, но не выполняли платный запрос к Carbon для этой статьи. Промпт — задание для вашей проверки, а не результат измерения качества модели. Если модель ещё не выбрана, начните со сравнения Carbon, Hydrogen и Argon.

1. Проверьте, к какому платному проекту относится ключ

Нужны аккаунт Google, которому разрешён Gemini API, доступный в AI Studio проект Google Cloud, ключ этого проекта и действующий API-биллинг. Проверяйте эти четыре условия отдельно. Подписка на приложение Gemini или Google AI Ultra сама по себе не настраивает оплату API для проекта вашего приложения.

1. Откройте Google AI Studio и выберите нужный проект. Если проект Cloud уже существует, при необходимости импортируйте его в AI Studio. Не создавайте посторонний проект только ради появления кнопки выпуска ключа.
2. В управлении API-ключами этого проекта создайте или выберите ключ. В журнале развёртывания сохраните имя или ID проекта, а не секрет. Убедитесь, что терминал или сервер загрузит ключ именно этого проекта.
3. Завершите настройку платного доступа для того же проекта в разделе биллинга AI Studio. В зависимости от аккаунта возможны Prepay, выбор Prepay/Postpay или переходный вариант Postpay. Для Prepay может потребоваться не менее 5 долларов США либо эквивалент в местной валюте. Ориентируйтесь на фактический статус аккаунта: привязанная карта ещё не доказывает наличие средств для запросов.
4. Убедитесь, что биллинг активен и необходимый предоплаченный баланс доступен. До запроса проверьте квоты проекта и региональные условия. У платного проекта тоже есть ограничения.

Источники: руководство Google по API-ключам и оплате. Если импорт проекта или создание ключа недоступны, попросите администратора проверить необходимые разрешения. Не решайте отсутствие кнопки публикацией секрета или бесконтрольной выдачей широких прав.

Официальная страница на английском, снимок от 13 ноября 2026 года. Подтверждает публичный выпуск для разработчиков, но не статус оплаты вашего аккаунта и не успешный API-вызов. Оригинал.

Проблема старого ключа не обязательно связана с опечаткой

Сейчас AI Studio по умолчанию создаёт authorization keys. Согласно текущей документации, неограниченные standard keys отклоняются, а standard keys с явно заданными ограничениями продолжают работать. Проверьте тип и ограничения ключа, не считая все старые ключи недействительными.

Храните секрет в серверной переменной окружения или менеджере секретов. Локально задайте 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 и автоматического продолжения в foreground различаются. Указанная граница включает текущее продолжение для 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, сведения об использовании и три содержательных пункта проверки. Прочитайте ответ: завершённое взаимодействие всё равно может не соответствовать требованиям к формату или содержанию. Сохраните JSON для диагностики. Если впоследствии замените безопасный промпт клиентскими данными, обращайтесь с файлом ответа как с потенциально конфиденциальным.

Здесь указан store=False, поскольку запрос одноразовый. Он отключает сохранение взаимодействия для последующего получения или серверного продолжения беседы, но не является универсальным обещанием относительно всех журналов провайдера. По умолчанию действует store=true. Не переносите эту настройку в фоновую задачу или код, использующий previous_interaction_id.

3. Вызовите REST API и прочитайте правильные поля

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 означает проблему передачи или HTTP-запроса; не продолжайте так, будто ответ уже получен. Лимит 900 секунд явно задаёт тайм-аут клиента, а не утверждает, что Carbon всегда работает 15 минут. Тайм-аут клиента также не доказывает остановку сервера. Не повторяйте потенциально платную работу немедленно, не выяснив её состояние.

output_text — удобное свойство SDK, а не поле REST-ответа. В REST текст находится в steps, внутри элементов model_output и их содержимого типа text. Парсер для candidates из GenerateContent либо 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. Разберитесь с настройками до реальной нагрузки

Первый запрос намеренно не включает инструменты, большие файлы и долгий агентный цикл. Добавляйте их по одному после проверки доступа. Руководство Carbon задаёт следующие ограничения.

Для мигрирующих приложений с маленьким выходным лимитом Google рекомендует оставлять минимум 32 768 токенов на рассуждения и вывод. Это решение о бюджете, а не доказательство максимального расхода в каждом запросе. Когда уместно, снижайте уровень рассуждений и смотрите на использование токенов, а не оценивайте счёт по длине ответа. Условия цен и воспроизводимое сравнение приведены в руководстве по выбору Gemini 4.

Когда первый вызов превращается в долгую задачу

Не увеличивайте только max_output_tokens, оставляя остальной код без изменений. Документация длинной генерации различает продолжение в foreground, стриминг и фоновое выполнение. Свежий SDK умеет объединять несколько этапов foreground; собственный 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 API — 55 дней, доступны более короткие варианты. Выбирайте режим осознанно, а не случайно вместе со скопированным кодом.

5. Ищите ошибку по порядку выполнения

Прочитайте структурированную ошибку и запишите конечную точку, точный ID модели, идентификатор проекта, версию SDK и время, исключив секрет. Исправляйте первый сломанный этап до изменения промпта или увеличения бюджета.

Категории объясняет справочник Google. Наша диагностика ошибок Argon API помогает разделить проблемы маршрута, квоты и ответа, но специфичные для Argon детали нельзя автоматически переносить на Carbon. Если после добавления инструментов возникнет ошибка подписи, используйте разбор missing thought signature, а не удаляйте историю вслепую.

Перенос существующего Gemini-клиента

Сохраните рабочую базовую версию и меняйте по одной границе. Нативный GenerateContent API Google по-прежнему поддерживается. Рекомендация Interactions для новых проектов не требует немедленно переписывать все рабочие клиенты.

При переходе обновляйте формат запроса вместе с парсером. Замена только модели на gemini-4-carbon при чтении candidates — незавершённая миграция. Проверьте уровни рассуждений, уберите явные ссылки на кэш и устаревшие предположения о сэмплинге, пересмотрите тайм-ауты и лимиты вывода. В JavaScript Interactions поля generation_config, thinking_level, max_output_tokens используют snake_case; не переносите регистр полей GenerateContent.

До возврата инструментов и клиентских файлов выполните тот же безопасный проверочный промпт. Затем проверьте одну типичную задачу с известными критериями приёмки. Успешный первый вызов подтверждает путь интеграции, а не надёжность многошагового агента в продакшене.

Можно ли запустить пример через Ofox?

Статью публикует Ofox, но примеры используют нативные ключи и адрес Google. В нашем снимке публичного catalog от 13 ноября 2026 года Carbon не был указан. Это наблюдение на конкретную дату, а не доказательство отсутствия поддержки для любого аккаунта или будущего маршрута. Мы не проверяли вызов Carbon через Ofox и не обещаем, что достаточно заменить Base URL.

Для Ofox сначала проверьте текущую доступность точной модели и её протоколы. Затем настройте адрес, аутентификацию и формат по документации Ofox Gemini API. Разделяйте ключи Ofox и Google. Наличие Gemini-совместимого маршрута не подтверждает поддержку Google Interactions или всех функций Carbon.

Ошибки маршрута Ofox разбирайте по руководству Ofox по обработке ошибок и фактическому ответу. Биллинг Google, баланс Ofox и подписка приложения — разные системы: деньги в одной не оплачивают запросы в другой.

Что сохранить после первого успешного вызова

Перед завершением настройки сохраните сведения без секретов:

• Точную модель, адрес API, версию SDK и идентификатор проекта.
• Ответ с ID взаимодействия, статусом и использованием токенов.
• Извлечённый текст, соответствующий заданию из трёх пунктов.
• Уровень рассуждений, бюджет вывода и режим сохранения запроса.
• Возникшие ошибки и конкретные исправления, которые их устранили.

Теперь есть базовая проверка доступа, протокола и вывода. Если после добавления инструмента или большого промпта базовый запрос проходит, а новая задача — нет, исследуйте изменённую часть. Не нужно снова создавать ключи, переносить биллинг или каждый раз запускать всего агента целиком.