Gemini API reference

Referensi API ini menjelaskan API standar, streaming, dan real-time yang dapat Anda gunakan untuk berinteraksi dengan model Gemini. Anda dapat menggunakan REST API di lingkungan mana pun yang mendukung permintaan HTTP. Lihat panduan Memulai untuk mengetahui cara memulai panggilan API pertama Anda. Jika Anda mencari referensi untuk library dan SDK khusus bahasa kami, buka link untuk bahasa tersebut di navigasi kiri di bagian Referensi SDK.

Endpoint utama

Gemini API disusun berdasarkan endpoint utama berikut:

  • Interaksi (CreateInteraction) (Direkomendasikan): Primitif standar yang direkomendasikan untuk membangun dengan Gemini, dioptimalkan untuk alur kerja agentic, pengelolaan status sisi server, dan percakapan multi-modal, multi-giliran yang kompleks.
  • Pembuatan konten standar (generateContent): Endpoint REST standar yang memproses permintaan Anda dan menampilkan respons lengkap model dalam satu paket. Endpoint ini paling cocok untuk tugas non-interaktif yang dapat menunggu seluruh hasil.
  • Pembuatan konten streaming (streamGenerateContent): Menggunakan Server-Sent Events (SSE) untuk mengirimkan potongan respons kepada Anda saat respons tersebut dibuat. Hal ini memberikan pengalaman yang lebih cepat dan interaktif untuk aplikasi seperti chatbot.
  • Live API (BidiGenerateContent): API berbasis WebSocket stateful untuk streaming dua arah, yang dirancang untuk kasus penggunaan percakapan real-time
  • Mode batch (batchGenerateContent): Endpoint REST standar untuk mengirimkan batch permintaan generateContent.
  • Embedding (embedContent): Endpoint REST standar yang menghasilkan vektor embedding teks dari Content input.
  • Gen Media API: Endpoint untuk membuat media dengan model khusus kami seperti Imagen untuk pembuatan gambar, dan Veo untuk pembuatan video. Gemini juga memiliki kemampuan bawaan yang dapat Anda akses menggunakan generateContent API.
  • Platform API: Endpoint utilitas yang mendukung kemampuan inti seperti mengupload file, dan menghitung token.

Autentikasi

Semua permintaan ke Gemini API harus menyertakan header x-goog-api-key dengan kunci API Anda. Buat kunci API dengan beberapa klik di Google AI Studio.

Berikut adalah contoh permintaan dengan kunci API yang disertakan di header:

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "Explain how AI works in a few words"
          }
        ]
      }
    ]
  }'

Untuk mengetahui petunjuk tentang cara meneruskan kunci ke API menggunakan Gemini SDK, lihat panduan Menggunakan kunci Gemini API.

Pembuatan konten

Ini adalah endpoint pusat untuk mengirimkan perintah ke model. Ada dua endpoint untuk membuat konten, dan perbedaan utamanya adalah cara Anda menerima respons:

  • generateContent (REST): Menerima permintaan dan memberikan satu respons setelah model menyelesaikan seluruh pembuatan.
  • streamGenerateContent (SSE): Menerima permintaan yang sama persis, tetapi model melakukan streaming kembali potongan respons saat respons tersebut dibuat. Hal ini memberikan pengalaman pengguna yang lebih baik untuk aplikasi interaktif karena memungkinkan Anda menampilkan hasil parsial secara langsung.

Struktur isi permintaan

Isi permintaan adalah objek JSON yang identik untuk mode standar dan streaming serta dibuat dari beberapa objek inti:

  • Content objek: Mewakili satu giliran dalam percakapan.
  • Part objek: Bagian data dalam giliran Content (seperti teks atau gambar).
  • inline_data (Blob): Penampung untuk byte media mentah dan jenis MIME-nya.

Di tingkat tertinggi, isi permintaan berisi objek contents, yang merupakan daftar objek Content, yang masing-masing mewakili giliran dalam percakapan. Dalam sebagian besar kasus, untuk pembuatan teks dasar, Anda akan memiliki satu objek Content, tetapi jika ingin mempertahankan histori percakapan, Anda dapat menggunakan beberapa objek Content.

Berikut menunjukkan isi permintaan generateContent yang umum:

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
          "role": "user",
          "parts": [
              // A list of Part objects goes here
          ]
      },
      {
          "role": "model",
          "parts": [
              // A list of Part objects goes here
          ]
      }
    ]
  }'

Struktur isi respons

Isi respons serupa untuk kedua mode streaming dan standar, kecuali untuk hal berikut:

Di tingkat tinggi, isi respons berisi objek candidates, yang merupakan daftar objek Candidate. Objek Candidate berisi objek Content yang memiliki respons yang dihasilkan yang ditampilkan dari model.

Contoh permintaan

Contoh berikut menunjukkan cara komponen ini digabungkan untuk berbagai jenis permintaan.

Perintah hanya teks

Perintah teks sederhana terdiri dari array contents dengan satu objek Content. Array parts objek tersebut, pada gilirannya, berisi satu objek Part dengan kolom text.

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "Explain how AI works in a single paragraph."
          }
        ]
      }
    ]
  }'

Perintah multimodal (teks dan gambar)

Untuk memberikan teks dan gambar dalam perintah, array parts harus berisi dua objek Part: satu untuk teks, dan satu untuk inline_data gambar.

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
    "contents": [{
    "parts":[
        {
            "inline_data": {
            "mime_type":"image/jpeg",
            "data": "/9j/4AAQSkZJRgABAQ... (base64-encoded image)"
            }
        },
        {"text": "What is in this picture?"},
      ]
    }]
  }'

Percakapan multi-giliran (chat)

Untuk membuat percakapan dengan beberapa giliran, Anda menentukan array contents dengan beberapa objek Content. API akan menggunakan seluruh histori ini sebagai konteks untuk respons berikutnya. role untuk setiap objek Content harus bergantian antara user dan model.

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          { "text": "Hello." }
        ]
      },
      {
        "role": "model",
        "parts": [
          { "text": "Hello! How can I help you today?" }
        ]
      },
      {
        "role": "user",
        "parts": [
          { "text": "Please write a four-line poem about the ocean." }
        ]
      }
    ]
  }'

Poin-poin penting

  • Content adalah amplop: Ini adalah penampung tingkat atas untuk giliran pesan, baik dari pengguna maupun model.
  • Part memungkinkan multimodalitas: Gunakan beberapa objek Part dalam satu objek Content untuk menggabungkan berbagai jenis data (teks, gambar, URI video, dll.).
  • Pilih metode data Anda:
    • Untuk media kecil yang disematkan langsung (seperti sebagian besar gambar), gunakan Part dengan inline_data.
    • Untuk file yang lebih besar atau file yang ingin Anda gunakan kembali di seluruh permintaan, gunakan File API untuk mengupload file dan mereferensikannya dengan bagian file_data.
  • Kelola histori percakapan: Untuk aplikasi chat yang menggunakan REST API, buat array contents dengan menambahkan objek Content untuk setiap giliran, bergantian antara "user" dan "model" peran. Jika Anda menggunakan SDK, lihat dokumentasi SDK untuk mengetahui cara yang direkomendasikan untuk mengelola histori percakapan.

Contoh respons

Contoh berikut menunjukkan cara komponen ini digabungkan untuk berbagai jenis permintaan.

Respons hanya teks

Respons teks default terdiri dari array candidates dengan satu atau beberapa objek content yang berisi respons model.

Berikut adalah contoh respons standar:

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "At its core, Artificial Intelligence works by learning from vast amounts of data ..."
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 1
    }
  ],
}

Berikut adalah serangkaian respons streaming. Setiap respons berisi responseId yang mengikat respons lengkap:

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "The image displays"
          }
        ],
        "role": "model"
      },
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": ...
  },
  "modelVersion": "gemini-3.5-flash",
  "responseId": "mAitaLmkHPPlz7IPvtfUqQ4"
}

...

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": " the following materials:\n\n*   **Wood:** The accordion and the violin are primarily"
          }
        ],
        "role": "model"
      },
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": ...
  }
  "modelVersion": "gemini-3.5-flash",
  "responseId": "mAitaLmkHPPlz7IPvtfUqQ4"
}

Live API (BidiGenerateContent) WebSocket API

Live API menawarkan API berbasis WebSocket stateful untuk streaming dua arah guna mengaktifkan kasus penggunaan streaming real-time. Anda dapat meninjau panduan Live API dan referensi Live API untuk mengetahui detail selengkapnya.

Model khusus

Selain rangkaian model Gemini, Gemini API menawarkan endpoint untuk model khusus seperti Imagen, Lyria dan model embedding. Anda dapat melihat panduan ini di bagian Model.

Platform API

Endpoint lainnya memungkinkan kemampuan tambahan untuk digunakan dengan endpoint utama yang dijelaskan sejauh ini. Lihat topik Mode batch dan File API di bagian Panduan untuk mempelajari lebih lanjut.

Langkah berikutnya

Jika Anda baru memulai, lihat panduan berikut, yang akan membantu Anda memahami model pemrograman Gemini API:

Anda mungkin juga ingin melihat panduan kemampuan, yang memperkenalkan berbagai fitur Gemini API dan memberikan contoh kode: