Gemini AI API

Dokumentasi resmi Gemini AI API dari Maelyn API untuk integrasi model Gemini melalui OpenAI-compatible API, mendukung chat, conversation history, streaming, dan image generation

Base Information

BASE_URL_API: https://api.maelyn.eu/api
Path / Endpoint: /ai/gemini
Method: POST
Credit Usage: 5
Authentication: x-maelyn-auth

Endpoint ini menyediakan akses ke model Gemini melalui API yang kompatibel dengan format OpenAI Chat Completions.

Authentication

Setiap request wajib menggunakan API key Maelyn melalui header x-maelyn-auth.

Content-Type: application/json
x-maelyn-auth: YOUR_API_KEY

Contoh:

curl -X POST "https://api.maelyn.eu/api/ai/gemini" \
  -H "Content-Type: application/json" \
  -H "x-maelyn-auth: YOUR_API_KEY" \
  -d '{
    "query": "Halo, jelaskan apa itu Artificial Intelligence"
  }'

Request Body

Request paling sederhana dapat dilakukan menggunakan field query.

{
  "query": "Jelaskan apa itu Artificial Intelligence"
}

Model yang digunakan secara default adalah:

gemini-3.6-flash

Model dapat ditentukan secara manual menggunakan parameter model.

{
  "model": "gemini-3.6-flash",
  "query": "Jelaskan apa itu Artificial Intelligence"
}

Body Parameters

Name	Type	Required	Default	Description
`query`	`string`	No*	-	Pesan/input utama pengguna
`text`	`string`	No*	-	Alias dari `query`
`prompt`	`string`	No*	-	Alias dari `query`
`message`	`string`	No*	-	Alias dari `query`
`messages`	`array`	No	-	Conversation dalam format OpenAI
`history`	`array`	No	-	Riwayat percakapan, maksimal 10 message
`model`	`string`	No	`gemini-3.6-flash`	Model Gemini yang digunakan
`stream`	`boolean`	No	`false`	Mengaktifkan streaming response
`temperature`	`number`	No	-	Mengatur tingkat variasi output
`top_p`	`number`	No	-	Parameter nucleus sampling
`max_tokens`	`number`	No	-	Maksimum token output
`stop`	`string/array`	No	-	Stop sequence
`mode`	`string`	No	`chat`	Mode `chat` atau `image`
`images`	`array`	No	-	Input gambar untuk image-related request

Salah satu dari query, text, prompt, message, atau messages harus tersedia untuk mode chat.

Available Models

Berikut model yang tersedia pada endpoint ini:

Model	Description
`gemini-3.6-flash`	Latest all-around model
`gemini-3.5-flash`	Alias untuk backend Gemini 3.6 Flash
`gemini-3.5-flash-thinking`	Model dengan kemampuan reasoning/deep thinking
`gemini-3.1-pro`	Model Pro
`gemini-auto`	Pemilihan model secara otomatis
`gemini-3.5-flash-thinking-lite`	Reasoning dengan depth yang lebih adaptif
`gemini-flash-lite`	Model ringan untuk response cepat

Jika model tidak termasuk dalam daftar yang didukung, request akan ditolak.

Chat

Simple Chat

Request paling sederhana:

{
  "query": "Apa itu Artificial Intelligence?"
}

Response:

{
  "success": true,
  "model": "gemini-3.6-flash",
  "stream": false,
  "result": {
    "id": "chatcmpl-1ece790360bf",
    "object": "chat.completion",
    "created": 1788540469,
    "text": "Artificial Intelligence adalah teknologi yang memungkinkan komputer...",
    "finish_reason": "stop",
    "usage": {
      "prompt_tokens": 10,
      "completion_tokens": 20,
      "total_tokens": 30
    }
  }
}

Model Selection

Model dapat dipilih melalui parameter model.

{
  "model": "gemini-3.5-flash-thinking",
  "query": "Analisis dampak kecerdasan buatan terhadap perkembangan teknologi."
}

Contoh menggunakan model Pro:

{
  "model": "gemini-3.1-pro",
  "query": "Buat analisis mendalam mengenai perkembangan AI."
}

Jika model tidak diberikan, API otomatis menggunakan:

gemini-3.6-flash

Conversation History

Endpoint mendukung conversation history menggunakan parameter history.

Maksimum history yang dapat dikirim adalah 10 message.

{
  "model": "gemini-3.6-flash",
  "history": [
    {
      "role": "user",
      "content": "Apa itu JavaScript?"
    },
    {
      "role": "assistant",
      "content": "JavaScript adalah bahasa pemrograman..."
    },
    {
      "role": "user",
      "content": "Apa kegunaannya?"
    },
    {
      "role": "assistant",
      "content": "JavaScript banyak digunakan untuk..."
    }
  ],
  "query": "Bagaimana cara mempelajarinya?"
}

Role yang didukung:

user
assistant
system

Contoh conversation:

{
  "history": [
    {
      "role": "user",
      "content": "Nama saya Budi."
    },
    {
      "role": "assistant",
      "content": "Halo Budi!"
    }
  ], 
  "query": "Siapa nama saya?"
}

Messages Format

Selain history, API juga mendukung format messages yang kompatibel dengan OpenAI Chat Completions.

{
  "model": "gemini-3.6-flash",
  "messages": [
    {
      "role": "system",
      "content": "Kamu adalah asisten pemrograman."
    },
    {
      "role": "user",
      "content": "Apa itu REST API?"
    },
    {
      "role": "assistant",
      "content": "REST API adalah..."
    },
    {
      "role": "user",
      "content": "Berikan contohnya."
    }
  ]
}

Maksimum messages yang dapat dikirim adalah 10 message.

Format ini cocok digunakan apabila aplikasi kamu sudah menggunakan struktur OpenAI-compatible messages.

Streaming

Streaming dapat diaktifkan dengan:

{
  "model": "gemini-3.6-flash",
  "query": "Jelaskan sejarah perkembangan komputer.",
  "stream": true
}

Jika stream tidak diberikan:

{
  "stream": false
}

akan digunakan secara default.

Non-Streaming

{
  "query": "Halo!",
  "stream": false
}

API akan menunggu sampai seluruh response selesai kemudian mengembalikan JSON.

Streaming

{
  "query": "Jelaskan apa itu machine learning.",
  "stream": true
}

Pada mode streaming, response dari upstream akan diteruskan sebagai Server-Sent Events (SSE).

Client dapat membaca response secara bertahap tanpa menunggu seluruh jawaban selesai.

Generation Parameters

API mendukung beberapa parameter generation yang kompatibel dengan format OpenAI.

Temperature

{
  "query": "Buatkan cerita pendek tentang AI.",
  "temperature": 0.8
}

Nilai yang lebih tinggi menghasilkan output yang cenderung lebih bervariasi.

Top P

{
  "query": "Jelaskan teknologi blockchain.",
  "top_p": 0.9
}

Max Tokens

{
  "query": "Jelaskan Artificial Intelligence secara detail.",
  "max_tokens": 1000
}

Stop

{
  "query": "Buatkan daftar bahasa pemrograman.",
  "stop": [
    "END"
  ]
}

Image Generation

Endpoint juga mendukung mode image menggunakan:

{
  "mode": "image"
}

Image generation menggunakan adapter image generation internal dan tidak menggunakan Google Gemini API key.

Contoh:

{
  "mode": "image",
  "prompt": "Anime girl with blue hair, futuristic city background"
}

Atau menggunakan query:

{
  "mode": "image",
  "query": "A futuristic cyberpunk city at night"
}

Image Editing

Mode image juga dapat digunakan untuk melakukan editing terhadap gambar.

Input gambar dapat diberikan dalam bentuk URL atau data yang didukung oleh adapter image.

Contoh menggunakan URL:

{
  "mode": "image",
  "prompt": "Ubah background menjadi kota futuristik",
  "images": [
    "https://example.com/image.jpg"
  ]
}

Image Response

Contoh response ketika image generation berhasil:

{
  "success": true,
  "model": "flux",
  "mode": "image",
  "result": {
    "text": null,
    "images": [
      "https://cdn.maelyn.eu/generated-image.png"
    ],
    "finish_reason": "stop",
    "usage": null
  }
}

Field images berisi hasil gambar yang dihasilkan oleh image adapter.

Response Structure

Response chat menggunakan struktur:

{
  "success": true,
  "model": "gemini-3.6-flash",
  "stream": false,
  "result": {
    "id": "chatcmpl-...",
    "object": "chat.completion",
    "created": 1788540469,
    "text": "Response dari model...",
    "finish_reason": "stop",
    "usage": {
      "prompt_tokens": 10,
      "completion_tokens": 20,
      "total_tokens": 30
    }
  }
}

Response Fields

Field	Description
`success`	Status request
`model`	Model yang digunakan
`stream`	Status streaming
`result.id`	ID completion
`result.object`	Tipe object response
`result.created`	Unix timestamp
`result.text`	Response teks dari AI
`result.finish_reason`	Alasan generation selesai
`result.usage`	Informasi penggunaan token

Error Responses

Invalid JSON

Terjadi ketika body request bukan JSON yang valid.

{
  "success": false,
  "error": "INVALID_JSON",
  "message": "Body request harus berupa JSON"
}

Invalid Body

Terjadi ketika body request tidak memiliki format yang sesuai.

{
  "success": false,
  "error": "INVALID_BODY",
  "message": "Body request tidak valid"
}

Query Required

Terjadi ketika request chat tidak memiliki input.

{
  "success": false,
  "error": "QUERY_REQUIRED",
  "message": "Field query wajib diisi"
}

Gunakan salah satu:

query
text
prompt
message
messages

Invalid History

Format history tidak valid.

{
  "success": false,
  "error": "INVALID_HISTORY",
  "message": "Format history tidak valid"
}

Invalid History Message

Salah satu message dalam history memiliki format yang tidak valid.

{
  "success": false,
  "error": "INVALID_HISTORY_MESSAGE",
  "message": "Format message pada history tidak valid"
}

History Limit Exceeded

Jumlah history melebihi batas maksimum 10 message.

{
  "success": false,
  "error": "HISTORY_LIMIT_EXCEEDED",
  "message": "History maksimal 10 message"
}

Invalid Message

Format messages tidak valid.

{
  "success": false,
  "error": "INVALID_MESSAGE",
  "message": "Format message tidak valid"
}

Model Not Supported

Model yang diminta tidak tersedia.

{
  "success": false,
  "error": "MODEL_NOT_SUPPORTED",
  "message": "Model yang dipilih tidak didukung"
}

Gunakan salah satu model yang tersedia pada bagian Available Models.

Upstream API Error

Terjadi masalah ketika API gagal mendapatkan response dari backend Gemini.

{
  "success": false,
  "error": "UPSTREAM_API_ERROR",
  "message": "Gagal mengambil respon dari Gemini"
}

Empty AI Response

Model tidak memberikan response yang dapat digunakan.

{
  "success": false,
  "error": "EMPTY_AI_RESPONSE",
  "message": "AI tidak memberikan response"
}

Request Timeout

Request terlalu lama dan melebihi batas waktu yang ditentukan.

{
  "success": false,
  "error": "REQUEST_TIMEOUT",
  "message": "Request ke AI mengalami timeout"
}

Fetch Failed

Terjadi kegagalan koneksi ke upstream API.

{
  "success": false,
  "error": "FETCH_FAILED",
  "message": "Gagal terhubung ke AI API"
}

Image Generation Failed

Image generation atau image editing gagal.

{
  "success": false,
  "error": "IMAGE_GENERATION_FAILED",
  "message": "Gagal menghasilkan gambar"
}

Internal Server Error

Terjadi kesalahan internal pada Maelyn API.

{
  "success": false,
  "error": "INTERNAL_SERVER_ERROR",
  "message": "Terjadi kesalahan pada sistem"
}

Complete Examples

Basic Request

curl -X POST "https://api.maelyn.eu/api/ai/gemini" \
  -H "Content-Type: application/json" \
  -H "x-maelyn-auth: YOUR_API_KEY" \
  -d '{
    "query": "Apa itu machine learning?"
  }'

Select Model

curl -X POST "https://api.maelyn.eu/api/ai/gemini" \
  -H "Content-Type: application/json" \
  -H "x-maelyn-auth: YOUR_API_KEY" \
  -d '{
    "model": "gemini-3.5-flash-thinking",
    "query": "Jelaskan cara kerja neural network."
  }'

Conversation

{
  "model": "gemini-3.6-flash",
  "history": [
    {
      "role": "user",
      "content": "Saya sedang belajar JavaScript."
    },
    {
      "role": "assistant",
      "content": "Bagus! JavaScript adalah bahasa yang banyak digunakan untuk web."
    }
  ],
  "query": "Apa yang harus saya pelajari selanjutnya?"
}

Streaming

{
  "model": "gemini-3.6-flash",
  "query": "Jelaskan perkembangan AI dari tahun ke tahun.",
  "stream": true
}

Image Generation

{
  "mode": "image",
  "model": "gemini-3.6-flash",
  "prompt": "A beautiful anime city at sunset"
}

Untuk mode image, model chat tidak digunakan sebagai engine image generation. Request akan diproses menggunakan image adapter internal (flux).

Playground

AI ChatGPT