Panduan developer untuk Gemini 4 Carbon

Gemini 4 Carbon adalah model termutakhir Google yang unggul dalam pekerjaan mendalam pada tugas-tugas kompleks di dunia nyata di berbagai domain, termasuk coding, keuangan, hukum, pengamanan cyber, dan sains. Model ini merupakan bagian dari rangkaian Gemini 4. Gemini 4 Carbon adalah Model Termutakhir Google yang tunduk pada Pasal 34 Persyaratan Khusus Layanan (untuk mengetahui detailnya, lihat Pemantauan penyalahgunaan).

Dokumen ini membahas kemampuan utama 4 Carbon, konvensi API yang diterapkan, cara bermigrasi ke versi tersebut, dan panduan memulai. Untuk mengetahui ringkasan rangkaian Gemini 4, lihat Mulai menggunakan Gemini 4.

Kemampuan utama di Gemini 4 Carbon

Gemini 4 Carbon mencakup kemampuan berikut:

• Batas token input dan output terpadu: 4 Carbon memiliki batas 1.048.576 token terpadu yang mencakup token input dan output (dengan output mencakup penalaran, panggilan fungsi, dan respons akhir).
• Dekode panjang hingga 1.048.576 token: 4 Carbon memperluas pembuatan di luar satu segmen latar depan (65.536 token saat melakukan streaming, atau 32.768 token saat tidak melakukan streaming) hingga 1.048.576 token (dikurangi token input Anda) di Interactions API dan GenerateContent (v1beta1). Google Gen AI SDK menangani continuation_token secara otomatis di seluruh segmen, atau Anda dapat menjalankan dekode latar belakang asinkron yang dikelola server (background=true) atau mengelola continuation_token dalam loop kelanjutan kustom.
• Tingkat penalaran: 4 Carbon mendukung LOW, MEDIUM (default di gemini-4-carbon), dan HIGH (default di gemini-4-carbon-cyber-permissive).
• Caching implisit dengan caching tahan lama: Caching implisit berlaku secara otomatis untuk awalan perintah bersama yang berisi 4.096 token atau lebih, dengan caching tahan lama diaktifkan secara default. Cache konteks eksplisit tidak didukung.
• Input file Office dan OpenDocument: Selain PDF dan teks biasa, 4 Carbon menerima file Microsoft Office (.docx, .dotx, .doc, .pptx, .ppt, .xlsx, .xls) dan OpenDocument (.odt, .odp, .ods) secara inline atau dari Cloud Storage di GenerateContent dan Interactions API.
• Pemahaman video agentic: Pemahaman video agentic tersedia secara umum dan nonaktif secara default.

Panduan Memulai

Sebelum memulai, Anda harus melakukan autentikasi ke Gemini Enterprise Agent Platform menggunakan Kredensial Default Aplikasi (ADC) atau kunci API. Lihat Memulai Agent Platform untuk mengetahui informasi selengkapnya.

Dalam blok kode berikut, ganti PROJECT_ID dengan project ID Anda.

Coba di Agent Studio

Untuk menguji perintah dan mengonfigurasi gemini-4-carbon di UI Agent Studio, lakukan hal berikut:

1. Buka Agent Studio di project Cloud de Confiance by S3NS Anda, lalu pilih gemini-4-carbon di bagian grup Gemini.
2. Di Model settings, konfigurasikan opsi berikut:
   • Thinking level: Pilih Low, Medium (default), atau High.
   • Region: Pilih Global, us, atau eu.
   • Output token limit: Tetapkan antara 32,768 dan 1,048,576 (default 1,048,576). Agent Studio menangani token kelanjutan secara otomatis untuk respons yang melebihi batas permintaan tunggal.

Penginstalan

Mengupgrade ke Google Gen AI SDK terbaru. Kelanjutan otomatis di Interactions API memerlukan google-genai >= 2.34.0 untuk Python, @google/genai >= 2.32.0 untuk JavaScript/TypeScript, >= 1.77.0 untuk Go, atau >= 1.80.0 untuk Java (di GenerateContent, kelanjutan otomatis memerlukan >= 2.30.1 untuk Python, >= 2.29.1 untuk JavaScript/TypeScript, >= 1.74.0 untuk Go, >= 1.77.0 untuk Java, >= 1.26.0 untuk .NET, atau >= 1.6.0 untuk Kotlin):

pip install --upgrade "google-genai>=2.34.0"

Permintaan dasar

Kirim permintaan ke gemini-4-carbon menggunakan Google Gen AI SDK atau REST:

from google import genai
from google.genai import types

client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")

response = client.models.generate_content(
    model="gemini-4-carbon",
    contents="Design a lock-free ring buffer in Rust for multi-producer, single-consumer telemetry ingestion.",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(
            thinking_level="MEDIUM",  # Default: "MEDIUM" (Valid: "LOW", "MEDIUM", "HIGH")
        ),
    ),
)
print(response.text)

from google import genai

client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")

# Turn 1: Initial request (stored server-side by default)
turn1 = client.interactions.create(
    model="gemini-4-carbon",
    input="Design a lock-free ring buffer in Rust for multi-producer, single-consumer telemetry ingestion.",
    store=True,
)
print(turn1.output_text)

# Turn 2: Continue the conversation using previous_interaction_id
turn2 = client.interactions.create(
    model="gemini-4-carbon",
    input="Add a bounded backpressure policy and unit tests for concurrent writers.",
    previous_interaction_id=turn1.id,
)
print(turn2.output_text)

curl -X POST \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json" \
"https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-4-carbon:generateContent" \
-d '{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Provide an architectural review of this Go interface."
        }
      ]
    }
  ],
  "generationConfig": {
    "thinkingConfig": {
      "thinkingLevel": "MEDIUM"
    }
  }
}'

Output terstruktur

Untuk menghasilkan output JSON yang sesuai dengan skema, konfigurasikan response_mime_type dan response_schema:

from pydantic import BaseModel, Field
from google import genai
from google.genai import types

class ArchitectureReview(BaseModel):
    component: str = Field(description="Service or module name")
    bottlenecks: list[str] = Field(description="Throughput or latency bottlenecks")
    recommended_changes: list[str] = Field(description="Concrete refactoring steps")

client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")

response = client.models.generate_content(
    model="gemini-4-carbon",
    contents="Review a synchronous order-processing pipeline backed by a single primary database at 15,000 writes/sec.",
    config=types.GenerateContentConfig(
        response_mime_type="application/json",
        response_schema=ArchitectureReview,
        thinking_config=types.ThinkingConfig(thinking_level="HIGH"),
    ),
)
print(response.text)

Contoh dekode panjang

Secara default, satu segmen API latar depan menghasilkan hingga 65.536 token output saat streaming atau 32.768 token output saat non-streaming, dengan output mencakup pemikiran, panggilan fungsi, dan respons akhir. Untuk menghasilkan penyelesaian hingga 1.048.576 token (dikurangi token input Anda), gunakan dekode panjang di Interactions API atau GenerateContent. Untuk opsi kelanjutan, transisi status, dan aturan validasi, lihat Dekode panjang.

Menggunakan dekode panjang dengan Interactions API

Di google-genai >= 2.34.0 (Python), @google/genai >= 2.32.0 (JavaScript/TypeScript), Go >= 1.77.0, dan Java >= 1.80.0, interactions.create() otomatis mengikuti continuation_token di seluruh segmen setiap kali segmen menampilkan status="requires_continuation". Anda juga dapat memilih tidak ikut (automatic_continuation=False) untuk menjalankan loop tersimpan kustom (store=True) atau stateless (store=False):

from google import genai

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

# Automatic continuation is enabled by default in google-genai >= 2.34.0.
# Unary calls merge all segments into one Interaction with summed usage.
interaction = client.interactions.create(
    model="gemini-4-carbon",
    input="Write a complete formal proof of the prime number theorem.",
    generation_config={
        "max_output_tokens": 256000,
        "thinking_level": "high",
    },
)
print(interaction.output_text)
print(f"Merged segment IDs: {interaction.continuation_ids}")
print(f"Initial input tokens: {interaction.usage.initial_input_tokens}")

# Optional: Delete each stored server segment (last segment first) before its 7-day TTL expires.
for segment_id in reversed(interaction.continuation_ids or [interaction.id]):
    client.interactions.delete(id=segment_id)

# Streaming yields events across all segments in order. Intermediate segments
# emit interaction.completed with status="requires_continuation".
stream = client.interactions.create(
    model="gemini-4-carbon",
    input="Write a complete formal proof of the prime number theorem.",
    stream=True,
    generation_config={
        "max_output_tokens": 256000,
        "thinking_level": "high",
    },
)
for event in stream:
    if event.event_type == "step.delta" and getattr(event.delta, "text", None):
        print(event.delta.text, end="", flush=True)
    elif (
        event.event_type == "interaction.completed"
        and event.interaction.status != "requires_continuation"
    ):
        print(f"\nFinal status: {event.interaction.status}")

# Set automatic_continuation=False to return after a single segment.
single_segment = client.interactions.create(
    model="gemini-4-carbon",
    input="Write a complete formal proof of the prime number theorem.",
    generation_config={"max_output_tokens": 256000, "thinking_level": "high"},
    automatic_continuation=False,
)

from google import genai

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

prompt = "Write a complete formal proof of the prime number theorem."

# Stored loop (store=True, default): chain previous_interaction_id + continuation_token
# without resending input.
segment = client.interactions.create(
    model="gemini-4-carbon",
    input=prompt,
    store=True,
    generation_config={"max_output_tokens": 131072, "thinking_level": "high"},
    automatic_continuation=False,
)
full_text = segment.output_text or ""

while segment.status == "requires_continuation" and segment.continuation_token:
    segment = client.interactions.create(
        model="gemini-4-carbon",
        previous_interaction_id=segment.id,
        continuation_token=segment.continuation_token,
        generation_config={"max_output_tokens": 131072, "thinking_level": "high"},
        automatic_continuation=False,
    )
    full_text += segment.output_text or ""

# If status == "incomplete", max_output_tokens was exhausted; raise max_output_tokens
# to continue (leaving default automatic_continuation=True lets the SDK finish remaining segments).
if segment.status == "incomplete" and segment.continuation_token:
    segment = client.interactions.create(
        model="gemini-4-carbon",
        previous_interaction_id=segment.id,
        continuation_token=segment.continuation_token,
        generation_config={"max_output_tokens": 256000, "thinking_level": "high"},
    )
    full_text += segment.output_text or ""

# Stateless loop (store=False): resend original input + continuation_token
# with no previous_interaction_id.
stateless_seg = client.interactions.create(
    model="gemini-4-carbon",
    input=prompt,
    store=False,
    generation_config={"max_output_tokens": 131072, "thinking_level": "high"},
    automatic_continuation=False,
)
stateless_text = stateless_seg.output_text or ""
while stateless_seg.status == "requires_continuation" and stateless_seg.continuation_token:
    stateless_seg = client.interactions.create(
        model="gemini-4-carbon",
        input=prompt,
        store=False,
        continuation_token=stateless_seg.continuation_token,
        generation_config={"max_output_tokens": 131072, "thinking_level": "high"},
        automatic_continuation=False,
    )
    stateless_text += stateless_seg.output_text or ""

# Segment 1: Start a stored interaction (store=true by default)
curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" \
  -d '{
    "model": "gemini-4-carbon",
    "store": true,
    "input": "Write a complete formal proof of the prime number theorem.",
    "generation_config": {
      "max_output_tokens": 131072,
      "thinking_level": "high"
    }
  }'

# Segment 2: When status is "requires_continuation", pass previous_interaction_id
# and continuation_token without resending input
curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" \
  -d '{
    "model": "gemini-4-carbon",
    "store": true,
    "previous_interaction_id": "SEGMENT_1_ID",
    "continuation_token": "CONTINUATION_TOKEN",
    "generation_config": {
      "max_output_tokens": 131072,
      "thinking_level": "high"
    }
  }'

# Segment 1: Stateless interaction (store=false)
curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" \
  -d '{
    "model": "gemini-4-carbon",
    "store": false,
    "input": "Write a complete formal proof of the prime number theorem.",
    "generation_config": {
      "max_output_tokens": 131072,
      "thinking_level": "high"
    }
  }'

# Segment 2: Resend the original input and continuation_token (no previous_interaction_id)
curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" \
  -d '{
    "model": "gemini-4-carbon",
    "store": false,
    "input": "Write a complete formal proof of the prime number theorem.",
    "continuation_token": "CONTINUATION_TOKEN",
    "generation_config": {
      "max_output_tokens": 131072,
      "thinking_level": "high"
    }
  }'

Untuk eksekusi asinkron yang dikelola server (background=True dengan store=True) atau pemulihan dari checkpoint streaming (peristiwa interaction.status_update yang dikeluarkan pada 32.768 token output dan setiap 5.000 token setelahnya), gunakan pola berikut:

import time
from google import genai

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

# Start a server-managed background long decode (requires store=True)
interaction = client.interactions.create(
    model="gemini-4-carbon",
    input="Write a complete formal proof of the prime number theorem.",
    background=True,
    store=True,
    generation_config={"max_output_tokens": 256000, "thinking_level": "high"},
)

while interaction.status in ("queued", "in_progress"):
    time.sleep(10)
    interaction = client.interactions.get(id=interaction.id)

print(f"Status: {interaction.status}")
print(interaction.output_text)

# Optional: Cancel an in-progress background interaction and resume later
# from its persisted checkpoint continuation_token (if >= 32,768 tokens decoded).
# cancelled = client.interactions.cancel(id=interaction.id)
# if cancelled.continuation_token:
#     resumed = client.interactions.create(
#         model="gemini-4-carbon",
#         previous_interaction_id=cancelled.id,
#         continuation_token=cancelled.continuation_token,
#         background=True,
#         generation_config={"max_output_tokens": 256000, "thinking_level": "high"},
#     )

# Start a server-managed background long decode (requires store=true)
curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" \
  -d '{
    "model": "gemini-4-carbon",
    "background": true,
    "store": true,
    "input": "Write a complete formal proof of the prime number theorem.",
    "generation_config": {
      "max_output_tokens": 256000,
      "thinking_level": "high"
    }
  }'

# Poll the interaction until status reaches completed, incomplete, failed, or cancelled
curl -s -X GET \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions/INTERACTION_ID"

# Optional: Cancel an in-progress background decode
curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions/INTERACTION_ID/cancel"

# Optional: Resume a cancelled background decode from its checkpoint continuation_token
curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" \
  -d '{
    "model": "gemini-4-carbon",
    "background": true,
    "store": true,
    "previous_interaction_id": "INTERACTION_ID",
    "continuation_token": "CONTINUATION_TOKEN",
    "generation_config": {
      "max_output_tokens": 256000,
      "thinking_level": "high"
    }
  }'

from google import genai
from google.genai import errors

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

# With default automatic_continuation=True, stream=True automatically
# reconnects from the latest interaction.status_update checkpoint (32,768
# output tokens, then every 5,000 tokens) if no output was yielded after the
# checkpoint. If a disconnect occurs after output was yielded since the last
# checkpoint, the SDK raises ContinuationInterruptedError so you can resume
# from err.continuation_token.
stream = client.interactions.create(
    model="gemini-4-carbon",
    input="Write a complete formal proof of the prime number theorem.",
    stream=True,
    store=True,
    generation_config={"max_output_tokens": 256000, "thinking_level": "high"},
)

try:
    for event in stream:
        if event.event_type == "step.delta" and getattr(event.delta, "text", None):
            print(event.delta.text, end="", flush=True)
except errors.ContinuationInterruptedError as err:
    # Resuming from a mid-segment checkpoint regenerates any output yielded
    # after that checkpoint.
    if err.interaction_id and err.continuation_token:
        resumed_stream = client.interactions.create(
            model="gemini-4-carbon",
            previous_interaction_id=err.interaction_id,
            continuation_token=err.continuation_token,
            stream=True,
            store=True,
            generation_config={"max_output_tokens": 256000, "thinking_level": "high"},
        )
        for event in resumed_stream:
            if event.event_type == "step.delta" and getattr(event.delta, "text", None):
                print(event.delta.text, end="", flush=True)

# Start a streaming interaction; save interaction.id from interaction.created
# and the latest continuation_token from interaction.status_update SSE events
curl -N -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" \
  -d '{
    "model": "gemini-4-carbon",
    "stream": true,
    "store": true,
    "input": "Write a complete formal proof of the prime number theorem.",
    "generation_config": {
      "max_output_tokens": 256000,
      "thinking_level": "high"
    }
  }'

# Resume a dropped stream from the last saved checkpoint continuation_token
# (for store=false, resend the original input instead of previous_interaction_id)
curl -N -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" \
  -d '{
    "model": "gemini-4-carbon",
    "stream": true,
    "store": true,
    "previous_interaction_id": "SEGMENT_ID",
    "continuation_token": "CHECKPOINT_CONTINUATION_TOKEN",
    "generation_config": {
      "max_output_tokens": 256000,
      "thinking_level": "high"
    }
  }'

Menggunakan dekode panjang dengan GenerateContent

Di GenerateContent (v1beta1), tetapkan max_output_tokens lebih besar dari 65.536 untuk permintaan streaming atau lebih besar dari 32.768 untuk permintaan non-streaming (hingga 1.048.576). Google Gen AI SDK secara otomatis mengikuti continuation_token di seluruh segmen saat finish_reason adalah CONTINUATION (tetapkan automatic_continuation=False di GenerateContentConfig untuk memilih tidak ikut), atau Anda dapat meneruskan continuation_token dalam loop kustom:

from google import genai
from google.genai import types

client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")

# Automatic continuation is enabled by default in google-genai >= 2.30.1.
# Chunks across all continuation requests are yielded as a single stream.
for chunk in client.models.generate_content_stream(
    model="gemini-4-carbon",
    contents="Write a complete formal proof of the prime number theorem.",
    config=types.GenerateContentConfig(
        max_output_tokens=256000,
        thinking_config=types.ThinkingConfig(thinking_level="HIGH"),
    ),
):
    print(chunk.text, end="")

# Set automatic_continuation=False to disable automatic continuation.
for chunk in client.models.generate_content_stream(
    model="gemini-4-carbon",
    contents="Write a complete formal proof of the prime number theorem.",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_level="HIGH"),
        automatic_continuation=False,
    ),
):
    print(chunk.text, end="")

# Request 1: Initial request with maxOutputTokens > 32,768
curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-4-carbon:generateContent" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{"text": "Write a complete formal proof of the prime number theorem."}]
    }],
    "generationConfig": {
      "maxOutputTokens": 131072,
      "thinkingConfig": {"thinkingLevel": "HIGH"}
    }
  }'

# Request 2: Resend the original request with top-level continuationToken
# from Request 1 (candidates[0].continuationToken)
curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-4-carbon:generateContent" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{"text": "Write a complete formal proof of the prime number theorem."}]
    }],
    "continuationToken": "CONTINUATION_TOKEN",
    "generationConfig": {
      "maxOutputTokens": 131072,
      "thinkingConfig": {"thinkingLevel": "HIGH"}
    }
  }'

Aturan API dan konvensi perilaku wajib

4 Carbon menerapkan konvensi di bagian berikut untuk tingkat pemikiran, batas token, caching, parameter pembuatan, dan eksekusi alat multi-turn.

Tingkat penalaran

4 Carbon mendukung tiga nilai thinking_level (thinking_budget dan MINIMAL menampilkan error validasi HTTP 400). Teruskan nilai huruf besar ("LOW", "MEDIUM", "HIGH") di GenerateContent dan nilai huruf kecil ("low", "medium", "high") di Interactions API. Tabel berikut mencantumkan setiap tingkat penalaran dan workload yang direkomendasikan:

Batas token, caching, dan penagihan

4 Carbon menerapkan aturan token, caching, media, dan penagihan berikut:

• Batas token input dan output terpadu serta anggaran output default: Anggaran token dan batas segmen latar depan berfungsi sebagai berikut:
  • Batas token keseluruhan model adalah 1,048,576 token dan mencakup token input dan output (dengan output mencakup penalaran, panggilan fungsi, dan respons akhir). max_output_tokens mengontrol batas token output untuk pembuatan (hingga 1,048,576 dikurangi token input Anda); menetapkan max_output_tokens lebih besar dari 1,048,576 akan menampilkan error HTTP 400.
  • Jika max_output_tokens dihilangkan di GenerateContent atau Interactions API, total anggaran output default (pemikiran, panggilan fungsi, dan respons) adalah 65.536 token. Karena satu segmen latar depan menghasilkan hingga 65.536 token saat streaming atau 32.768 token saat non-streaming, Google Gen AI SDK (v1beta1) secara otomatis merangkai dua segmen 32.768 token pada panggilan non-streaming jika diperlukan, sedangkan satu permintaan REST non-streaming berhenti setelah satu segmen latar depan 32.768 token. Di Agent Studio, batas token output ditetapkan secara default ke 1,048,576 dengan kelanjutan otomatis.
• Dekode panjang: Satu segmen latar depan menghasilkan hingga 65.536 token output saat streaming atau 32.768 token output saat non-streaming. Untuk memperpanjang output single-turn hingga 1.048.576 token (dikurangi token input) di Interactions API atau GenerateContent (v1beta1), lihat Dekode panjang.
• Cache konteks: Cache konteks eksplisit tidak didukung. Caching implisit (dengan caching tahan lama yang diaktifkan secara default) diterapkan secara otomatis ke awalan perintah bersama yang berisi 4.096 token atau lebih, jadi tempatkan konten statis di awal perintah Anda.
• Input Office dan OpenDocument: Teruskan file Word (application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/vnd.openxmlformats-officedocument.wordprocessingml.template, application/msword, application/vnd.oasis.opendocument.text), PowerPoint (application/vnd.openxmlformats-officedocument.presentationml.presentation, application/vnd.ms-powerpoint, application/vnd.oasis.opendocument.presentation), dan spreadsheet Excel atau OpenDocument (application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/vnd.ms-excel, application/vnd.oasis.opendocument.spreadsheet) secara inline atau melalui Cloud Storage URI (gs://) menggunakan inlineData atau fileData pada input GenerateContent dan document (termasuk hasil alat) di Interactions API.
• Video agentic: Video yang diupload ditetapkan secara default ke media_processing="static". Tetapkan media_processing="agentic" untuk mengaktifkan pemrosesan video agentic.
• Penghitungan dan penagihan token: Setiap token yang diproses model akan dihitung dan ditagih, termasuk token penalaran dan petunjuk sistem alat internal serta deklarasi fungsi saat menggunakan grounding. Grounding dengan Google Penelusuran juga tetap ditagih per kueri.

Parameter, panggilan fungsi, dan validasi chat

4 Carbon menerapkan aturan berikut untuk parameter pembuatan, panggilan alat, dan histori percakapan:

• Parameter sampling yang diabaikan (temperature, top_k, top_p): Backend mengabaikan nilai kustom. Kontrol kedalaman penalaran dengan thinking_level, dan format output dengan response_schema.
• Parameter yang tidak didukung (frequency_penalty, presence_penalty, dan candidate_count lebih besar dari 1): Meneruskan frequency_penalty, presence_penalty, atau candidate_count lebih besar dari 1 (candidateCount ditetapkan pada 1) akan menampilkan error HTTP 400. Hapus parameter ini dari permintaan Anda.

• Panggilan fungsi: Deklarasi alat dan giliran eksekusi mengikuti aturan berikut:

  • Simetri belokan: Setiap FunctionResponse harus cocok dengan id, name, dan urutan FunctionCall sebelumnya.
  • Eksekusi berurutan: Lebih memilih giliran eksekusi alat berurutan dalam loop alat multi-langkah.

  • Pemformatan pra-alat: Pisahkan petunjuk inline dengan \n\n dan hindari teks tidak terstruktur sebelum panggilan alat. Untuk mencatat status perantara sebelum panggilan alat, gunakan deklarasi fungsi khusus:

    {
      "name": "update",
      "description": "Update working notes before tool execution",
      "parameters": {
        "type": "OBJECT",
        "properties": {
          "previous_step": {"type": "STRING"},
          "plan": {"type": "STRING"},
          "next_step": {"type": "STRING"}
        },
        "required": ["previous_step", "plan", "next_step"]
      }
    }
    

• Validasi urutan chat: Payload multi-turn chat menerapkan batasan berikut:

  • Payload histori tidak boleh diakhiri dengan giliran peran model.
  • Respons model yang telah disiapkan tidak didukung.

Dekode panjang

Long decode membagi pembuatan hingga 1.048.576 token (dikurangi token input Anda) di beberapa segmen pada Interactions API atau GenerateContent (v1beta1). Di Interactions API, setiap segmen latar depan menghasilkan hingga 65.536 token output saat streaming (stream=true) atau 32.768 token output saat non-streaming (stream=false) dan menampilkan status="requires_continuation" dengan continuation_token terenkripsi, atau Anda dapat menetapkan background=true (store=true) sehingga server menjalankan loop kelanjutan secara asinkron dan menyimpan output gabungan dalam satu Interaction. Di GenerateContent, segmen streaming menghasilkan hingga 65.536 token output dan segmen non-streaming menghasilkan hingga 32.768 token output sebelum memunculkan finish_reason=CONTINUATION dengan continuation_token, yang berlanjut hingga finish_reason=STOP. Di Agent Studio, menetapkan batas token output lebih besar dari 65.536 hingga 1.048.576 akan menangani token kelanjutan secara otomatis. Untuk contoh kode yang dapat dijalankan, lihat Contoh panduan memulai dekode panjang.

Kapan harus menggunakan dekode panjang

Sebagian besar permintaan selesai dalam anggaran output default 65.536 token (atau satu segmen latar depan non-streaming 32.768 token melalui REST). Gunakan dekode panjang hanya jika satu respons memerlukan lebih banyak output dari itu. Dekode panjang memberi model lebih banyak ruang untuk penalaran; hal ini tidak membuat jawaban lebih panjang (gunakan thinking_level untuk mengontrol kedalaman penalaran).

Memilih opsi kelanjutan

Pilih pola kelanjutan berdasarkan platform API, postur penyimpanan, dan lingkungan runtime Anda. Semua opsi dalam tabel berikut mencapai batas 1.048.576 token yang sama (dikurangi token input) di gemini-4-carbon dan gemini-4-carbon-cyber-permissive.

Persyaratan versi API dan SDK

Dekode panjang memerlukan versi API dan versi SDK minimum berikut:

• Persyaratan v1beta1 API (masalah umum): Dekode panjang (continuation_token) di Interactions API dan GenerateContent (generateContent dan streamGenerateContent) hanya didukung di v1beta1 API (bukan v1) di Agent Platform. Google Gen AI SDK menggunakan v1beta1 secara default, kecuali jika api_version='v1' ditentukan di http_options (atau api_version="v1" di interactions.create); untuk panggilan REST langsung, gunakan jalur endpoint /v1beta1/.
• Versi SDK dan kompatibilitas OpenAI: Untuk melanjutkan otomatis di Interactions API, upgrade ke Python google-genai >= 2.34.0, JavaScript/TypeScript @google/genai >= 2.32.0, Go >= 1.77.0, atau Java >= 1.80.0 (untuk bahasa lain di Interactions API, panggil REST API secara langsung dengan background=true atau loop kelanjutan kustom). Untuk melanjutkan otomatis di GenerateContent, upgrade ke Python >= 2.30.1, JavaScript/TypeScript >= 2.29.1, Go >= 1.74.0, Java >= 1.77.0, .NET >= 1.26.0, atau Kotlin >= 1.6.0. Versi SDK yang lebih lama dan lapisan kompatibilitas OpenAI tidak dapat mengambil penyelesaian panjang menggunakan token lanjutan.

Aturan kelanjutan Interactions API

Transisi status, aturan perantaian, dan perilaku penyimpanan berikut berlaku untuk dekode panjang di Interactions API.

Nilai status dan anggaran token output

Jika generation_config.max_output_tokens dihilangkan pada permintaan Interactions API, total anggaran output ditetapkan secara default ke 65.536 token (sehingga panggilan non-streaming berhenti pada 32.768 token dengan status="requires_continuation", dan segmen kedua dapat menghasilkan 32.768 token yang tersisa). Siapkan generation_config.max_output_tokens hingga 1,048,576 (dikurangi token input) untuk dekode yang lebih panjang dalam mode latar depan dan background=true. Server menampilkan nilai status berikut:

• requires_continuation: Batas output per segmen (32.768 non-streaming atau 65.536 streaming) tercapai sebelum max_output_tokens; teruskan continuation_token yang ditampilkan pada permintaan berikutnya untuk melanjutkan decoding.
• incomplete: Total anggaran max_output_tokens telah habis; melanjutkan dengan continuation_token tanpa menaikkan max_output_tokens akan menampilkan error HTTP 400 (max_output_tokens has already been exhausted). Tingkatkan max_output_tokens pada permintaan berikutnya untuk melanjutkan decoding.
• completed: Pembuatan selesai secara alami dan continuation_token dihapus.

Penautan, pengalihan mode, dan penyimpanan segmen

Permintaan kelanjutan di Interactions API menerapkan aturan berikut:

• Stored continuation (store=true, default): Teruskan previous_interaction_id yang ditetapkan ke segmen id yang mengeluarkan continuation_token bersama dengan continuation_token, dan hapus input (segmen yang disimpan sudah menyimpan input giliran). Selalu pasangkan setiap continuation_token dengan previous_interaction_id segmen yang mengeluarkannya; meneruskan continuation_token pada interaksi yang sudah completed akan menampilkan error HTTP 400.
• Kelanjutan stateless (store=false): Hilangkan previous_interaction_id dan kirim ulang input asli bersama dengan continuation_token di setiap segmen.
• Beralih mode store di seluruh segmen: Anda dapat beralih dari tersimpan (store=true) ke stateless (store=false) di tengah dekode dengan menghilangkan previous_interaction_id dan mengirim ulang input asli dengan continuation_token. Beralih dari stateless (store=false) ke tersimpan (store=true) tidak didukung karena tidak ada interaksi induk tersimpan untuk previous_interaction_id.
• Peralihan dan percabangan mode latar depan dan background=true: Continuation yang disimpan (store=true) dapat beralih antara eksekusi latar depan (background=false) dan latar belakang (background=true) di seluruh segmen, termasuk melanjutkan interaksi background=true yang dibatalkan dari checkpoint-nya continuation_token (dipertahankan setelah 32.768 token output) dalam mode latar belakang atau latar depan. Menggunakan kembali previous_interaction_id dan continuation_token yang sama akan membuat kelanjutan cabang yang independen.
• Penegakan batas giliran: Memulai giliran pengguna baru (previous_interaction_id dengan input baru dan tanpa continuation_token) dari segmen yang statusnya requires_continuation atau incomplete akan menampilkan error HTTP 400. Selesaikan melanjutkan dekode ke completed, atau buat cabang giliran berikutnya dari interaksi completed terbaru. Setelah segmen akhir mencapai completed, meneruskan id segmen akhir tersebut sebagai previous_interaction_id akan merekonstruksi histori percakapan lengkap di semua segmen sebelumnya.
• Konsistensi parameter di seluruh segmen: Mengubah model, system_instruction, atau deklarasi fungsi (tools) pada segmen lanjutan akan menampilkan error HTTP 400. Jangan ubah thinking_level dan alat bawaan di seluruh segmen (lihat Masalah umum).
• Perilaku get, list, dan delete segmen tunggal: Dalam mode latar depan (background=false), setiap segmen disimpan sebagai resource Interaction terpisah (interactions.get(id) hanya menampilkan segmen tersebut, interactions.list() mencantumkan setiap segmen secara terpisah, dan interactions.delete(id) hanya menghapus segmen tersebut; saat menghapus rantai segmen, hapus dalam urutan terbalik dari segmen terakhir ke belakang). Di Google Gen AI SDK dengan automatic_continuation=True (stream=False), interactions.create() menggabungkan semua segmen saat ditampilkan dan mengisi interaction.continuation_ids dengan ID segmen yang diurutkan (diakhiri dengan interaction.id). Jika segmen berikutnya gagal, melebihi timeout numerik per panggilan, atau terhenti di tengah streaming setelah melewati checkpoint yang dapat dilanjutkan, SDK akan memunculkan ContinuationInterruptedError yang membawa partial_interaction, continuation_token, interaction_id, dan continuation_ids sehingga Anda dapat melanjutkan dari continuation_token.

Aturan loop kustom GenerateContent

Dalam loop kelanjutan GenerateContent kustom, ikuti aturan berikut:

• Tetapkan max_output_tokens lebih besar dari 65.536 (streaming) atau 32.768 (non-streaming) hingga 1.048.576, dan kirim ulang contents, system_instruction, dan tools asli pada setiap permintaan lanjutan bersama dengan continuation_token terbaru (kolom tingkat teratas di GenerateContentRequest di REST, atau di GenerateContentConfig di Google Gen AI SDK).
• Jangan menambahkan output model parsial ke dalam contents atau mengirim perintah lanjutan yang meminta model untuk melanjutkan.
• Lanjutkan pengulangan selama finish_reason adalah CONTINUATION dan continuation_token ada, meskipun segmen menghabiskan semua 32.768 atau 65.536 token untuk penalaran (parts: [{"text": ""}]). Jika finish_reason adalah MAX_TOKENS saat continuation_token ada, naikkan max_output_tokens dalam permintaan berikutnya.
• Gabungkan bagian yang terakumulasi menjadi satu giliran model untuk histori multi-giliran hanya setelah STOP.

Penghitungan token, pemadatan, dan penyimpanan dalam cache implisit

Penghitungan dan penyimpanan token dalam cache di seluruh segmen lanjutan berfungsi sebagai berikut:

• Di Interactions API, panggilan interactions.create() non-streaming dengan automatic_continuation=True dan interaksi background=true yang dikelola server menjumlahkan jumlah token di semua segmen dalam usage (total_input_tokens, total_cached_tokens, total_output_tokens, total_thought_tokens, total_tokens), sehingga mempertahankan jumlah perintah segmen pertama dalam usage.initial_input_tokens. Dalam loop latar depan kustom dan peristiwa interaction.completed yang di-streaming, usage setiap segmen hanya melaporkan delta segmen tersebut, jadi jumlahkan kolom usage di seluruh segmen untuk total token yang ditagih.
• Di GenerateContent, Python Google Gen AI SDK (generate_content dan generate_content_stream) mengakumulasikan total token yang ditagih di seluruh segmen dalam usage_metadata akhir dan mempertahankan initial_prompt_token_count. Dalam loop REST kustom, jumlahkan prompt_token_count, cached_content_token_count, candidates_token_count, dan thoughts_token_count akhir di seluruh segmen.
• Karena setiap segmen kelanjutan latar depan mengisi ulang percakapan dan token yang dihasilkan sebelumnya sebagai input, usage.total_input_tokens (di Interactions API) dan prompt_token_count (di GenerateContent) meningkat di seluruh segmen. Jangan gunakan jumlah input kumulatif untuk memicu pemadatan konteks di infrastruktur pengelola agen; sebagai gantinya, periksa usage.initial_input_tokens (atau initial_prompt_token_count di GenerateContent) dan padatkan hanya setelah giliran selesai (status="completed" atau tidak ada continuation_token).
• Setiap segmen kelanjutan akan mengisi ulang perintah ditambah token yang didekode sebelumnya dan otomatis memenuhi syarat untuk cache konteks implisit (minimum 4.096 token, dengan cache tahan lama diaktifkan secara default) saat segmen berjalan secara berurutan. Segmen yang telah selesai akan ditagih pada akhir setiap segmen, meskipun segmen berikutnya gagal atau dibatalkan.

Bermigrasi ke 4 Carbon dari 3.1 Pro

Perilaku berikut berbeda dengan gemini-3.1-pro-preview:

• 4 Carbon memiliki batas 1.048.576 token terpadu di seluruh input dan output (dengan output mencakup penalaran, panggilan fungsi, dan respons akhir), bukan batas input dan output yang terpisah. Satu segmen latar depan dibatasi hingga 65.536 token saat streaming (atau 32.768 token saat non-streaming), dan output dapat diperluas hingga 1.048.576 token menggunakan dekode panjang di Interactions API atau GenerateContent (ditangani secara otomatis di Google Gen AI SDK, dengan background=true di Interactions API, atau menggunakan continuation_token dalam loop kustom).
• thinking_budget menampilkan error HTTP 400, bukan dipetakan ke tingkat penalaran. MINIMAL juga menampilkan error.
• Penyimpanan cache konteks eksplisit tidak didukung.
• Setiap token yang diproses model akan ditagih, termasuk petunjuk sistem alat internal dan deklarasi fungsi saat menggunakan grounding.

Untuk perbandingan berdampingan, lihat Bermigrasi dari Gemini 3.1 Pro.

 client = genai.Client(
     enterprise=True,
     project="PROJECT_ID",
     location="global", # Supports "global", "us", and "eu" ("global" and "us" for cyber)
 )

 response = client.models.generate_content(
-    model="gemini-3.1-pro-preview",
+    model="gemini-4-carbon",
     contents=prompt,
     config=types.GenerateContentConfig(
-        temperature=0.0,
-        cached_content="projects/.../cachedContents/...", # Explicit caching unsupported
         thinking_config=types.ThinkingConfig(
-            thinking_budget=16384, # Returns HTTP 400 instead of mapping silently
-            thinking_level="MINIMAL", # MINIMAL unsupported on Gemini 4 Carbon
+            thinking_level="MEDIUM", # Valid: "LOW", "MEDIUM" (default), "HIGH"
         ),
     ),
 )

Untuk bermigrasi dari gemini-3.1-pro-preview, lakukan hal berikut:

1. Perbarui ID model menjadi gemini-4-carbon (atau gemini-4-carbon-cyber-permissive untuk workload keamanan siber yang disetujui melalui Program Fairwind).
2. Upgrade ke Google Gen AI SDK terbaru dan perhitungkan batas token input dan output terpadu: Upgrade ke google-genai >= 2.34.0 (Python), @google/genai >= 2.32.0 (JavaScript/TypeScript), Go >= 1.77.0, atau Java >= 1.80.0 untuk melanjutkan otomatis Interactions API (atau >= 2.30.1 Python/>= 2.29.1 JavaScript di GenerateContent). Token input dan output (termasuk pemikiran dan panggilan fungsi) menggunakan batas token terpadu sebesar 1.048.576 token. Untuk output yang melebihi 65.536 token (hingga 1.048.576 token) di Interactions API atau GenerateContent, tetapkan max_output_tokens lebih besar dari 65.536 agar Google Gen AI SDK berlanjut secara otomatis di seluruh segmen (atau gunakan background=true atau loop continuation_token kustom).
3. Ganti parameter anggaran penalaran: Ganti thinking_budget dan MINIMAL dengan thinking_level yang ditetapkan ke LOW, MEDIUM (default di gemini-4-carbon), atau HIGH (default di gemini-4-carbon-cyber-permissive) (gunakan huruf kecil "low", "medium", atau "high" di Interactions API).
4. Hapus caching eksplisit dan muat konten perintah statis di awal (4.096 token atau lebih) untuk caching implisit otomatis.
5. Hapus parameter yang tidak berpengaruh atau tidak didukung: Hapus kolom pembuatan yang diabaikan dan ditolak sebagai berikut:
   • Hapus temperature, top_p, dan top_k, yang diabaikan.
   • Hapus frequency_penalty, presence_penalty, dan nilai candidate_count yang lebih besar dari 1.
   • Hapus semua respons model yang telah disiapkan dari histori percakapan.

Checklist ringkasan untuk developer

Gunakan checklist berikut untuk memverifikasi integrasi 4 Carbon Anda:

Masalah umum

Masalah umum berikut berlaku untuk dekode panjang 4 Carbon:

• Dekode panjang memerlukan v1beta1: Dekode panjang (continuation_token) di Interactions API dan GenerateContent API (generateContent dan streamGenerateContent) hanya didukung di v1beta1 API (bukan v1) di Agent Platform. Google Gen AI SDK menggunakan v1beta1 secara default, kecuali jika api_version='v1' ditetapkan di http_options (atau api_version="v1" di interactions.create); untuk panggilan REST langsung, gunakan jalur endpoint /v1beta1/.
• Perubahan parameter di seluruh segmen kelanjutan Interactions API: Mengubah model, system_instruction, atau deklarasi fungsi di seluruh segmen kelanjutan akan menampilkan error HTTP 400, sedangkan perubahan di tengah dekode pada generation_config.thinking_level atau alat bawaan (google_search, code_execution, url_context) tidak ditolak oleh validasi server. Pertahankan thinking_level dan alat bawaan agar tidak berubah di semua segmen loop kelanjutan.

Referensi lainnya

Untuk mengetahui informasi selengkapnya tentang 4 Carbon, lihat referensi berikut:

• Halaman model Gemini 4 Carbon
• Mulai menggunakan Gemini 4
• Notebook pengantar
• Gemini 4 Carbon untuk cyber