how-tos

Gemini 4 Carbon API: Panduan Permintaan Pertama dengan cURL, Python & Gemini Native

Poyo.ai Team
9 min read
Share:

Panduan Gemini 4 Carbon API: permintaan pertama dengan cURL dan Python

Panduan Gemini 4 Carbon API ini membawa Anda dari kunci API ke permintaan yang berfungsi dengan cURL, SDK OpenAI untuk Python, dan format native generateContent milik Google, semuanya dengan ID model gemini-4-carbon. Setiap contoh mengikuti skema permintaan yang dipublikasikan PoYo per 16 November 2026. Anda bisa menguji prompt terlebih dahulu di halaman model Gemini 4 Carbon.

Baru mengenal model ini? Mulailah dengan ikhtisar Gemini 4 Carbon API untuk batas dan posisinya.

Sebelum mulai

Buat kunci di dasbor PoYo dan simpan di server Anda:

export POYO_API_KEY="your-poyo-key"
FormatEndpointGunakan saat
Chat CompletionsPOST https://api.poyo.ai/v1/chat/completionsAnda sudah memakai SDK OpenAI, pesan hanya teks
Gemini NativePOST https://api.poyo.ai/v1beta/models/gemini-4-carbon:generateContentAnda membutuhkan part gambar atau file (inlineData)
Streaming Gemini NativePOST https://api.poyo.ai/v1beta/models/gemini-4-carbon:streamGenerateContentFormat native dengan server-sent events

Setiap permintaan mengirim Authorization: Bearer $POYO_API_KEY. Di PoYo, gemini-4-carbon tidak mendukung /v1/responses atau /v1/messages.

Permintaan Gemini 4 Carbon API pertama dengan 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 dan messages wajib diisi. Field opsional dalam skema PoYo: temperature (0–2), top_p (0–1; gunakan ini atau temperature, jangan keduanya), max_tokens, stream, stop (hingga 4 urutan), frequency_penalty dan presence_penalty (−2 hingga 2), serta n. content setiap pesan berupa string.

Responsnya adalah objek chat.completion standar: teks di choices[0].message.content, penyebab berhenti di choices[0].finish_reason, dan jumlah token di usage.prompt_tokens, usage.completion_tokens, dan usage.total_tokens.

Python dengan SDK OpenAI

Arahkan SDK ke PoYo dan jangan ubah apa pun selain itu:

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)

Berpindah dari gemini-4-argon, atau dari model lain yang mendukung Chat Completions di PoYo, hanya perlu mengubah satu baris pada model.

Streaming dengan SDK OpenAI

Dengan stream=True, PoYo mengirim event chat.completion.chunk dan diakhiri dengan data: [DONE]. Teks datang di choices[0].delta.content, dan chunk terakhir membawa finish_reason dan 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)

Format native generateContent Gemini

Endpoint native menerima model di path URL. Body memakai contents (masing-masing dengan role user atau model dan array parts), ditambah generationConfig opsional (temperature, topP, topK, maxOutputTokens, stopSequences) dan 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}
  }'

Responsnya adalah objek GenerateContentResponse milik Google, dikembalikan secara langsung. Teks ada di candidates[].content.parts[].text dan jumlah token di usageMetadata. Model thinking dapat menambahkan part dengan thought: true atau thoughtSignature, jadi lewati part yang tidak berisi teks:

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 native

Ganti metodenya menjadi :streamGenerateContent. Responsnya berupa text/event-stream: setiap baris data: adalah GenerateContentResponse parsial, event terakhir membawa finishReason, dan stream diakhiri dengan data: [DONE]. Parameter query alt=sse diterima tetapi tidak wajib.

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 multimodal melalui Gemini 4 Carbon API

Google mencantumkan teks, gambar, audio, video, dan PDF sebagai jenis input Gemini 4 Carbon. Di PoYo, input file dikirim melalui format native sebagai part inlineData dengan mimeType dan data base64. Dokumentasi PoYo menampilkan contoh gambar, dan menyarankan agar instruksi teks diletakkan sebelum part media:

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

Skema Chat Completions PoYo mendokumentasikan content sebagai string, jadi jangan kirim array gambar bergaya OpenAI ke /v1/chat/completions. Untuk PDF, audio, dan video, dokumentasi PoYo tidak menampilkan contoh terpisah; kirim satu file kecil terlebih dahulu dan periksa responsnya sebelum Anda membangun pipeline di atasnya. Media ikut dihitung dalam prompt: usageMetadata.promptTokensDetails merinci token prompt per modalitas.

Mengatur output maksimum

FormatFieldTanda bahwa output terpotong
Chat Completionsmax_tokensfinish_reason: "length"
Gemini NativegenerationConfig.maxOutputTokensfinishReason selain STOP

Google mencantumkan 65.536 token output sebagai batas sinkron default dan konteks 1.048.576 token yang dibagi antara input dan output. Halaman harga Google menyebutkan bahwa token thinking ditagih dengan tarif output, sehingga jumlah output di usage bisa lebih besar daripada teks yang terlihat. Skema yang dipublikasikan PoYo tidak memiliki field tingkat thinking; field output maksimum adalah kontrol panjang yang terdokumentasi.

Membaca usage dan menghitung biaya permintaan

PoYo mematok harga gemini-4-carbon sebesar $1.60 per 1M token input, $8.00 per 1M token output, dan $0.08 per 1M token baca cache (1 kredit = $0.005).

FormatToken inputToken output (termasuk thinking)
Chat Completionsusage.prompt_tokensusage.total_tokens − usage.prompt_tokens
Gemini NativeusageMetadata.promptTokenCounttotalTokenCount − promptTokenCount (jawaban ditambah 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

Contoh terukur (produksi PoYo, 16 November 2026): permintaan /v1/chat/completions tanpa streaming yang meminta gemini-4-carbon meninjau fungsi Python 40 baris mengembalikan prompt_tokens: 480, completion_tokens: 1094, dan total_tokens: 1574 dalam 6,3 detik, tanpa thinking token yang dilaporkan. PoYo menagih 1,904 kredit, sama dengan hasil rumus.

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)

Perhitungan ini mengenakan tarif input penuh untuk setiap token prompt. Token baca cache ditagih $0.08 per 1M, tetapi skema respons PoYo tidak mendokumentasikan field token cache, jadi anggap rumus ini sebagai batas atas. Skenario biaya dalam skala besar ada di Harga Gemini 4 Carbon API.

Error yang perlu ditangani

Endpoint LLM di PoYo mengembalikan kode status HTTP yang sebenarnya:

HTTPPenyebabYang perlu dilakukan
400Field hilang atau tidak valid; body {"code": 400, "error": {"type": "validation_error", ...}}Perbaiki permintaan; baca error.details
400Format salah untuk model ini; pesan mencantumkan URI yang didukungGunakan Chat Completions atau Gemini Native
400Error Gemini Native, bentuk Google {"error": {"code": 400, "message": "...", "status": "INVALID_ARGUMENT"}}Perbaiki contents / generationConfig
401Kunci API hilang atau tidak validPeriksa header Authorization
402Kredit tidak cukupIsi ulang sebelum mencoba lagi
404ID model tidak dikenal (model_not_found)Periksa ejaannya: gemini-4-carbon
500 / 502 / 503Error server atau upstreamCoba lagi dengan exponential backoff

Dokumentasi PoYo menyebutkan bahwa endpoint LLM saat ini tidak dibatasi rate limit, tetapi kode error umum PoYo mencakup 429. Tangani dengan menunggu lalu mencoba lagi. Dengan SDK OpenAI, tangkap openai.APIStatusError dan bercabang berdasarkan status_code. Lihat kode error PoYo untuk body lengkapnya.

Checklist sebelum rilis

  • Simpan POYO_API_KEY di sisi server; jangan pernah menyertakannya di kode browser atau aplikasi mobile.
  • Selalu atur max_tokens atau maxOutputTokens, dan catat finish_reason / finishReason agar jawaban yang terpotong terlihat.
  • Simpan blok usage dari setiap respons bersama ID permintaan yang Anda tetapkan, agar Anda bisa merekonsiliasi pengeluaran per fitur.
  • Letakkan konteks panjang yang stabil (file repositori, dokumen) di awal dan pertanyaan yang berubah di akhir, agar caching implisit berpeluang diterapkan.
  • Ulangi hanya respons 5xx dan 429; respons 400 akan gagal lagi sampai body-nya diubah.

Untuk loop agen, output tool, dan pola konteks panjang, lanjutkan ke Gemini 4 Carbon API untuk agen coding. Untuk memutuskan kapan Argon sudah cukup, baca Gemini 4 Carbon API vs Gemini 4 Argon.

Pertanyaan yang sering diajukan

Bagaimana cara memanggil Gemini 4 Carbon API di Python?

Gunakan SDK OpenAI dengan base_url="https://api.poyo.ai/v1", kunci PoYo Anda, dan model="gemini-4-carbon". Untuk permintaan native, kirim POST ke /v1beta/models/gemini-4-carbon:generateContent dengan requests.

Apakah Gemini 4 Carbon API mendukung streaming?

Ya. Atur "stream": true di Chat Completions, atau panggil :streamGenerateContent dalam format native. Keduanya mengembalikan server-sent events yang diakhiri dengan data: [DONE].

Bagaimana cara mengirim gambar ke Gemini 4 Carbon API?

Gunakan endpoint native Gemini dengan part inlineData (mimeType ditambah data base64) setelah part teks Anda. Chat Completions di PoYo hanya menerima konten berupa string.

Bagaimana cara membatasi token output Gemini 4 Carbon API?

Atur max_tokens (Chat Completions) atau generationConfig.maxOutputTokens (native). Token thinking ditagih sebagai output, jadi bandingkan jumlah output di usage dengan teks yang terlihat saat menentukan batasnya.

Mengapa Gemini 4 Carbon API mengembalikan 400 di /v1/responses?

Di PoYo, gemini-4-carbon hanya mendukung Chat Completions dan Gemini Native. Format lain mengembalikan 400 beserta daftar URI yang didukung.

Share: