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 diatur berdasarkan endpoint utama berikut:

  • Pembuatan konten standar (generateContent): Endpoint REST standar yang memproses permintaan Anda dan menampilkan respons lengkap model dalam satu paket. Cara ini paling cocok untuk tugas non-interaktif di mana Anda dapat menunggu seluruh hasilnya.
  • Pembuatan konten streaming (streamGenerateContent): Menggunakan Server-Sent Events (SSE) untuk mengirimkan potongan respons kepada Anda saat potongan tersebut dibuat. Hal ini memberikan pengalaman yang lebih cepat dan interaktif untuk aplikasi seperti chatbot.
  • Live API (BidiGenerateContent): API berbasis WebSocket yang memiliki status 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 input Content.
  • 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 ini yang sudah terintegrasi dan 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 dengan beberapa klik di Google AI Studio.

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

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.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 cara meneruskan kunci Anda ke API menggunakan Gemini SDK, lihat panduan Menggunakan kunci API Gemini.

Pembuatan konten

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

  • generateContent (REST): Menerima permintaan dan memberikan satu respons setelah model menyelesaikan seluruh proses pembuatannya.
  • streamGenerateContent (SSE): Menerima permintaan yang sama persis, tetapi model melakukan streaming kembali potongan respons saat respons tersebut dihasilkan. 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:

  • Objek Content: Mewakili satu giliran dalam percakapan.
  • Objek Part: 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 ini menunjukkan isi permintaan generateContent yang umum:

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.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 mode streaming dan standar, kecuali untuk hal berikut:

Secara umum, 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-2.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 gambar inline_data.

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.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 membangun 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-2.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 teratas 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 secara 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 merujuknya dengan bagian file_data.
  • Mengelola histori percakapan: Untuk aplikasi chat yang menggunakan REST API, buat array contents dengan menambahkan objek Content untuk setiap giliran, bergantian antara peran "user" dan "model". 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 sederhana 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 seluruh respons:

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "The image displays"
          }
        ],
        "role": "model"
      },
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": ...
  },
  "modelVersion": "gemini-2.5-flash-lite",
  "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-2.5-flash-lite",
  "responseId": "mAitaLmkHPPlz7IPvtfUqQ4"
}

Live API (BidiGenerateContent) WebSockets 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 embedding. Anda dapat melihat panduan ini di bagian Model.

Platform API

Endpoint lainnya mengaktifkan kemampuan tambahan untuk digunakan dengan endpoint utama yang telah 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 juga dapat melihat panduan kemampuan, yang memperkenalkan berbagai fitur Gemini API dan memberikan contoh kode: