
Questa guida alla Gemini 4 Carbon API ti porta da una chiave API a una richiesta funzionante con cURL, con l'SDK OpenAI per Python e con il formato nativo generateContent di Google, sempre con l'ID modello gemini-4-carbon. Ogni esempio segue lo schema di richiesta pubblicato da PoYo al 16 novembre 2026. Puoi prima provare i prompt sulla pagina del modello Gemini 4 Carbon.
Non conosci ancora il modello? Parti dalla panoramica della Gemini 4 Carbon API per limiti e posizionamento.
Prima di iniziare
Crea una chiave nella dashboard di PoYo e tienila sul tuo server:
export POYO_API_KEY="your-poyo-key"
| Formato | Endpoint | Quando usarlo |
|---|---|---|
| Chat Completions | POST https://api.poyo.ai/v1/chat/completions | Usi già l'SDK di OpenAI, messaggi solo testuali |
| Gemini Native | POST https://api.poyo.ai/v1beta/models/gemini-4-carbon:generateContent | Ti servono parti con immagini o file (inlineData) |
| Gemini Native in streaming | POST https://api.poyo.ai/v1beta/models/gemini-4-carbon:streamGenerateContent | Formato nativo con server-sent events |
Ogni richiesta invia Authorization: Bearer $POYO_API_KEY. Su PoYo, gemini-4-carbon non supporta /v1/responses né /v1/messages.
Prima richiesta alla 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 e messages sono obbligatori. Campi facoltativi nello schema di PoYo: temperature (0–2), top_p (0–1, usa questo oppure temperature, non entrambi), max_tokens, stream, stop (fino a 4 sequenze), frequency_penalty e presence_penalty (da −2 a 2) e n. Il content di ogni messaggio è una stringa.
La risposta è un normale oggetto chat.completion: il testo in choices[0].message.content, il motivo di arresto in choices[0].finish_reason e i conteggi in usage.prompt_tokens, usage.completion_tokens e usage.total_tokens.
Python con l'SDK di OpenAI
Punta l'SDK a PoYo e non cambiare nient'altro:
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)
Passare da gemini-4-argon, o da qualsiasi altro modello che supporta Chat Completions su PoYo, richiede di cambiare una sola riga: model.
Streaming con l'SDK di OpenAI
Con stream=True, PoYo invia eventi chat.completion.chunk e termina con data: [DONE]. Il testo arriva in choices[0].delta.content e l'ultimo chunk contiene finish_reason e 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)
Il formato nativo generateContent di Gemini
L'endpoint nativo riceve il modello nel percorso URL. Il body usa contents (ciascuno con role user o model e un array parts), più i campi facoltativi generationConfig (temperature, topP, topK, maxOutputTokens, stopSequences) e 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 risposta è l'oggetto GenerateContentResponse di Google, restituito direttamente. Il testo è in candidates[].content.parts[].text e i conteggi in usageMetadata. I modelli con thinking possono aggiungere parti con thought: true o una thoughtSignature, quindi salta le parti senza testo:
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
Sostituisci il metodo con :streamGenerateContent. La risposta è text/event-stream: ogni riga data: è una GenerateContentResponse parziale, l'ultimo evento contiene finishReason e lo stream termina con data: [DONE]. Il parametro di query alt=sse è accettato ma non obbligatorio.
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)
Input multimodale con la Gemini 4 Carbon API
Google elenca testo, immagini, audio, video e PDF come tipi di input per Gemini 4 Carbon. Su PoYo, l'input di file passa dal formato nativo come parte inlineData con un mimeType e data in base64. La documentazione di PoYo mostra un esempio con un'immagine e consiglia di mettere le istruzioni testuali prima delle parti multimediali:
{
"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}
}
Lo schema Chat Completions di PoYo documenta content come stringa, quindi non inviare array di immagini in stile OpenAI a /v1/chat/completions. Per PDF, audio e video la documentazione di PoYo non mostra un esempio dedicato; invia prima un file piccolo e controlla la risposta prima di costruirci sopra una pipeline. I contenuti multimediali contano nel prompt: usageMetadata.promptTokensDetails suddivide i token del prompt per modalità.
Impostare l'output massimo
| Formato | Campo | Segnale che l'output è stato troncato |
|---|---|---|
| Chat Completions | max_tokens | finish_reason: "length" |
| Gemini Native | generationConfig.maxOutputTokens | finishReason diverso da STOP |
Google indica 65.536 token di output come limite sincrono predefinito e un contesto da 1.048.576 token condiviso tra input e output. La pagina dei prezzi di Google indica che i token di thinking sono fatturati alla tariffa di output, quindi il conteggio di output in usage può essere maggiore del testo visibile. Gli schemi pubblicati da PoYo non hanno un campo per il livello di thinking; il campo dell'output massimo è il controllo di lunghezza documentato.
Leggere l'usage e calcolare il costo di una richiesta
PoYo applica a gemini-4-carbon $1.60 per 1M di token in input, $8.00 per 1M di token in output e $0.08 per 1M di token letti dalla cache (1 credito = $0.005).
| Formato | Token di input | Token di output (thinking incluso) |
|---|---|---|
| Chat Completions | usage.prompt_tokens | usage.total_tokens − usage.prompt_tokens |
| Gemini Native | usageMetadata.promptTokenCount | totalTokenCount − promptTokenCount (risposta più 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
Esempio misurato (produzione PoYo, 16 novembre 2026): una richiesta /v1/chat/completions senza streaming che chiedeva a gemini-4-carbon di rivedere una funzione Python di 40 righe ha restituito prompt_tokens: 480, completion_tokens: 1094 e total_tokens: 1574 in 6,3 secondi, senza thinking token riportati. PoYo ha addebitato 1,904 crediti, lo stesso valore della formula.
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)
Questo calcolo applica a ogni token del prompt la tariffa di input piena. I token letti dalla cache sono fatturati a $0.08 per 1M, ma gli schemi di risposta di PoYo non documentano un campo per i token in cache, quindi considera questa formula un limite superiore. Scenari di costo su larga scala sono in Prezzi della Gemini 4 Carbon API.
Errori da gestire
Gli endpoint LLM di PoYo restituiscono codici di stato HTTP reali:
| HTTP | Causa | Cosa fare |
|---|---|---|
| 400 | Campo mancante o non valido; body {"code": 400, "error": {"type": "validation_error", ...}} | Correggi la richiesta; leggi error.details |
| 400 | Formato sbagliato per questo modello; il messaggio elenca gli URI supportati | Usa Chat Completions o Gemini Native |
| 400 | Errore Gemini Native, nella forma di Google {"error": {"code": 400, "message": "...", "status": "INVALID_ARGUMENT"}} | Correggi contents / generationConfig |
| 401 | Chiave API mancante o non valida | Controlla l'header Authorization |
| 402 | Crediti insufficienti | Ricarica prima di riprovare |
| 404 | ID modello sconosciuto (model_not_found) | Controlla l'ortografia: gemini-4-carbon |
| 500 / 502 / 503 | Errore del server o upstream | Riprova con backoff esponenziale |
La documentazione di PoYo indica che al momento gli endpoint LLM non hanno limiti di frequenza, ma i codici di errore generali di PoYo includono 429. Gestiscilo con un'attesa e un nuovo tentativo. Con l'SDK di OpenAI, intercetta openai.APIStatusError e ramifica su status_code. Consulta i codici di errore di PoYo per i body completi.
Checklist prima del rilascio
- Tieni
POYO_API_KEYlato server; non includerla mai nel codice browser o mobile. - Imposta sempre
max_tokensomaxOutputTokense registrafinish_reason/finishReason, così le risposte troncate sono visibili. - Salva il blocco usage di ogni risposta accanto all'ID richiesta che assegni, così puoi riconciliare la spesa per funzionalità.
- Metti il contesto lungo e stabile (file del repository, documenti) all'inizio e la domanda variabile alla fine, per dare al caching implicito la possibilità di attivarsi.
- Riprova solo le risposte 5xx e
429; un 400 fallirà di nuovo finché il body non cambia.
Per i loop degli agenti, l'output degli strumenti e i pattern con contesto lungo, prosegui con Gemini 4 Carbon API per agenti di coding. Per capire quando basta Argon, leggi Gemini 4 Carbon API vs Gemini 4 Argon.
Domande frequenti
Come chiamo la Gemini 4 Carbon API in Python?
Usa l'SDK di OpenAI con base_url="https://api.poyo.ai/v1", la tua chiave PoYo e model="gemini-4-carbon". Per le richieste native, invia una POST a /v1beta/models/gemini-4-carbon:generateContent con requests.
La Gemini 4 Carbon API supporta lo streaming?
Sì. Imposta "stream": true su Chat Completions, oppure chiama :streamGenerateContent nel formato nativo. Entrambi restituiscono server-sent events che terminano con data: [DONE].
Come invio un'immagine alla Gemini 4 Carbon API?
Usa l'endpoint nativo di Gemini con una parte inlineData (mimeType più data in base64) dopo la parte testuale. Chat Completions su PoYo accetta solo contenuto in forma di stringa.
Come limito i token di output della Gemini 4 Carbon API?
Imposta max_tokens (Chat Completions) o generationConfig.maxOutputTokens (nativo). I token di thinking sono fatturati come output, quindi confronta il conteggio di output in usage con il testo visibile quando scegli il limite.
Perché la Gemini 4 Carbon API restituisce 400 su /v1/responses?
Su PoYo, gemini-4-carbon supporta solo Chat Completions e Gemini Native. Gli altri formati restituiscono 400 con l'elenco degli URI supportati.