how-tos

Gemini 4 Carbon API: руководство — первый запрос на cURL, Python и Gemini Native

Poyo.ai Team
9 min read
Share:

Руководство по Gemini 4 Carbon API: первый запрос на cURL и Python

Это руководство по Gemini 4 Carbon API проведёт вас от API-ключа до работающего запроса на cURL, через Python OpenAI SDK и в нативном формате Google generateContent — везде с ID модели gemini-4-carbon. Каждый пример соответствует опубликованной схеме запросов PoYo на 16 ноября 2026 года. Сначала можно проверить промпты на странице модели Gemini 4 Carbon.

Впервые слышите об этой модели? Начните с обзора Gemini 4 Carbon API, где описаны лимиты и позиционирование.

Перед началом

Создайте ключ в панели PoYo и храните его на сервере:

export POYO_API_KEY="your-poyo-key"
ФорматЭндпоинтКогда использовать
Chat CompletionsPOST https://api.poyo.ai/v1/chat/completionsУ вас уже есть OpenAI SDK, сообщения только текстовые
Gemini NativePOST https://api.poyo.ai/v1beta/models/gemini-4-carbon:generateContentНужны части с изображениями или файлами (inlineData)
Стриминг Gemini NativePOST https://api.poyo.ai/v1beta/models/gemini-4-carbon:streamGenerateContentНативный формат с server-sent events

Каждый запрос передаёт Authorization: Bearer $POYO_API_KEY. В PoYo gemini-4-carbon не поддерживает /v1/responses и /v1/messages.

Первый запрос к Gemini 4 Carbon API через cURL

curl https://api.poyo.ai/v1/chat/completions \
  -H "Authorization: Bearer $POYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-4-carbon",
    "messages": [
      {"role": "system", "content": "You are a code reviewer. Be specific and cite line numbers."},
      {"role": "user", "content": "Review this function for race conditions: ..."}
    ],
    "max_tokens": 8192,
    "temperature": 1
  }'

Поля model и messages обязательны. Необязательные поля в схеме PoYo: temperature (0–2), top_p (0–1; используйте его или temperature, но не оба сразу), max_tokens, stream, stop (до 4 последовательностей), frequency_penalty и presence_penalty (от −2 до 2), а также n. Поле content каждого сообщения — строка.

Ответ — стандартный объект chat.completion: текст в choices[0].message.content, причина остановки в choices[0].finish_reason, счётчики в usage.prompt_tokens, usage.completion_tokens и usage.total_tokens.

Python и OpenAI SDK

Направьте SDK на PoYo, больше ничего менять не нужно:

import os
from openai import OpenAI

client = OpenAI(base_url="https://api.poyo.ai/v1", api_key=os.environ["POYO_API_KEY"])

resp = client.chat.completions.create(
    model="gemini-4-carbon",
    messages=[
        {"role": "system", "content": "You are a senior backend engineer."},
        {"role": "user", "content": "Write a migration plan from Celery 4 to Celery 5."},
    ],
    max_tokens=8192,
)

print(resp.choices[0].message.content)
print(resp.choices[0].finish_reason, resp.usage.prompt_tokens, resp.usage.completion_tokens)

Переход с gemini-4-argon или любой другой модели, поддерживающей Chat Completions в PoYo, — это изменение одной строки в model.

Стриминг через OpenAI SDK

При stream=True PoYo отправляет события chat.completion.chunk и завершает поток строкой data: [DONE]. Текст приходит в choices[0].delta.content, а последний чанк содержит finish_reason и usage:

stream = client.chat.completions.create(
    model="gemini-4-carbon",
    messages=[{"role": "user", "content": "Explain the CAP theorem with one example per trade-off."}],
    max_tokens=4096,
    stream=True,
)

usage = None
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
    if getattr(chunk, "usage", None):
        usage = chunk.usage
print("\n", usage)

Нативный формат generateContent от Gemini

Нативный эндпоинт принимает модель в пути URL. Тело запроса содержит contents (у каждого элемента role — user или model — и массив parts), а также необязательные generationConfig (temperature, topP, topK, maxOutputTokens, stopSequences) и safetySettings:

curl "https://api.poyo.ai/v1beta/models/gemini-4-carbon:generateContent" \
  -H "Authorization: Bearer $POYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "List three risks of running database migrations during peak traffic."}]}
    ],
    "generationConfig": {"maxOutputTokens": 2048, "temperature": 0.7}
  }'

Ответ — объект Google GenerateContentResponse, возвращаемый напрямую. Текст находится в candidates[].content.parts[].text, счётчики — в usageMetadata. Модели с мышлением могут добавлять части с thought: true или thoughtSignature, поэтому пропускайте части без текста:

import os, requests

URL = "https://api.poyo.ai/v1beta/models/gemini-4-carbon:generateContent"
HEADERS = {"Authorization": f"Bearer {os.environ['POYO_API_KEY']}"}

body = {
    "contents": [{"role": "user", "parts": [{"text": "Summarize the trade-offs of event sourcing."}]}],
    "generationConfig": {"maxOutputTokens": 2048},
}
r = requests.post(URL, headers=HEADERS, json=body, timeout=600)
r.raise_for_status()
data = r.json()

text = "".join(
    p["text"]
    for c in data.get("candidates", [])
    for p in c.get("content", {}).get("parts", [])
    if "text" in p and not p.get("thought")
)
print(text)
print(data["usageMetadata"])

Нативный стриминг

Замените метод на :streamGenerateContent. Ответ приходит как text/event-stream: каждая строка data: — частичный GenerateContentResponse, последнее событие содержит finishReason, а поток завершается строкой data: [DONE]. Параметр запроса alt=sse принимается, но не обязателен.

import json

STREAM_URL = "https://api.poyo.ai/v1beta/models/gemini-4-carbon:streamGenerateContent"
usage = {}
with requests.post(STREAM_URL, headers=HEADERS, json=body, stream=True, timeout=600) as r:
    r.raise_for_status()
    for line in r.iter_lines(decode_unicode=True):
        if not line or not line.startswith("data: "):
            continue
        payload = line[len("data: "):]
        if payload == "[DONE]":
            break
        event = json.loads(payload)
        for cand in event.get("candidates", []):
            for part in cand.get("content", {}).get("parts", []):
                if "text" in part and not part.get("thought"):
                    print(part["text"], end="", flush=True)
        usage = event.get("usageMetadata", usage)
print("\n", usage)

Мультимодальный ввод в Gemini 4 Carbon API

Google указывает текст, изображения, аудио, видео и PDF как типы входных данных для Gemini 4 Carbon. В PoYo файлы передаются через нативный формат в виде части inlineData с mimeType и data в base64. В документации PoYo приведён пример с изображением и рекомендуется ставить текстовые инструкции перед медиачастями:

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {"text": "Read this architecture diagram and list every service that writes to the database."},
        {"inlineData": {"mimeType": "image/png", "data": "BASE64_IMAGE_DATA"}}
      ]
    }
  ],
  "generationConfig": {"maxOutputTokens": 4096}
}

Схема Chat Completions в PoYo описывает content как строку, поэтому не отправляйте в /v1/chat/completions массивы изображений в стиле OpenAI. Для PDF, аудио и видео в документации PoYo отдельного примера нет: сначала отправьте один небольшой файл и проверьте ответ, прежде чем строить на этом пайплайн. Медиа учитываются в промпте: usageMetadata.promptTokensDetails разбивает входные токены по модальностям.

Настройка максимального вывода

ФорматПолеПризнак того, что вывод обрезан
Chat Completionsmax_tokensfinish_reason: "length"
Gemini NativegenerationConfig.maxOutputTokensfinishReason, отличный от STOP

Google указывает 65,536 выходных токенов как лимит по умолчанию для синхронных запросов и контекст в 1,048,576 токенов, общий для входа и выхода. На странице цен Google сказано, что токены мышления тарифицируются по ставке выхода, поэтому число выходных токенов в usage может быть больше, чем видимый текст. В опубликованных схемах PoYo нет поля уровня мышления; задокументированный способ управлять длиной — поле максимального вывода.

Чтение usage и расчёт стоимости запроса

В PoYo gemini-4-carbon стоит $1.60 за 1M входных токенов, $8.00 за 1M выходных и $0.08 за 1M токенов чтения из кэша (1 кредит = $0.005).

ФорматВходные токеныВыходные токены (включая мышление)
Chat Completionsusage.prompt_tokensusage.total_tokens − usage.prompt_tokens
Gemini NativeusageMetadata.promptTokenCounttotalTokenCount − promptTokenCount (ответ плюс thoughtsTokenCount)
INPUT_USD, OUTPUT_USD = 1.60, 8.00  # PoYo, per 1M tokens

def carbon_cost_usd(input_tokens: int, output_tokens: int) -> float:
    return (input_tokens * INPUT_USD + output_tokens * OUTPUT_USD) / 1_000_000

def carbon_cost_credits(input_tokens: int, output_tokens: int) -> float:
    return carbon_cost_usd(input_tokens, output_tokens) / 0.005

Измеренный пример (продакшн PoYo, 16 ноября 2026 г.): непотоковый запрос к /v1/chat/completions с просьбой к gemini-4-carbon проверить функцию на Python из 40 строк вернул prompt_tokens: 480, completion_tokens: 1094 и total_tokens: 1574 за 6,3 секунды, без токенов размышления. PoYo списал 1,904 кредита — столько же, сколько даёт формула.

input:     480 × $1.60 / 1,000,000 = $0.000768   (0.1536 credits)
output:  1,094 × $8.00 / 1,000,000 = $0.008752   (1.7504 credits)
total:                               $0.009520   (1.9040 credits)

Здесь каждый входной токен считается по полной ставке входа. Токены чтения из кэша стоят $0.08 за 1M, но в схемах ответов PoYo поле с кэшированными токенами не описано, поэтому считайте эту формулу оценкой сверху. Сценарии затрат в масштабе — в статье Цены Gemini 4 Carbon API.

Ошибки, которые стоит обрабатывать

LLM-эндпоинты PoYo возвращают настоящие HTTP-коды статуса:

HTTPПричинаЧто делать
400Отсутствует или некорректно поле; тело {"code": 400, "error": {"type": "validation_error", ...}}Исправьте запрос; смотрите error.details
400Неподходящий формат для этой модели; в сообщении перечислены поддерживаемые URIИспользуйте Chat Completions или Gemini Native
400Ошибка Gemini Native в формате Google {"error": {"code": 400, "message": "...", "status": "INVALID_ARGUMENT"}}Исправьте contents / generationConfig
401API-ключ отсутствует или недействителенПроверьте заголовок Authorization
402Недостаточно кредитовПополните баланс перед повтором
404Неизвестный ID модели (model_not_found)Проверьте написание: gemini-4-carbon
500 / 502 / 503Ошибка сервера или вышестоящего провайдераПовторите с экспоненциальной задержкой

В документации PoYo сказано, что LLM-эндпоинты сейчас не ограничены по частоте запросов, но среди общих кодов ошибок PoYo есть 429. Обрабатывайте его ожиданием и повтором. В OpenAI SDK перехватывайте openai.APIStatusError и ветвитесь по status_code. Полные тела ответов — в разделе коды ошибок PoYo.

Чек-лист перед запуском в продакшен

  • Храните POYO_API_KEY на сервере; никогда не включайте его в браузерный или мобильный код.
  • Всегда задавайте max_tokens или maxOutputTokens и логируйте finish_reason / finishReason, чтобы обрезанные ответы были заметны.
  • Сохраняйте блок usage каждого ответа рядом с назначенным вами ID запроса, чтобы сверять расходы по функциям.
  • Ставьте длинный стабильный контекст (файлы репозитория, документы) в начало, а меняющийся вопрос — в конец: так у неявного кэширования есть шанс сработать.
  • Повторяйте только ответы 5xx и 429; запрос с 400 будет падать снова, пока не изменится тело.

Об агентных циклах, выводе инструментов и паттернах работы с длинным контекстом читайте в статье Gemini 4 Carbon API для агентов разработки. Чтобы понять, когда достаточно Argon, прочитайте Gemini 4 Carbon API vs Gemini 4 Argon.

Часто задаваемые вопросы

Как вызвать Gemini 4 Carbon API на Python?

Используйте OpenAI SDK с base_url="https://api.poyo.ai/v1", вашим ключом PoYo и model="gemini-4-carbon". Для нативных запросов отправляйте POST на /v1beta/models/gemini-4-carbon:generateContent через requests.

Поддерживает ли Gemini 4 Carbon API стриминг?

Да. Задайте "stream": true в Chat Completions или вызовите :streamGenerateContent в нативном формате. Оба варианта возвращают server-sent events, которые завершаются строкой data: [DONE].

Как отправить изображение в Gemini 4 Carbon API?

Используйте нативный эндпоинт Gemini с частью inlineData (mimeType плюс data в base64) после текстовой части. Chat Completions в PoYo принимает только строковый content.

Как ограничить число выходных токенов Gemini 4 Carbon API?

Задайте max_tokens (Chat Completions) или generationConfig.maxOutputTokens (нативный формат). Токены мышления тарифицируются как выход, поэтому при выборе лимита сравнивайте число выходных токенов в usage с видимым текстом.

Почему Gemini 4 Carbon API возвращает 400 на /v1/responses?

В PoYo gemini-4-carbon поддерживает только Chat Completions и Gemini Native. Другие форматы возвращают 400 со списком поддерживаемых URI.

Share: