how-tos

Gemini 4 Carbon API: guía de la primera solicitud con cURL, Python y Gemini Native

Poyo.ai Team
10 min read
Share:

Guía de la Gemini 4 Carbon API: primera solicitud con cURL y Python

Esta guía de la Gemini 4 Carbon API te lleva desde la clave de API hasta una solicitud que funciona con cURL, el SDK de OpenAI para Python y el formato nativo generateContent de Google, siempre con el ID de modelo gemini-4-carbon. Cada ejemplo sigue el esquema de solicitud publicado por PoYo a 16 de noviembre de 2026. Puedes probar primero los prompts en la página del modelo Gemini 4 Carbon.

¿Es la primera vez que usas el modelo? Empieza por el resumen de la Gemini 4 Carbon API para conocer sus límites y su posicionamiento.

Antes de empezar

Crea una clave en el panel de PoYo y guárdala en tu servidor:

export POYO_API_KEY="your-poyo-key"
FormatoEndpointCuándo usarlo
Chat CompletionsPOST https://api.poyo.ai/v1/chat/completionsYa usas el SDK de OpenAI, mensajes solo de texto
Gemini NativePOST https://api.poyo.ai/v1beta/models/gemini-4-carbon:generateContentNecesitas partes de imagen o de archivo (inlineData)
Gemini Native con streamingPOST https://api.poyo.ai/v1beta/models/gemini-4-carbon:streamGenerateContentFormato nativo con server-sent events

Cada solicitud envía Authorization: Bearer $POYO_API_KEY. En PoYo, gemini-4-carbon no admite /v1/responses ni /v1/messages.

Primera solicitud a la Gemini 4 Carbon API con 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 y messages son obligatorios. Campos opcionales en el esquema de PoYo: temperature (0–2), top_p (0–1; usa este o temperature, no ambos), max_tokens, stream, stop (hasta 4 secuencias), frequency_penalty y presence_penalty (de −2 a 2), y n. El content de cada mensaje es una cadena.

La respuesta es un objeto chat.completion estándar: el texto en choices[0].message.content, el motivo de parada en choices[0].finish_reason y los recuentos en usage.prompt_tokens, usage.completion_tokens y usage.total_tokens.

Python con el SDK de OpenAI

Apunta el SDK a PoYo y no cambies nada más:

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)

Pasar desde gemini-4-argon, o desde cualquier otro modelo que admita Chat Completions en PoYo, supone cambiar una sola línea: model.

Streaming con el SDK de OpenAI

Con stream=True, PoYo envía eventos chat.completion.chunk y termina con data: [DONE]. El texto llega en choices[0].delta.content y el último fragmento incluye finish_reason y 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)

El formato nativo generateContent de Gemini

El endpoint nativo recibe el modelo en la ruta de la URL. El cuerpo usa contents (cada uno con role user o model y un array parts), además de los opcionales generationConfig (temperature, topP, topK, maxOutputTokens, stopSequences) y 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}
  }'

La respuesta es el objeto GenerateContentResponse de Google, devuelto tal cual. El texto está en candidates[].content.parts[].text y los recuentos en usageMetadata. Los modelos con razonamiento pueden añadir partes con thought: true o una thoughtSignature, así que omite las partes que no tengan texto:

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"])

Streaming nativo

Cambia el método por :streamGenerateContent. La respuesta es text/event-stream: cada línea data: es un GenerateContentResponse parcial, el último evento incluye finishReason y el stream termina con data: [DONE]. El parámetro de consulta alt=sse se acepta, pero no es obligatorio.

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)

Entrada multimodal con la Gemini 4 Carbon API

Google indica texto, imagen, audio, vídeo y PDF como tipos de entrada de Gemini 4 Carbon. En PoYo, los archivos se envían mediante el formato nativo como una parte inlineData con un mimeType y data en base64. La documentación de PoYo muestra un ejemplo con imagen y recomienda colocar las instrucciones de texto antes de las partes multimedia:

{
  "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}
}

El esquema de Chat Completions de PoYo documenta content como una cadena, así que no envíes arrays de imágenes al estilo de OpenAI a /v1/chat/completions. Para PDF, audio y vídeo, la documentación de PoYo no muestra un ejemplo específico; envía primero un archivo pequeño y revisa la respuesta antes de construir un pipeline sobre ello. Los archivos multimedia cuentan para el prompt: usageMetadata.promptTokensDetails desglosa los tokens del prompt por modalidad.

Configurar la salida máxima

FormatoCampoSeñal de que la salida se ha cortado
Chat Completionsmax_tokensfinish_reason: "length"
Gemini NativegenerationConfig.maxOutputTokensfinishReason distinto de STOP

Google indica 65.536 tokens de salida como límite síncrono por defecto y un contexto de 1.048.576 tokens compartido entre entrada y salida. La página de precios de Google indica que los tokens de razonamiento se facturan a la tarifa de salida, así que el recuento de salida en usage puede ser mayor que el texto visible. Los esquemas publicados por PoYo no tienen ningún campo de nivel de razonamiento; el campo de salida máxima es el control de longitud documentado.

Leer el uso y calcular el coste de una solicitud

PoYo cobra gemini-4-carbon a 1,60 $ por cada millón de tokens de entrada, 8,00 $ por cada millón de tokens de salida y 0,08 $ por cada millón de tokens leídos de caché (1 crédito = 0,005 $).

FormatoTokens de entradaTokens de salida (incl. razonamiento)
Chat Completionsusage.prompt_tokensusage.total_tokens − usage.prompt_tokens
Gemini NativeusageMetadata.promptTokenCounttotalTokenCount − promptTokenCount (respuesta más 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

Ejemplo medido (producción de PoYo, 16 de noviembre de 2026): una solicitud sin streaming a /v1/chat/completions que pedía a gemini-4-carbon revisar una función de Python de 40 líneas devolvió prompt_tokens: 480, completion_tokens: 1094 y total_tokens: 1574 en 6,3 segundos, sin tokens de razonamiento informados. PoYo cobró 1,904 créditos, la misma cifra que da la fórmula.

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)

Este cálculo aplica la tarifa de entrada completa a todos los tokens del prompt. Los tokens leídos de caché se facturan a 0,08 $ por millón, pero los esquemas de respuesta de PoYo no documentan ningún campo de tokens en caché, así que considera esta fórmula como un límite superior. Tienes escenarios de coste a escala en precios de la Gemini 4 Carbon API.

Errores que conviene gestionar

Los endpoints de LLM de PoYo devuelven códigos de estado HTTP reales:

HTTPCausaQué hacer
400Campo ausente o no válido; cuerpo {"code": 400, "error": {"type": "validation_error", ...}}Corrige la solicitud; lee error.details
400Formato incorrecto para este modelo; el mensaje lista las URI admitidasUsa Chat Completions o Gemini Native
400Error de Gemini Native, con la estructura de Google {"error": {"code": 400, "message": "...", "status": "INVALID_ARGUMENT"}}Corrige contents / generationConfig
401Clave de API ausente o no válidaRevisa la cabecera Authorization
402Créditos insuficientesRecarga antes de reintentar
404ID de modelo desconocido (model_not_found)Revisa la ortografía: gemini-4-carbon
500 / 502 / 503Error del servidor o del proveedor upstreamReintenta con backoff exponencial

La documentación de PoYo indica que los endpoints de LLM no tienen actualmente límite de tasa, pero los códigos de error generales de PoYo incluyen 429. Gestiónalo esperando y reintentando. Con el SDK de OpenAI, captura openai.APIStatusError y ramifica según status_code. Consulta los códigos de error de PoYo para ver los cuerpos completos.

Lista de comprobación antes de pasar a producción

  • Mantén POYO_API_KEY en el servidor; nunca la incluyas en código de navegador o de móvil.
  • Define siempre max_tokens o maxOutputTokens, y registra finish_reason / finishReason para que las respuestas truncadas sean visibles.
  • Guarda el bloque de uso de cada respuesta junto al ID de solicitud que asignes, para poder conciliar el gasto por funcionalidad.
  • Coloca primero el contexto largo y estable (archivos del repositorio, documentos) y al final la pregunta que cambia; así das a la caché implícita la oportunidad de aplicarse.
  • Reintenta solo las respuestas 5xx y 429; un 400 volverá a fallar mientras no cambie el cuerpo.

Para bucles de agentes, salida de herramientas y patrones de contexto largo, continúa con Gemini 4 Carbon API para agentes de programación. Para decidir cuándo basta con Argon, lee Gemini 4 Carbon API frente a Gemini 4 Argon.

Preguntas frecuentes

¿Cómo llamo a la Gemini 4 Carbon API en Python?

Usa el SDK de OpenAI con base_url="https://api.poyo.ai/v1", tu clave de PoYo y model="gemini-4-carbon". Para solicitudes nativas, haz un POST a /v1beta/models/gemini-4-carbon:generateContent con requests.

¿La Gemini 4 Carbon API admite streaming?

Sí. Define "stream": true en Chat Completions o llama a :streamGenerateContent en el formato nativo. Ambos devuelven server-sent events que terminan con data: [DONE].

¿Cómo envío una imagen a la Gemini 4 Carbon API?

Usa el endpoint nativo de Gemini con una parte inlineData (mimeType más data en base64) después de tu parte de texto. Chat Completions en PoYo solo acepta contenido de tipo cadena.

¿Cómo limito los tokens de salida de la Gemini 4 Carbon API?

Define max_tokens (Chat Completions) o generationConfig.maxOutputTokens (nativo). Los tokens de razonamiento se facturan como salida, así que compara el recuento de salida en usage con el texto visible al elegir el límite.

¿Por qué la Gemini 4 Carbon API devuelve 400 en /v1/responses?

En PoYo, gemini-4-carbon solo admite Chat Completions y Gemini Native. Los demás formatos devuelven 400 con la lista de URI admitidas.

Share: