
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"
| Formato | Endpoint | Cuándo usarlo |
|---|---|---|
| Chat Completions | POST https://api.poyo.ai/v1/chat/completions | Ya usas el SDK de OpenAI, mensajes solo de texto |
| Gemini Native | POST https://api.poyo.ai/v1beta/models/gemini-4-carbon:generateContent | Necesitas partes de imagen o de archivo (inlineData) |
| Gemini Native con streaming | POST https://api.poyo.ai/v1beta/models/gemini-4-carbon:streamGenerateContent | Formato 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
| Formato | Campo | Señal de que la salida se ha cortado |
|---|---|---|
| Chat Completions | max_tokens | finish_reason: "length" |
| Gemini Native | generationConfig.maxOutputTokens | finishReason 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 $).
| Formato | Tokens de entrada | Tokens de salida (incl. razonamiento) |
|---|---|---|
| Chat Completions | usage.prompt_tokens | usage.total_tokens − usage.prompt_tokens |
| Gemini Native | usageMetadata.promptTokenCount | totalTokenCount − 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:
| HTTP | Causa | Qué hacer |
|---|---|---|
| 400 | Campo ausente o no válido; cuerpo {"code": 400, "error": {"type": "validation_error", ...}} | Corrige la solicitud; lee error.details |
| 400 | Formato incorrecto para este modelo; el mensaje lista las URI admitidas | Usa Chat Completions o Gemini Native |
| 400 | Error de Gemini Native, con la estructura de Google {"error": {"code": 400, "message": "...", "status": "INVALID_ARGUMENT"}} | Corrige contents / generationConfig |
| 401 | Clave de API ausente o no válida | Revisa la cabecera Authorization |
| 402 | Créditos insuficientes | Recarga antes de reintentar |
| 404 | ID de modelo desconocido (model_not_found) | Revisa la ortografía: gemini-4-carbon |
| 500 / 502 / 503 | Error del servidor o del proveedor upstream | Reintenta 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_KEYen el servidor; nunca la incluyas en código de navegador o de móvil. - Define siempre
max_tokensomaxOutputTokens, y registrafinish_reason/finishReasonpara 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.