how-tos

Gemini 4 Carbon API Rehberi: cURL, Python ve Gemini Native ile İlk İstek

Poyo.ai Team
9 min read
Share:

Gemini 4 Carbon API rehberi: cURL ve Python ile ilk istek

Bu Gemini 4 Carbon API rehberi, bir API anahtarından başlayıp cURL, Python OpenAI SDK ve Google'ın yerel generateContent biçimiyle çalışan bir isteğe kadar sizi adım adım götürür; tüm örneklerde model kimliği gemini-4-carbon'dır. Her örnek, PoYo'nun 16 Kasım 2026 itibarıyla yayımladığı istek şemasını esas alır. İstemleri önce Gemini 4 Carbon model sayfasında test edebilirsiniz.

Modelle yeni mi tanışıyorsunuz? Limitler ve konumlandırma için Gemini 4 Carbon API genel bakışı ile başlayın.

Başlamadan önce

PoYo panelinde bir anahtar oluşturun ve onu sunucunuzda tutun:

export POYO_API_KEY="your-poyo-key"
BiçimUç noktaNe zaman kullanılır
Chat CompletionsPOST https://api.poyo.ai/v1/chat/completionsZaten OpenAI SDK kullanıyorsanız, yalnızca metin içeren mesajlar
Gemini NativePOST https://api.poyo.ai/v1beta/models/gemini-4-carbon:generateContentGörsel veya dosya parçalarına (inlineData) ihtiyacınız varsa
Gemini Native akışPOST https://api.poyo.ai/v1beta/models/gemini-4-carbon:streamGenerateContentServer-sent events ile yerel biçim

Her istek Authorization: Bearer $POYO_API_KEY gönderir. gemini-4-carbon, PoYo'da /v1/responses veya /v1/messages desteklemez.

cURL ile ilk Gemini 4 Carbon API isteği

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 ve messages zorunludur. PoYo şemasındaki isteğe bağlı alanlar: temperature (0–2), top_p (0–1; bunu ya da temperature alanını kullanın, ikisini birden değil), max_tokens, stream, stop (en fazla 4 dizi), frequency_penalty ve presence_penalty (−2 ile 2 arası) ve n. Her mesajın content alanı bir dizedir.

Yanıt standart bir chat.completion nesnesidir: metin choices[0].message.content alanında, durma nedeni choices[0].finish_reason alanında, sayılar ise usage.prompt_tokens, usage.completion_tokens ve usage.total_tokens alanlarındadır.

OpenAI SDK ile Python

SDK'yı PoYo'ya yönlendirin, başka hiçbir şeyi değiştirmeyin:

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)

gemini-4-argon veya PoYo'da Chat Completions'ı destekleyen başka bir modelden geçiş, model alanında tek satırlık bir değişikliktir.

OpenAI SDK ile akış

stream=True ile PoYo, chat.completion.chunk olayları gönderir ve data: [DONE] ile bitirir. Metin choices[0].delta.content alanında gelir; son parça finish_reason ve usage bilgisini taşır:

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)

Gemini-native generateContent biçimi

Yerel uç nokta, modeli URL yolunda alır. Gövde contents alanını (her biri user veya model değerli bir role ve bir parts dizisi içerir), ayrıca isteğe bağlı generationConfig (temperature, topP, topK, maxOutputTokens, stopSequences) ve safetySettings alanlarını kullanır:

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}
  }'

Yanıt, doğrudan döndürülen Google GenerateContentResponse nesnesidir. Metin candidates[].content.parts[].text alanında, sayılar usageMetadata alanındadır. Düşünen modeller thought: true veya thoughtSignature içeren parçalar ekleyebilir; bu yüzden metin içermeyen parçaları atlayın:

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

Yerel akış

Yöntemi :streamGenerateContent ile değiştirin. Yanıt text/event-stream türündedir: her data: satırı kısmi bir GenerateContentResponse nesnesidir, son olay finishReason bilgisini taşır ve akış data: [DONE] ile biter. alt=sse sorgu parametresi kabul edilir ama zorunlu değildir.

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)

Gemini 4 Carbon API ile çok modlu girdi

Google, Gemini 4 Carbon için girdi türleri olarak metin, görsel, ses, video ve PDF listeler. PoYo'da dosya girdisi, yerel biçim üzerinden mimeType ve base64 data içeren bir inlineData parçası olarak gönderilir. PoYo belgeleri bir görsel örneği gösterir ve metin talimatlarının medya parçalarından önce yazılmasını önerir:

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

PoYo'nun Chat Completions şeması content alanını dize olarak tanımlar; bu yüzden /v1/chat/completions uç noktasına OpenAI tarzı görsel dizileri göndermeyin. PDF, ses ve video için PoYo belgelerinde ayrı bir örnek yoktur; bunun üzerine bir işlem hattı kurmadan önce küçük bir dosya gönderip yanıtı kontrol edin. Medya, isteme dahil sayılır: usageMetadata.promptTokensDetails istem token'larını modaliteye göre ayrıştırır.

Maksimum çıktıyı ayarlama

BiçimAlanÇıktının kesildiğini gösteren sinyal
Chat Completionsmax_tokensfinish_reason: "length"
Gemini NativegenerationConfig.maxOutputTokensSTOP dışında bir finishReason

Google, varsayılan senkron üst sınır olarak 65.536 çıktı token'ı ve girdi ile çıktı tarafından paylaşılan 1.048.576 token'lık bir bağlam listeler. Google'ın fiyat sayfasına göre düşünme token'ları çıktı ücretinden faturalandırılır; dolayısıyla usage içindeki çıktı sayısı görünen metinden büyük olabilir. PoYo'nun yayımladığı şemalarda düşünme seviyesi alanı yoktur; belgelenmiş uzunluk kontrolü maksimum çıktı alanıdır.

Kullanımı okuyun ve isteğin maliyetini hesaplayın

PoYo, gemini-4-carbon için 1M girdi token'ı başına $1.60, 1M çıktı token'ı başına $8.00 ve 1M önbellek okuma token'ı başına $0.08 fiyat uygular (1 kredi = $0.005).

BiçimGirdi token'larıÇıktı token'ları (düşünme dahil)
Chat Completionsusage.prompt_tokensusage.total_tokens − usage.prompt_tokens
Gemini NativeusageMetadata.promptTokenCounttotalTokenCount − promptTokenCount (yanıt artı 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

Ölçülmüş örnek (PoYo üretim ortamı, 16 Kasım 2026): gemini-4-carbon modelinden 40 satırlık bir Python fonksiyonunu incelemesini isteyen akışsız bir /v1/chat/completions isteği 6,3 saniyede prompt_tokens: 480, completion_tokens: 1094 ve total_tokens: 1574 döndürdü; düşünme token'ı raporlanmadı. PoYo bu istek için 1,904 kredi düştü; formülün verdiği değerle aynı.

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)

Bu hesap, her istem token'ını tam girdi ücretiyle fiyatlandırır. Önbellek okuma token'ları 1M başına $0.08'den faturalandırılır, ancak PoYo'nun yanıt şemaları önbelleğe alınmış token'lar için bir alan tanımlamaz; bu yüzden bu formülü bir üst sınır olarak kabul edin. Ölçekli maliyet senaryoları Gemini 4 Carbon API fiyatlandırması yazısında yer alıyor.

Ele alınması gereken hatalar

PoYo'daki LLM uç noktaları gerçek HTTP durum kodları döndürür:

HTTPNedenNe yapılmalı
400Eksik veya geçersiz alan; gövde {"code": 400, "error": {"type": "validation_error", ...}}İsteği düzeltin; error.details alanını okuyun
400Bu model için yanlış biçim; mesaj desteklenen URI'leri listelerChat Completions veya Gemini Native kullanın
400Gemini Native hatası, Google yapısında {"error": {"code": 400, "message": "...", "status": "INVALID_ARGUMENT"}}contents / generationConfig alanlarını düzeltin
401Eksik veya geçersiz API anahtarıAuthorization başlığını kontrol edin
402Yetersiz krediYeniden denemeden önce bakiye yükleyin
404Bilinmeyen model kimliği (model_not_found)Yazımı kontrol edin: gemini-4-carbon
500 / 502 / 503Sunucu veya üst akış (upstream) hatasıÜstel geri çekilmeyle (exponential backoff) yeniden deneyin

PoYo belgelerine göre LLM uç noktalarında şu anda hız sınırı yoktur, ancak PoYo'nun genel hata kodları arasında 429 de bulunur. Bunu bekleyip yeniden deneyerek ele alın. OpenAI SDK ile openai.APIStatusError yakalayın ve status_code değerine göre dallanın. Tam gövdeler için PoYo hata kodlarına bakın.

Yayına almadan önce kontrol listesi

  • POYO_API_KEY değerini sunucu tarafında tutun; asla tarayıcı veya mobil kodla birlikte dağıtmayın.
  • Her zaman max_tokens veya maxOutputTokens ayarlayın ve kesilen yanıtların görünür olması için finish_reason / finishReason değerini loglayın.
  • Her yanıtın usage bloğunu, atadığınız istek kimliğinin yanında saklayın; böylece harcamayı özellik bazında mutabakat edebilirsiniz.
  • Uzun ve sabit bağlamı (depo dosyaları, dokümanlar) başa, değişen soruyu sona koyun; bu, örtük önbelleğin devreye girmesine fırsat tanır.
  • Yalnızca 5xx ve 429 yanıtlarını yeniden deneyin; 400 hatası gövde değişene kadar tekrar başarısız olur.

Ajan döngüleri, araç çıktıları ve uzun bağlam kalıpları için kodlama ajanları için Gemini 4 Carbon API yazısıyla devam edin. Argon'un ne zaman yeterli olduğuna karar vermek için Gemini 4 Carbon API ve Gemini 4 Argon karşılaştırmasını okuyun.

Sıkça sorulan sorular

Gemini 4 Carbon API'yi Python'da nasıl çağırırım?

OpenAI SDK'yı base_url="https://api.poyo.ai/v1", PoYo anahtarınız ve model="gemini-4-carbon" ile kullanın. Yerel istekler için requests ile /v1beta/models/gemini-4-carbon:generateContent adresine POST gönderin.

Gemini 4 Carbon API akışı destekliyor mu?

Evet. Chat Completions'ta "stream": true ayarlayın veya yerel biçimde :streamGenerateContent çağırın. İkisi de data: [DONE] ile biten server-sent events döndürür.

Gemini 4 Carbon API'ye nasıl görsel gönderirim?

Gemini-native uç noktasını, metin parçanızdan sonra gelen bir inlineData parçasıyla (mimeType artı base64 data) kullanın. PoYo'daki Chat Completions yalnızca dize içerik kabul eder.

Gemini 4 Carbon API çıktı token'larını nasıl sınırlarım?

max_tokens (Chat Completions) veya generationConfig.maxOutputTokens (yerel) ayarlayın. Düşünme token'ları çıktı olarak faturalandırılır; bu yüzden üst sınırı seçerken usage içindeki çıktı sayısını görünen metinle karşılaştırın.

Gemini 4 Carbon API neden /v1/responses için 400 döndürüyor?

gemini-4-carbon, PoYo'da yalnızca Chat Completions ve Gemini Native'i destekler. Diğer biçimler, desteklenen URI'lerin listesiyle birlikte 400 döndürür.

Share: