
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"
| Format | Endpoint | Gunakan saat |
|---|---|---|
| Chat Completions | POST https://api.poyo.ai/v1/chat/completions | Anda sudah memakai SDK OpenAI, pesan hanya teks |
| Gemini Native | POST https://api.poyo.ai/v1beta/models/gemini-4-carbon:generateContent | Anda membutuhkan part gambar atau file (inlineData) |
| Streaming Gemini Native | POST https://api.poyo.ai/v1beta/models/gemini-4-carbon:streamGenerateContent | Format 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
| Format | Field | Tanda bahwa output terpotong |
|---|---|---|
| Chat Completions | max_tokens | finish_reason: "length" |
| Gemini Native | generationConfig.maxOutputTokens | finishReason 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).
| Format | Token input | Token output (termasuk thinking) |
|---|---|---|
| Chat Completions | usage.prompt_tokens | usage.total_tokens − usage.prompt_tokens |
| Gemini Native | usageMetadata.promptTokenCount | totalTokenCount − 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:
| HTTP | Penyebab | Yang perlu dilakukan |
|---|---|---|
| 400 | Field hilang atau tidak valid; body {"code": 400, "error": {"type": "validation_error", ...}} | Perbaiki permintaan; baca error.details |
| 400 | Format salah untuk model ini; pesan mencantumkan URI yang didukung | Gunakan Chat Completions atau Gemini Native |
| 400 | Error Gemini Native, bentuk Google {"error": {"code": 400, "message": "...", "status": "INVALID_ARGUMENT"}} | Perbaiki contents / generationConfig |
| 401 | Kunci API hilang atau tidak valid | Periksa header Authorization |
| 402 | Kredit tidak cukup | Isi ulang sebelum mencoba lagi |
| 404 | ID model tidak dikenal (model_not_found) | Periksa ejaannya: gemini-4-carbon |
| 500 / 502 / 503 | Error server atau upstream | Coba 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_KEYdi sisi server; jangan pernah menyertakannya di kode browser atau aplikasi mobile. - Selalu atur
max_tokensataumaxOutputTokens, dan catatfinish_reason/finishReasonagar 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.