API Reference

This gateway exposes Gemini-style REST routes and an optional OpenAI-compatible Chat Completions route. Requests use JSON bodies, JSON responses, standard HTTP methods, and API-key authentication.

The upstream is the cookie-authenticated Gemini Web application. The Gemini REST surface is a compatibility layer, not Google AI Studio or the official Gemini Developer API.

Authentication

The API uses API keys to authenticate requests. You can view and manage your API keys in the Admin Dashboard. Your API keys carry many privileges, so be sure to keep them secure!

Authorization: Bearer YOUR_API_KEY

x-goog-api-key: YOUR_API_KEY
Authorization: Bearer YOUR_API_KEY
GET /v1beta/models?key=YOUR_API_KEY

Supported Models

Select one of the current Gemini models below and pass its exact ID in the model parameter.

Gemini REST API

These paths match Gemini REST naming. Both v1beta and v1 variants are available.

GET  /v1beta/models
GET  /v1beta/models/{model}
POST /v1beta/models/{model}:generateContent
POST /v1beta/models/{model}:streamGenerateContent
POST /v1beta/models/{model}:countTokens

GET /models accepts pageSize and pageToken, and returns nextPageToken when another page is available.

Generate Content

Send Gemini contents, parts, and optional systemInstruction.

curl "https://aggeee.io.vn/v1beta/models/gemini-3.6-flash:generateContent" \
  -H "x-goog-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "systemInstruction": {"parts": [{"text": "Answer concisely."}]},
    "contents": [{"role": "user", "parts": [{"text": "Hello!"}]}]
  }'

Response

{
  "candidates": [{
    "content": {"role": "model", "parts": [{"text": "Hello!"}]},
    "finishReason": "STOP",
    "index": 0
  }],
  "usageMetadata": {
    "promptTokenCount": 4,
    "candidatesTokenCount": 2,
    "totalTokenCount": 6
  },
  "modelVersion": "gemini-3.6-flash",
  "responseId": "gateway-generated-response-id"
}

Function Calling

Declare functions using functionDeclarations. The gateway validates the selected name and arguments. Your application executes the function; the gateway never executes arbitrary terminal commands.

{
  "contents": [{"role": "user", "parts": [{"text": "Weather in Hue?"}]}],
  "tools": [{"functionDeclarations": [{
    "name": "get_weather",
    "description": "Get current weather for a city",
      "parametersJsonSchema": {
        "type": "OBJECT",
      "properties": {"city": {"type": "STRING"}},
      "required": ["city"]
    }
  }]}],
  "toolConfig": {"functionCallingConfig": {"mode": "AUTO"}}
}

A requested function is returned as a Gemini part:

{
  "candidates": [{"content": {"role": "model", "parts": [{
    "functionCall": {"name": "get_weather", "args": {"city": "Hue"}}
  }]}}]
}

Execute the approved function and send its result in the next request:

{
  "contents": [
    {"role": "user", "parts": [{"text": "Weather in Hue?"}]},
    {"role": "model", "parts": [{"functionCall": {
      "name": "get_weather", "args": {"city": "Hue"}
    }}]},
    {"role": "function", "parts": [{"functionResponse": {
      "name": "get_weather",
      "response": {"temperature": 31, "condition": "Sunny"}
    }}]}
  ]
}

parameters and parametersJsonSchema are both accepted but are mutually exclusive. Function selection is prompt-based emulation because Gemini Web does not expose Google's native Function Calling protocol.

Images and Files

Use Gemini-style inlineData. Each inline part is base64 encoded and limited to 20 MiB by this gateway.

import base64
import requests

with open("image.jpg", "rb") as image_file:
    encoded = base64.b64encode(image_file.read()).decode("ascii")

response = requests.post(
    "https://aggeee.io.vn/v1beta/models/gemini-3.6-flash:generateContent",
    headers={"x-goog-api-key": "YOUR_API_KEY"},
    json={"contents": [{"parts": [
        {"text": "Describe this image."},
        {"inlineData": {"mimeType": "image/jpeg", "data": encoded}}
    ]}]},
    timeout=500,
)
response.raise_for_status()

Persistent fileData.fileUri and resumable Files API uploads are unavailable. Use inlineData.

Streaming and Token Counting

POST /v1beta/models/gemini-3.6-flash:streamGenerateContent?alt=sse
POST /v1beta/models/gemini-3.6-flash:countTokens

The streaming route uses Server-Sent Events. The Gemini Web response is collected first, so this compatibility route currently emits one final event instead of token-level deltas.

With ?alt=sse, the response is text/event-stream. Without it, the endpoint returns the final streamed JSON object with application/json.

countTokens and usageMetadata are estimates, not output from Google's tokenizer.

Supported compatibility generation options are candidateCount: 1, stopSequences, responseMimeType: "application/json", responseSchema, and responseJsonSchema. Parameters that cannot be honored by Gemini Web—such as temperature, topP, topK, seed, and maxOutputTokens—return INVALID_ARGUMENT instead of being silently ignored.

Chat Completions

Creates a model response for the given chat conversation.

import requests

response = requests.post(
    "https://aggeee.io.vn/v1/chat/completions",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "model": "gemini-3.1-pro",
        "messages": [{"role": "user", "content": "Hello!"}],
    },
    timeout=500,
)
response.raise_for_status()
print(response.json()["choices"][0]["message"]["content"])

curl https://aggeee.io.vn/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gemini-3.1-pro",
    "messages": [
      {
        "role": "user",
        "content": "Hello!"
      }
    ]
  }'

{
  "id": "chatcmpl_a1b2c3d4",
  "object": "chat.completion",
  "created": 1718291039,
  "model": "gemini-3.1-pro",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hi there! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0
  }
}

Conversation API

Use conversations when you want Gemini to continue the same underlying chat instead of creating a fresh Gemini chat for every request.

Recommended Flow

# First request: no conversation_id, gateway creates a new Gemini chat.
curl https://aggeee.io.vn/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gemini-3.1-pro",
    "messages": [
      {"role": "user", "content": "My name is Hung."}
    ]
  }'

# Use conversation_id from the first response to continue the same Gemini chat.
curl https://aggeee.io.vn/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gemini-3.1-pro",
    "conversation_id": "conv_xxx",
    "messages": [
      {"role": "user", "content": "What is my name?"}
    ]
  }'

Conversation Response Fields

{
  "id": "chatcmpl_a1b2c3d4",
  "object": "chat.completion",
  "model": "gemini-3.1-pro",
  "conversation_id": "conv_xxx",
  "gemini_metadata": ["gemini_chat_id", "reply_id", "candidate_id"],
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "Your name is Hung."
      }
    }
  ]
}

Compatibility Matrix

Error Codes

Our API uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, or you ran out of credits).

{
  "detail": "Unauthorized"
}

{
  "error": {
    "code": 400,
    "message": "contents must be a non-empty array",
    "status": "INVALID_ARGUMENT"
  }
}