Panduan Akses Gemini API: Kompatibilitas Google dan Konteks Luas

I. Ikhtisar

Situs ini menyediakan akses yang kompatibel dengan format Google Gemini API, mendukung dua metode pemanggilan: 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 akun Anda.

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

II. Alamat Endpoint

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

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

III. Metode Autentikasi

Sama dengan interface lain di situs ini, gunakan kunci sk- dari akun Anda:

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 Menggunakan 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, berikan jawaban yang singkat."}]
    },
    "contents": [
      {"role": "user", "parts": [{"text": "Bagaimana cara memilih antara interface streaming dan non-streaming?"}]}
    ]
  }'

V. Parameter Permintaan

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

VI. Struktur Respons

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [{"text": "Gemini API mendukung input teks, 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 selesai: STOP / MAX_TOKENS / SAFETY / RECITATION
usageMetadata.promptTokenCount	Jumlah token input (basis penagihan)
usageMetadata.candidatesTokenCount	Jumlah token output (basis penagihan)
usageMetadata.totalTokenCount	Total jumlah token

VII. Output Streaming

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

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

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

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

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

VIII. Kode Error Umum

Status HTTP	Arti	Saran Penanganan
400	Format permintaan salah (konten 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 tidak aktif, saldo tidak cukup, atau tidak ada akses ke model ini	Isi saldo atau periksa otoritas kunci
404	Model atau endpoint tidak ditemukan	Konfirmasi slug model
429	Permintaan terlalu sering	Coba kembali nanti
500	Kesalahan internal server	Coba lagi nanti, hubungi layanan pelanggan jika masalah berlanjut

Respons error memiliki struktur terpadu: {"code": status_code, "message": "deskripsi_error", "data": null}.

IX. Catatan Kompatibilitas

• Google GenAI SDK (google-genai) dapat digunakan melalui endpoint kustom.
• Mendukung berbagai klien yang kompatibel dengan Gemini yang menargetkan generateContent.
• Nama model merujuk pada slug yang dikembalikan oleh GET /v1/models.