how-tos

Gemini 4 Carbon API: przewodnik — pierwsze żądanie w cURL, Pythonie i Gemini Native

Poyo.ai Team
9 min read
Share:

Przewodnik po Gemini 4 Carbon API: pierwsze żądanie w cURL i Pythonie

Ten przewodnik po Gemini 4 Carbon API prowadzi od klucza API do działającego żądania w cURL, w Python OpenAI SDK i w natywnym formacie Google generateContent, za każdym razem z ID modelu gemini-4-carbon. Każdy przykład odpowiada opublikowanemu schematowi żądań PoYo według stanu z 16 listopada 2026. Prompty możesz najpierw przetestować na stronie modelu Gemini 4 Carbon.

Nie znasz jeszcze tego modelu? Zacznij od przeglądu Gemini 4 Carbon API, w którym opisano limity i pozycjonowanie.

Zanim zaczniesz

Utwórz klucz w panelu PoYo i trzymaj go na serwerze:

export POYO_API_KEY="your-poyo-key"
FormatEndpointKiedy go używać
Chat CompletionsPOST https://api.poyo.ai/v1/chat/completionsJuż używasz OpenAI SDK, wiadomości tylko tekstowe
Gemini NativePOST https://api.poyo.ai/v1beta/models/gemini-4-carbon:generateContentPotrzebujesz części z obrazami lub plikami (inlineData)
Streaming Gemini NativePOST https://api.poyo.ai/v1beta/models/gemini-4-carbon:streamGenerateContentFormat natywny z server-sent events

Każde żądanie wysyła Authorization: Bearer $POYO_API_KEY. W PoYo gemini-4-carbon nie obsługuje /v1/responses ani /v1/messages.

Pierwsze żądanie do Gemini 4 Carbon API w 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
  }'

Pola model i messages są wymagane. Pola opcjonalne w schemacie PoYo: temperature (0–2), top_p (0–1; używaj jego albo temperature, nie obu naraz), max_tokens, stream, stop (do 4 sekwencji), frequency_penalty i presence_penalty (od −2 do 2) oraz n. Pole content każdej wiadomości jest ciągiem znaków.

Odpowiedź to standardowy obiekt chat.completion: tekst w choices[0].message.content, przyczyna zatrzymania w choices[0].finish_reason, a liczniki w usage.prompt_tokens, usage.completion_tokens i usage.total_tokens.

Python z OpenAI SDK

Skieruj SDK na PoYo i nie zmieniaj niczego więcej:

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)

Przejście z gemini-4-argon lub dowolnego innego modelu obsługującego Chat Completions w PoYo to zmiana jednej linii w model.

Streaming przez OpenAI SDK

Przy stream=True PoYo wysyła zdarzenia chat.completion.chunk i kończy strumień linią data: [DONE]. Tekst przychodzi w choices[0].delta.content, a ostatni chunk zawiera finish_reason i 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)

Natywny format generateContent Gemini

Natywny endpoint przyjmuje model w ścieżce URL. Treść żądania zawiera contents (każdy element z role — user lub model — i tablicą parts) oraz opcjonalne generationConfig (temperature, topP, topK, maxOutputTokens, stopSequences) i 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}
  }'

Odpowiedź to obiekt Google GenerateContentResponse, zwracany bezpośrednio. Tekst jest w candidates[].content.parts[].text, a liczniki w usageMetadata. Modele z myśleniem mogą dodawać części z thought: true lub thoughtSignature, więc pomijaj części bez tekstu:

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 natywny

Zmień metodę na :streamGenerateContent. Odpowiedź ma typ text/event-stream: każda linia data: to częściowy GenerateContentResponse, ostatnie zdarzenie zawiera finishReason, a strumień kończy się linią data: [DONE]. Parametr zapytania alt=sse jest akceptowany, ale niewymagany.

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)

Wejście multimodalne w Gemini 4 Carbon API

Google wymienia tekst, obraz, audio, wideo i PDF jako typy wejścia dla Gemini 4 Carbon. W PoYo pliki przekazuje się przez format natywny jako część inlineData z mimeType i data w base64. Dokumentacja PoYo pokazuje przykład z obrazem i zaleca umieszczanie instrukcji tekstowych przed częściami z mediami:

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

Schemat Chat Completions w PoYo opisuje content jako ciąg znaków, więc nie wysyłaj do /v1/chat/completions tablic obrazów w stylu OpenAI. Dla PDF, audio i wideo dokumentacja PoYo nie podaje osobnego przykładu; najpierw wyślij jeden mały plik i sprawdź odpowiedź, zanim zbudujesz na tym pipeline. Media wliczają się do promptu: usageMetadata.promptTokensDetails rozbija tokeny promptu według modalności.

Ustawianie maksymalnego wyjścia

FormatPoleSygnał, że wyjście zostało ucięte
Chat Completionsmax_tokensfinish_reason: "length"
Gemini NativegenerationConfig.maxOutputTokensfinishReason inny niż STOP

Google podaje 65,536 tokenów wyjściowych jako domyślny limit dla żądań synchronicznych oraz kontekst 1,048,576 tokenów wspólny dla wejścia i wyjścia. Strona cennika Google mówi, że tokeny myślenia są rozliczane według stawki za wyjście, więc liczba tokenów wyjściowych w usage może być większa niż widoczny tekst. Opublikowane schematy PoYo nie mają pola poziomu myślenia; udokumentowanym sposobem kontroli długości jest pole maksymalnego wyjścia.

Odczyt usage i obliczanie kosztu żądania

PoYo wycenia gemini-4-carbon na $1.60 za 1M tokenów wejściowych, $8.00 za 1M tokenów wyjściowych i $0.08 za 1M tokenów odczytu z cache (1 kredyt = $0.005).

FormatTokeny wejścioweTokeny wyjściowe (wraz z myśleniem)
Chat Completionsusage.prompt_tokensusage.total_tokens − usage.prompt_tokens
Gemini NativeusageMetadata.promptTokenCounttotalTokenCount − promptTokenCount (odpowiedź plus 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

Przykład zmierzony (produkcja PoYo, 16 listopada 2026): żądanie /v1/chat/completions bez streamingu, w którym gemini-4-carbon miał przejrzeć 40-wierszową funkcję w Pythonie, zwróciło prompt_tokens: 480, completion_tokens: 1094 i total_tokens: 1574 w 6,3 sekundy, bez zgłoszonych tokenów rozumowania. PoYo naliczył 1,904 kredytu, tyle samo, ile daje wzór.

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)

Ten wzór wycenia każdy token promptu po pełnej stawce za wejście. Tokeny odczytu z cache kosztują $0.08 za 1M, ale schematy odpowiedzi PoYo nie opisują pola z tokenami z cache, więc traktuj ten wzór jako górne oszacowanie. Scenariusze kosztów w skali znajdziesz w artykule Cennik Gemini 4 Carbon API.

Błędy, które warto obsłużyć

Endpointy LLM w PoYo zwracają prawdziwe kody statusu HTTP:

HTTPPrzyczynaCo zrobić
400Brakujące lub nieprawidłowe pole; treść {"code": 400, "error": {"type": "validation_error", ...}}Popraw żądanie; sprawdź error.details
400Zły format dla tego modelu; komunikat wymienia obsługiwane URIUżyj Chat Completions lub Gemini Native
400Błąd Gemini Native w formacie Google {"error": {"code": 400, "message": "...", "status": "INVALID_ARGUMENT"}}Popraw contents / generationConfig
401Brak klucza API lub nieprawidłowy kluczSprawdź nagłówek Authorization
402Niewystarczająca liczba kredytówDoładuj konto przed ponowieniem
404Nieznany ID modelu (model_not_found)Sprawdź pisownię: gemini-4-carbon
500 / 502 / 503Błąd serwera lub dostawcy upstreamPonów z wykładniczym backoffem

Dokumentacja PoYo mówi, że endpointy LLM obecnie nie mają limitów częstotliwości żądań, ale ogólne kody błędów PoYo obejmują 429. Obsłuż go odczekaniem i ponowieniem. W OpenAI SDK przechwytuj openai.APIStatusError i rozgałęziaj logikę według status_code. Pełne treści odpowiedzi znajdziesz w kodach błędów PoYo.

Lista kontrolna przed wdrożeniem

  • Trzymaj POYO_API_KEY po stronie serwera; nigdy nie umieszczaj go w kodzie przeglądarkowym ani mobilnym.
  • Zawsze ustawiaj max_tokens lub maxOutputTokens i loguj finish_reason / finishReason, aby ucięte odpowiedzi były widoczne.
  • Zapisuj blok usage każdej odpowiedzi obok nadanego przez siebie ID żądania, aby rozliczać wydatki według funkcji.
  • Umieszczaj długi, stabilny kontekst (pliki repozytorium, dokumenty) na początku, a zmieniające się pytanie na końcu — to daje szansę zadziałania niejawnemu cache'owaniu.
  • Ponawiaj tylko odpowiedzi 5xx i 429; żądanie z 400 będzie się nie udawać, dopóki nie zmienisz jego treści.

O pętlach agentów, wyjściu narzędzi i wzorcach pracy z długim kontekstem przeczytasz w artykule Gemini 4 Carbon API dla agentów programistycznych. Aby ocenić, kiedy Argon wystarczy, przeczytaj Gemini 4 Carbon API vs Gemini 4 Argon.

Najczęściej zadawane pytania

Jak wywołać Gemini 4 Carbon API w Pythonie?

Użyj OpenAI SDK z base_url="https://api.poyo.ai/v1", swoim kluczem PoYo i model="gemini-4-carbon". Dla żądań natywnych wyślij POST na /v1beta/models/gemini-4-carbon:generateContent za pomocą requests.

Czy Gemini 4 Carbon API obsługuje streaming?

Tak. Ustaw "stream": true w Chat Completions albo wywołaj :streamGenerateContent w formacie natywnym. Oba zwracają server-sent events zakończone linią data: [DONE].

Jak wysłać obraz do Gemini 4 Carbon API?

Użyj natywnego endpointu Gemini z częścią inlineData (mimeType plus data w base64) po części tekstowej. Chat Completions w PoYo przyjmuje wyłącznie content w postaci ciągu znaków.

Jak ograniczyć liczbę tokenów wyjściowych Gemini 4 Carbon API?

Ustaw max_tokens (Chat Completions) lub generationConfig.maxOutputTokens (format natywny). Tokeny myślenia są rozliczane jako wyjście, więc przy wyborze limitu porównaj liczbę tokenów wyjściowych w usage z widocznym tekstem.

Dlaczego Gemini 4 Carbon API zwraca 400 na /v1/responses?

W PoYo gemini-4-carbon obsługuje tylko Chat Completions i Gemini Native. Inne formaty zwracają 400 z listą obsługiwanych URI.

Share: