how-tos

Gemini 4 Carbon API-guide: første forespørsel med cURL, Python og Gemini Native

Poyo.ai Team
9 min read
Share:

Gemini 4 Carbon API-guide: første forespørsel med cURL og Python

Denne Gemini 4 Carbon API-guiden tar deg fra en API-nøkkel til en fungerende forespørsel med cURL, Python OpenAI SDK og Googles native generateContent-format, alle med modell-ID-en gemini-4-carbon. Hvert eksempel følger PoYos publiserte forespørselsskjema per 16. november 2026. Du kan teste prompter på Gemini 4 Carbon-modellsiden først.

Ny med modellen? Begynn med Gemini 4 Carbon API-oversikten for grenser og posisjonering.

Før du begynner

Opprett en nøkkel i PoYo-dashbordet, og hold den på serveren din:

export POYO_API_KEY="your-poyo-key"
FormatEndepunktBruk det når
Chat CompletionsPOST https://api.poyo.ai/v1/chat/completionsDu allerede bruker OpenAI SDK-et, meldinger med bare tekst
Gemini NativePOST https://api.poyo.ai/v1beta/models/gemini-4-carbon:generateContentDu trenger bilde- eller fildeler (inlineData)
Gemini Native-strømmingPOST https://api.poyo.ai/v1beta/models/gemini-4-carbon:streamGenerateContentNative format med server-sent events

Hver forespørsel sender Authorization: Bearer $POYO_API_KEY. gemini-4-carbon støtter ikke /v1/responses eller /v1/messages på PoYo.

Første forespørsel til Gemini 4 Carbon API med 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 og messages er påkrevd. Valgfrie felt i PoYos skjema: temperature (0–2), top_p (0–1, bruk den eller temperature, ikke begge), max_tokens, stream, stop (opptil 4 sekvenser), frequency_penalty og presence_penalty (−2 til 2) og n. Hver meldings content er en streng.

Svaret er et standard chat.completion-objekt: tekst i choices[0].message.content, stoppårsaken i choices[0].finish_reason og antall i usage.prompt_tokens, usage.completion_tokens og usage.total_tokens.

Python med OpenAI SDK-et

Pek SDK-et mot PoYo, og la alt annet være som før:

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)

Å bytte fra gemini-4-argon, eller en annen modell som støtter Chat Completions på PoYo, er en endring på én linje i model.

Strømming med OpenAI SDK-et

Med stream=True sender PoYo chat.completion.chunk-hendelser og avslutter med data: [DONE]. Teksten kommer i choices[0].delta.content, og den siste chunken inneholder finish_reason og 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)

Det Gemini-native generateContent-formatet

Det native endepunktet tar modellen i URL-stien. Brødteksten bruker contents (hver med role user eller model og en parts-array), pluss valgfri generationConfig (temperature, topP, topK, maxOutputTokens, stopSequences) og 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}
  }'

Svaret er Googles GenerateContentResponse-objekt, returnert direkte. Teksten ligger i candidates[].content.parts[].text, og antall ligger i usageMetadata. Tenkende modeller kan legge til deler med thought: true eller en thoughtSignature, så hopp over deler uten tekst:

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

Native strømming

Bytt metoden til :streamGenerateContent. Svaret er text/event-stream: hver data:-linje er et delvis GenerateContentResponse, den siste hendelsen inneholder finishReason, og strømmen avsluttes med data: [DONE]. Query-parameteren alt=sse godtas, men er ikke påkrevd.

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)

Multimodal input via Gemini 4 Carbon API

Google oppgir tekst, bilde, lyd, video og PDF som inputtyper for Gemini 4 Carbon. På PoYo sendes filinput via det native formatet som en inlineData-del med en mimeType og base64-kodet data. PoYos dokumentasjon viser et bildeeksempel og anbefaler å legge tekstinstruksjoner før mediedeler:

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

PoYos Chat Completions-skjema dokumenterer content som en streng, så ikke send bildearrays i OpenAI-stil til /v1/chat/completions. For PDF, lyd og video viser ikke PoYos dokumentasjon et eget eksempel; send én liten fil først og sjekk svaret før du bygger en pipeline på det. Medier teller med i prompten: usageMetadata.promptTokensDetails deler prompt-tokens opp etter modalitet.

Sette maks. output

FormatFeltTegn på at outputen ble kuttet
Chat Completionsmax_tokensfinish_reason: "length"
Gemini NativegenerationConfig.maxOutputTokensfinishReason annet enn STOP

Google oppgir 65 536 output-tokens som standardtaket for synkrone kall og en kontekst på 1 048 576 tokens delt mellom input og output. Googles prisside sier at thinking-tokens faktureres til outputsatsen, så outputantallet i usage kan være større enn den synlige teksten. PoYos publiserte skjemaer har ikke noe felt for tenkenivå; feltet for maks. output er den dokumenterte lengdekontrollen.

Les forbruket og beregn kostnaden for en forespørsel

PoYo priser gemini-4-carbon til $1.60 per 1M input-tokens, $8.00 per 1M output-tokens og $0.08 per 1M cache-leste tokens (1 kreditt = $0.005).

FormatInput-tokensOutput-tokens (inkl. thinking)
Chat Completionsusage.prompt_tokensusage.total_tokens − usage.prompt_tokens
Gemini NativeusageMetadata.promptTokenCounttotalTokenCount − promptTokenCount (svar pluss 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

Målt eksempel (PoYo produksjon, 16. november 2026): en ikke-strømmende /v1/chat/completions-forespørsel som ba gemini-4-carbon gjennomgå en Python-funksjon på 40 linjer, returnerte prompt_tokens: 480, completion_tokens: 1094 og total_tokens: 1574 på 6,3 sekunder, uten rapporterte thinking-tokens. PoYo belastet 1,904 kreditter, samme tall som formelen gir.

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)

Dette priser hver prompt-token til full inputsats. Cache-leste tokens faktureres til $0.08 per 1M, men PoYos svarskjemaer dokumenterer ikke et felt for cachede tokens, så se på formelen som en øvre grense. Kostnadsscenarier i stor skala finner du i Gemini 4 Carbon API-priser.

Feil som er verdt å håndtere

LLM-endepunkter på PoYo returnerer ekte HTTP-statuskoder:

HTTPÅrsakHva du gjør
400Manglende eller ugyldig felt; brødtekst {"code": 400, "error": {"type": "validation_error", ...}}Rett forespørselen; les error.details
400Feil format for denne modellen; meldingen lister opp støttede URI-erBruk Chat Completions eller Gemini Native
400Gemini Native-feil i Googles struktur {"error": {"code": 400, "message": "...", "status": "INVALID_ARGUMENT"}}Rett contents / generationConfig
401Manglende eller ugyldig API-nøkkelSjekk Authorization-headeren
402Ikke nok kreditterFyll på før du prøver igjen
404Ukjent modell-ID (model_not_found)Sjekk stavemåten: gemini-4-carbon
500 / 502 / 503Server- eller upstream-feilPrøv igjen med eksponentiell backoff

PoYos dokumentasjon sier at LLM-endepunkter for øyeblikket ikke har rate limiting, men PoYos generelle feilkoder inkluderer 429. Håndter den med en pause og et nytt forsøk. Med OpenAI SDK-et fanger du openai.APIStatusError og forgrener på status_code. Se PoYos feilkoder for fullstendige brødtekster.

Sjekkliste før du lanserer

  • Hold POYO_API_KEY på serversiden; legg den aldri i nettleser- eller mobilkode.
  • Sett alltid max_tokens eller maxOutputTokens, og logg finish_reason / finishReason slik at avkortede svar blir synlige.
  • Lagre usage-blokken fra hvert svar sammen med forespørsels-ID-en du tildeler, slik at du kan avstemme forbruket per funksjon.
  • Legg lang, stabil kontekst (repository-filer, dokumenter) først og det skiftende spørsmålet sist, slik at implisitt caching har en sjanse til å slå inn.
  • Prøv bare igjen ved 5xx- og 429-svar; en 400 vil feile igjen til brødteksten endres.

For agentløkker, verktøyoutput og mønstre med lang kontekst, fortsett med Gemini 4 Carbon API for kodeagenter. For å avgjøre når Argon er nok, les Gemini 4 Carbon API vs Gemini 4 Argon.

Ofte stilte spørsmål

Hvordan kaller jeg Gemini 4 Carbon API i Python?

Bruk OpenAI SDK-et med base_url="https://api.poyo.ai/v1", PoYo-nøkkelen din og model="gemini-4-carbon". For native forespørsler sender du en POST til /v1beta/models/gemini-4-carbon:generateContent med requests.

Støtter Gemini 4 Carbon API strømming?

Ja. Sett "stream": true på Chat Completions, eller kall :streamGenerateContent i det native formatet. Begge returnerer server-sent events som avsluttes med data: [DONE].

Hvordan sender jeg et bilde til Gemini 4 Carbon API?

Bruk det Gemini-native endepunktet med en inlineData-del (mimeType pluss base64-kodet data) etter tekstdelen din. Chat Completions på PoYo tar bare strenginnhold.

Hvordan begrenser jeg output-tokens i Gemini 4 Carbon API?

Sett max_tokens (Chat Completions) eller generationConfig.maxOutputTokens (native). Thinking-tokens faktureres som output, så sammenlign outputantallet i usage med den synlige teksten når du velger taket.

Hvorfor returnerer Gemini 4 Carbon API 400 på /v1/responses?

gemini-4-carbon støtter bare Chat Completions og Gemini Native på PoYo. Andre formater returnerer 400 med listen over støttede URI-er.

Share: