
Gemini 4 Carbon API adalah pilihan Google untuk pekerjaan coding yang paling sulit. Google membangunnya untuk debugging multi-langkah dan coding agentik horizon panjang, dan menyebutkan bahwa model ini menghabiskan lebih banyak token daripada Argon untuk mengeksplorasi, bernalar, dan menjalankan loop verifikasi. Panduan ini menghubungkan gemini-4-carbon (halaman model) ke agen coding melalui endpoint PoYo yang kompatibel dengan OpenAI. Agen ini melakukan streaming output, bisa membaca sebagian besar repositori, berhenti pada batas giliran dan anggaran dolar yang tegas, dan tahu kapan harus menyerahkan pekerjaan ke Argon.
Jika Anda belum mengirim permintaan pertama, mulailah dengan panduan Gemini 4 Carbon API.
Apa yang diberikan API ini kepada agen coding
| Item | Gemini 4 Carbon di PoYo |
|---|---|
| ID model | gemini-4-carbon |
| Endpoint agen yang dipakai di sini | POST https://api.poyo.ai/v1/chat/completions (SDK OpenAI, base_url="https://api.poyo.ai/v1") |
| Alternatif native | POST /v1beta/models/gemini-4-carbon:generateContent dan :streamGenerateContent |
| Jendela konteks | 1M token: teks, gambar, audio, video, PDF |
| Output maksimum per respons | 64K token |
| Streaming | "stream": true; chunk terakhir membawa finish_reason dan usage |
| Harga | $1.60 input / $8.00 output / $0.08 baca cache per 1M token (320 / 1,600 / 16 kredit) |
| Rate limit | Dokumentasi PoYo menyebutkan endpoint LLM saat ini tidak dibatasi rate limit |
| Error | 400 field tidak valid, 401 kunci salah, 402 kredit tidak cukup, 404 model tidak dikenal; ulangi 429 / 500 / 502 / 503 dengan backoff |
Dokumentasi Chat Completions mendokumentasikan field permintaan berikut: model, messages (content berupa string dengan role system, user, atau assistant), max_tokens, stream, temperature, top_p, stop, n, dan field penalti. Agen di bawah hanya memakai field-field tersebut.
Tool calling: apa yang terdokumentasi saat ini
PoYo mendokumentasikan tools untuk Anthropic Messages dan Responses. PoYo tidak mendokumentasikan tools atau deklarasi fungsi untuk model Gemini, baik di Chat Completions maupun Gemini Native. Responses tidak tersedia untuk gemini-4-carbon.
Karena itu, agen ini tidak mengirim array tools. Sebagai gantinya, agen memakai protokol aksi JSON di dalam konten pesan biasa. System prompt mencantumkan aksi yang diizinkan, model membalas dengan satu objek JSON per giliran, lalu kode Anda menjalankan aksi tersebut dan mengirim hasilnya kembali sebagai pesan user berikutnya. Cara ini berfungsi dengan model chat apa pun. Saat PoYo mendokumentasikan function calling native untuk Gemini, Anda bisa mengganti parser dengan tool call sungguhan dan mempertahankan bagian loop lainnya.
Ada pula manfaat keamanannya: model hanya bisa meminta empat aksi yang Anda tulis sendiri. Model tidak bisa menjalankan perintah shell sembarangan.
Input repo dengan konteks panjang: 1M masuk, 64K keluar
Jendela 1M token memungkinkan Anda mengirim sebagian besar repositori pada giliran pertama, alih-alih mengambil file satu per satu. Tabel peluncuran Google memberi alasan untuk memakainya: Carbon mencetak 96,2% di GraphWalks pada 256K–1M token, dibandingkan 84,2% untuk Argon. Tiga batas membentuk loop ini:
- Setiap giliran mengirim ulang seluruh riwayat. Snapshot ditagih lagi di setiap panggilan. Snapshot 300K token selama 12 giliran berarti setidaknya 3,6M token input, yaitu $5.76 dengan tarif $1.60 per 1M sebelum output apa pun.
- Output dibatasi 64K per respons. Minta satu file per aksi
write_file, bukan menulis ulang seluruh repo dalam satu balasan. - Ukur jumlah token, jangan menebak. PoYo tidak mendokumentasikan endpoint tokenizer. Baca
usage.prompt_tokensdari panggilan pertama, lalu sesuaikanMAX_SNAPSHOT_CHARSdengan anggaran token yang Anda inginkan.
Caching. Tabel harga PoYo memiliki tarif baca cache untuk Carbon ($0.08 per 1M, dibandingkan $1.60 untuk input baru), dan Google memberi diskon 95% untuk input yang di-cache. Dokumentasi PoYo tidak mendokumentasikan parameter permintaan untuk caching atau field usage token cache untuk model Gemini. Loop ini tidak mengirim parameter caching apa pun dan menganggarkan setiap token prompt dengan tarif input penuh. Mempertahankan system prompt dan snapshot sebagai prefiks yang tidak berubah tidak menambah biaya, dan tagihan Anda akan menunjukkan apakah ada pembacaan yang dikenai tarif cache.
Loop agen terbatas dalam Python
import json
import os
import subprocess
import time
from pathlib import Path
from openai import OpenAI, APIStatusError
client = OpenAI(api_key=os.environ["POYO_API_KEY"], base_url="https://api.poyo.ai/v1")
CARBON, ARGON = "gemini-4-carbon", "gemini-4-argon"
PRICE_IN, PRICE_OUT = 1.60, 8.00 # PoYo USD per 1M tokens, same for both (2026-11-16)
MAX_TURNS = 12
BUDGET_USD = 2.00
MAX_TOKENS_PER_TURN = 16_000 # Carbon allows up to 64,000
MAX_SNAPSHOT_CHARS = 400_000 # tune against usage.prompt_tokens
MAX_RESULT_CHARS = 20_000
REPO = Path("./my-repo").resolve()
SYSTEM = """You are a coding agent working in a Python repository.
Reply with exactly one JSON object and nothing else. Allowed actions:
{"action": "read_file", "path": "<relative path>"}
{"action": "write_file", "path": "<relative path>", "content": "<full file content>"}
{"action": "run_tests"}
{"action": "done", "summary": "<what changed and why>"}"""
def snapshot() -> str:
parts, total = [], 0
for p in sorted(REPO.rglob("*.py")):
block = f"### {p.relative_to(REPO)}\n{p.read_text(encoding='utf-8', errors='replace')}\n"
if total + len(block) > MAX_SNAPSHOT_CHARS:
break
parts.append(block)
total += len(block)
return "".join(parts)
def safe_path(rel: str) -> Path:
p = (REPO / rel).resolve()
if not p.is_relative_to(REPO):
raise ValueError("path outside repository")
return p
def execute(action: dict) -> str:
kind = action.get("action")
if kind == "read_file":
return safe_path(action["path"]).read_text(encoding="utf-8", errors="replace")
if kind == "write_file":
safe_path(action["path"]).write_text(action["content"], encoding="utf-8")
return "written"
if kind == "run_tests":
r = subprocess.run(["pytest", "-q"], cwd=REPO, capture_output=True, text=True, timeout=600)
return f"exit={r.returncode}\n{r.stdout}\n{r.stderr}"
raise ValueError(f"unknown action {kind!r}")
def call(model: str, messages: list):
"""One streamed turn. Returns (text, usage, finish_reason)."""
for attempt in range(4):
try:
stream = client.chat.completions.create(
model=model, messages=messages, max_tokens=MAX_TOKENS_PER_TURN, stream=True
)
text, usage, finish = [], None, None
for chunk in stream:
if chunk.choices:
choice = chunk.choices[0]
if choice.delta and choice.delta.content:
text.append(choice.delta.content)
print(choice.delta.content, end="", flush=True)
finish = choice.finish_reason or finish
if getattr(chunk, "usage", None):
usage = chunk.usage
return "".join(text), usage, finish
except APIStatusError as e:
if e.status_code in (429, 500, 502, 503) and attempt < 3:
time.sleep(2 ** attempt)
continue
raise # 400, 401, 402, 404: fix the request or the account, don't retry
def parse(text: str) -> dict:
t = text.strip()
if t.startswith("```"):
t = t.strip("`").removeprefix("json").strip()
return json.loads(t)
def run_agent(task: str, model: str = CARBON) -> dict:
messages = [
{"role": "system", "content": SYSTEM},
{"role": "user", "content": f"Repository snapshot:\n{snapshot()}\n\nTask: {task}"},
]
spent, last_prompt = 0.0, 0
for turn in range(1, MAX_TURNS + 1):
# Worst case for the next turn: at least last turn's input plus a full output
worst_next = last_prompt / 1e6 * PRICE_IN + MAX_TOKENS_PER_TURN / 1e6 * PRICE_OUT
if spent + worst_next > BUDGET_USD:
return {"status": "budget_stop", "turns": turn - 1, "spent_usd": round(spent, 4)}
text, usage, finish = call(model, messages)
if usage is None:
raise RuntimeError("no usage in stream; stopping so the budget stays enforceable")
spent += usage.prompt_tokens / 1e6 * PRICE_IN + usage.completion_tokens / 1e6 * PRICE_OUT
last_prompt = usage.prompt_tokens
messages.append({"role": "assistant", "content": text})
if finish == "length":
messages.append({"role": "user", "content": "Reply was cut off. Send one shorter JSON action."})
continue
try:
action = parse(text)
except json.JSONDecodeError:
messages.append({"role": "user", "content": "Reply with exactly one JSON object."})
continue
if action.get("action") == "done":
return {"status": "done", "summary": action.get("summary"), "turns": turn, "spent_usd": round(spent, 4)}
try:
result = execute(action)
except Exception as e: # report the failure to the model instead of crashing
result = f"error: {e}"
messages.append({"role": "user", "content": f"Result of {action.get('action')}:\n{result[:MAX_RESULT_CHARS]}"})
return {"status": "max_turns", "turns": MAX_TURNS, "spent_usd": round(spent, 4)}
if __name__ == "__main__":
print(run_agent("tests/test_parser.py::test_unicode fails. Find the root cause and fix it."))
Path.is_relative_to membutuhkan Python 3.9 atau lebih baru. Jalankan agen pada salinan atau branch repositori, karena write_file menimpa file.
Cara kerja pengaman biaya
| Pengaman | Yang dicegah | Asal angkanya |
|---|---|---|
MAX_TURNS | Loop yang tidak pernah memanggil done | Pilihan Anda; 12 adalah titik awal |
BUDGET_USD + pemeriksaan kasus terburuk | Pengeluaran melewati batas pada panggilan berikutnya | usage.prompt_tokens dan usage.completion_tokens dari chunk stream terakhir, dengan tarif PoYo $1.60 / $8.00 |
MAX_TOKENS_PER_TURN | Satu balasan yang tak terkendali | max_tokens, maksimal 64,000 untuk Carbon |
MAX_RESULT_CHARS | Log tes yang sangat besar membengkakkan setiap giliran berikutnya | Pemotongan sebelum hasil masuk ke riwayat |
usage is None → berhenti | Pengeluaran diam-diam yang tidak bisa Anda ukur | PoYo mendokumentasikan usage pada chunk stream terakhir |
402 tidak diulang | Badai retry saat saldo kosong | Kode error PoYo |
Google menghitung harga output Carbon termasuk token thinking, sehingga satu giliran bisa menagih output lebih banyak daripada JSON yang terlihat. Itulah sebabnya anggaran memakai completion_tokens dan tidak pernah menghitung karakter yang Anda terima. Estimasi ini menghitung semua input sebagai tanpa cache, jadi merupakan batas atas dari apa yang akan ditagih PoYo. Cocokkan dengan dasbor Anda untuk beberapa kali jalan pertama.
Pemeriksaan kasus terburuk bersifat konservatif. Dengan riwayat 300K token, satu giliran lagi berbiaya setidaknya $0.48 untuk input ditambah hingga $0.128 untuk output dengan max_tokens 16K. Dengan anggaran $2.00, loop berhenti sebelum panggilan yang bisa melewati batas.
Kapan beralih ke Gemini 4 Argon
Argon menerima permintaan yang sama dan berbiaya sama per token input dan output. Google menyebutnya "pilihan ideal untuk sebagian besar rekayasa perangkat lunak dan pekerjaan pengetahuan," dengan respons lebih cepat dan pemakaian token per giliran yang lebih rendah. Arahkan ke Argon dengan run_agent(task, model=ARGON) saat:
- Tugasnya rutin. Perbaikan kecil, perubahan satu file, dan penulisan tes tidak memerlukan token verifikasi tambahan milik Carbon.
- Satu respons harus melebihi 64K token. Carbon membatasi output di 64K. Panduan Argon kami membahas batas output Argon yang jauh lebih besar.
- Anda menginginkan percobaan pertama yang murah. Jalankan Argon terlebih dahulu dan eskalasi ke Carbon hanya jika tes masih gagal. Router di Gemini 4 Carbon API vs Gemini 4 Argon API melakukan hal ini.
Gunakan Carbon untuk mencari akar masalah di seluruh repositori dan loop yang banyak memakai terminal. Di tabel Google, Carbon mencetak 65,2% di Terminal-Bench 4.0 (AA) dibandingkan 57,1% untuk Argon, dan 9,6% di SWE-sweep dibandingkan 4,3%. Artikel ketersediaan Google juga menyarankan pembagian peran: Carbon untuk peran arsitektur, koordinasi, dan audit, dipasangkan dengan model yang lebih cepat dan ringan untuk pekerjaan paralel. Dalam loop ini, artinya satu kali jalan Carbon sebagai perencana yang membagikan file ke worker Argon.
Anggaran untuk kedua model ada di artikel harga Gemini 4 Carbon API. Jika Anda menimbang vendor lain untuk agen ini, lihat Gemini 4 Carbon API vs Claude Opus 5.5 API vs GPT-6 Astra API.
Pertanyaan yang sering diajukan
Apakah Gemini 4 Carbon API mendukung function calling di PoYo?
Dokumentasi PoYo saat ini tidak mendokumentasikan tools atau deklarasi fungsi untuk model Gemini di Chat Completions maupun Gemini Native. Tools didokumentasikan untuk Anthropic Messages dan Responses. Panduan ini memakai protokol aksi JSON di dalam konten pesan, yang hanya membutuhkan field yang terdokumentasi.
Bisakah saya memakai SDK OpenAI untuk Python dengan Gemini 4 Carbon API?
Ya. Buat OpenAI(api_key=..., base_url="https://api.poyo.ai/v1") dan kirim model="gemini-4-carbon" ke chat.completions.create. Streaming berfungsi dengan stream=True, dan chunk terakhir membawa usage.
Berapa output maksimum dan jendela konteks Gemini 4 Carbon API?
Konteks 1M token dan output hingga 64K token per respons. Atur max_tokens ke 64.000 atau kurang.
Bagaimana cara membatasi biaya Gemini 4 Carbon API dalam loop agen?
Batasi jumlah giliran, batasi max_tokens per giliran, potong hasil tool, dan berhenti saat pengeluaran sejauh ini ditambah giliran berikutnya dalam kasus terburuk akan melewati anggaran Anda. Hitung pengeluaran dari usage.prompt_tokens × $1.60 dan usage.completion_tokens × $8.00 per 1M token di PoYo.
Apakah Gemini 4 Carbon API mendukung context caching?
PoYo mencantumkan harga baca cache untuk Carbon sebesar $0.08 per 1M token (16 kredit). Dokumentasinya saat ini tidak mendokumentasikan parameter permintaan untuk caching atau field usage token cache untuk model Gemini, jadi anggarkan prompt dengan tarif input penuh dan periksa tagihan Anda untuk biaya bertarif cache.
Kapan agen coding sebaiknya memakai Gemini 4 Argon alih-alih Carbon?
Gunakan Argon untuk coding rutin, untuk respons tunggal apa pun yang harus melebihi 64K token, dan sebagai percobaan pertama yang lebih murah sebelum eskalasi ke Carbon. Keduanya berbiaya $1.60 / $8.00 per 1M token di PoYo, tetapi menurut Google Argon memakai lebih sedikit token per giliran.