Panduan Integrasi Gemini API: Panggilan Kompatibel Google dan Konteks Super Besar

I. Ikhtisar

Situs ini menyediakan akses yang kompatibel dengan format Google Gemini API, mendukung dua metode panggilan: generateContent dan pembuatan streaming. Proyek yang menggunakan Google GenAI SDK atau klien yang kompatibel dengan Gemini dapat terhubung dengan mengarahkan alamat permintaan ke gateway Gemini situs kami dan mengganti kunci API dengan kunci sk- dari situs ini.

Model seri Gemini yang saat ini tersedia dapat dilihat di area model (seperti gemini-3.7-flash, gemini-3.6-flash, gemini-3.5-flash, gemini-3.5-flash-lite, dll.). Daftar lengkap dan harga satuan dapat diperiksa melalui GET /v1/models.

II. Alamat API (Endpoint)

Metode	Path	Keterangan
POST	/v1beta/models/{model}:generateContent	Entry point pembuatan Gemini, body permintaan adalah payload generateContent
POST	/v1beta/models/{model}:streamGenerateContent?alt=sse	Pembuatan streaming (SSE)
GET	/v1/models	Daftar model dan harga satuan (tanpa autentikasi)

Alamat Gateway: https://www.relay-api.com. Nama model disertakan dalam URL (/v1beta/models/{model}:generateContent, konsisten dengan Google resmi); body permintaan berupa payload generateContent.

III. Metode Autentikasi

Sama seperti antarmuka situs kami lainnya, gunakan kunci sk- dari situs:

Authorization: Bearer sk-kunci-anda

Juga kompatibel dengan header x-api-key dan header resmi Google x-goog-api-key: sk-kunci-anda.

IV. Memulai Cepat (curl)

4.1 Non-streaming

curl -X POST https://www.relay-api.com/v1beta/models/gemini-3.7-flash:generateContent \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-kunci-anda" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [{"text": "Jelaskan Gemini API dalam satu kalimat"}]
      }
    ],
    "generationConfig": {
      "temperature": 0.7,
      "maxOutputTokens": 512
    }
  }'

4.2 Dengan Instruksi Sistem (systemInstruction)

curl -X POST https://www.relay-api.com/v1beta/models/gemini-3.7-flash:generateContent \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk-kunci-anda" \
  -d '{
    "model": "gemini-3.5-flash",
    "systemInstruction": {
      "parts": [{"text": "Anda adalah insinyur integrasi API senior, harap jawab dengan singkat."}]
    },
    "contents": [
      {"role": "user", "parts": [{"text": "Bagaimana cara memilih antara antarmuka streaming dan non-streaming?"}]}
    ]
  }'

V. Parameter Permintaan

Field	Tipe	Wajib	Keterangan
model	string	Ya	Slug model, misal gemini-3.7-flash
contents	array	Ya	Isi percakapan, elemen berupa {role, parts[]}; nilai role: user / model
contents[].parts	array	Ya	Blok konten, biasanya {text} untuk teks
systemInstruction	object	Tidak	Instruksi sistem, struktur {parts: [{text}]}
generationConfig.temperature	number	Tidak	Suhu pengambilan sampel, default 1.0
generationConfig.topP	number	Tidak	Nucleus sampling
generationConfig.topK	int	Tidak	Top-K sampling
generationConfig.maxOutputTokens	int	Tidak	Jumlah token output maksimum
generationConfig.stopSequences	array	Tidak	Urutan berhenti
stream	bool	Tidak	Apakah respon streaming, default false

VI. Struktur Respon

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [{"text": "Gemini API mendukung teks, input multimodal, dan output streaming."}]
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 16,
    "candidatesTokenCount": 20,
    "totalTokenCount": 36
  }
}

Field	Keterangan
candidates[].content.parts[].text	Teks yang dihasilkan model
candidates[].finishReason	Alasan berhenti: STOP / MAX_TOKENS / SAFETY / RECITATION
usageMetadata.promptTokenCount	Jumlah token input (dasar penagihan)
usageMetadata.candidatesTokenCount	Jumlah token output (dasar penagihan)
usageMetadata.totalTokenCount	Total jumlah token

VII. Output Streaming

Setelah menambahkan "stream": true pada body permintaan, server akan mengembalikan konten kandidat secara bertahap melalui SSE:

data: {"candidates": [{"content": {"parts": [{"text": "Gemini"}]}, "index": 0}]}

data: {"candidates": [{"content": {"parts": [{"text": " API mendukung "}]}, "index": 0}]}

data: {"candidates": [{"content": {"parts": [{"text": "output streaming."}]}, "index": 0, "finishReason": "STOP"}]}

Klien perlu mengurai setiap baris data: dan menggabungkan candidates[0].content.parts[0].text; jika finishReason pada chunk terakhir adalah STOP, maka pembuatan telah selesai.

VIII. Kode Kesalahan Umum

Kode Status HTTP	Makna	Saran Penanganan
400	Format permintaan salah (contents hilang, model tidak ada, dll.)	Periksa body permintaan dan nama model
401	Kunci API tidak valid atau hilang	Periksa header Authorization / x-api-key
403	Kunci dinonaktifkan, saldo habis, atau tidak diotorisasi untuk model/rute ini	Isi ulang saldo atau periksa otorisasi kunci
404	Model atau endpoint tidak ditemukan	Pastikan slug model sudah benar
429	Permintaan terlalu sering	Tunggu sejenak dan coba lagi (backoff)
500	Kesalahan internal server	Coba lagi nanti, jika terus berlanjut hubungi CS

Body respon kesalahan mengikuti struktur {"code": kode status, "message": "deskripsi kesalahan", "data": null}.

IX. Catatan Kompatibilitas

• Google GenAI SDK (google-genai) dapat terhubung melalui endpoint kustom.
• Mendukung semua jenis klien yang kompatibel dengan Gemini yang menggunakan generateContent sebagai target.
• Nama model mengacu pada slug yang dikembalikan oleh GET /v1/models.

Catatan Base URL: Situs ini menerima /v1beta/models/... dan /v1beta/v1beta/models/... (serta /v1/... dan /v1/v1/...), jadi klien yang menambahkan /v1 atau /v1beta secara otomatis tetap dapat berfungsi: Base URL bisa diisi dengan root domain atau alamat yang menyertakan /v1beta. Silakan cek dan salin ID Model di pojok kanan atas halaman "Token" di dasbor.