Gemini Native API

Overview

AIone supports calling the gateway directly using the Google Gemini native API format, suitable for custom gateway aggregation, the Google Gemini SDK, and scenarios where you already have Gemini integration code.

The request and response formats are fully identical to the Google Gemini API. The gateway only handles authentication, routing, and billing — no format conversion is performed.

Connection Details

Note: Use your AIone API Key (sk-nex-xxx), not a Google API Key.

Authentication methods

For client compatibility the gateway accepts four ways to carry the API key — use any one (always your sk-nex- AIone key):

Prefer a header (Authorization / x-goog-api-key). The ?key= query param may be recorded by access logs or proxy caches and is less safe; if a client sends both, the header wins.

This means you can point the official Google google-genai SDK straight at this gateway with no auth-code changes — the x-goog-api-key header the SDK sends by default is recognized correctly (just put your sk-nex- key in it).

Supported Models

All connected Gemini models are available through the native API, including:

Text / multimodal models: gemini-2.5-flash, gemini-2.5-pro, gemini-3-pro-preview, gemini-3-flash-preview, gemini-3.1-pro-preview, etc. (the -pro series supports image / video / audio understanding — see Multimodal Understanding)

Image generation models: gemini-3.1-flash-image-preview, gemini-3-pro-image-preview, gemini-2.5-flash-image, etc.

For the full list, query GET https://api.portal.aiin1.ai/v1/models.

Non-Streaming Request — generateContent

Basic Example

curl https://api.portal.aiin1.ai/v1beta/models/gemini-2.5-flash:generateContent \
  -H "Authorization: Bearer sk-nex-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "Explain quantum computing in one sentence"}]}
    ],
    "generationConfig": {
      "maxOutputTokens": 256,
      "temperature": 0.7
    }
  }'

Response Format

{
  "candidates": [
    {
      "content": {
        "parts": [{"text": "Quantum computing leverages quantum mechanics principles..."}],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 10,
    "candidatesTokenCount": 25,
    "totalTokenCount": 35
  },
  "modelVersion": "gemini-2.5-flash"
}

Image Generation Example

curl https://api.portal.aiin1.ai/v1beta/models/gemini-3.1-flash-image-preview:generateContent \
  -H "Authorization: Bearer sk-nex-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "Draw a cute cat"}]}
    ],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "maxOutputTokens": 4096,
      "imageConfig": {
        "imageSize": "2K",
        "aspectRatio": "16:9"
      }
    }
  }'

Images are returned as inlineData (base64-encoded) in the candidates[0].content.parts[] of the response.

Note: 4K image generation may take 2-3 minutes. Set your client's HTTP timeout to at least 600 seconds.

Multimodal Understanding (image / video / audio input)

Besides text, contents[].parts[] can carry images, video, or audio for the model to understand (supported by multimodal text models such as gemini-2.5-pro, gemini-3.1-pro-preview). Two ways to pass a file:

Supported video formats: video/mp4, video/webm, video/mov, video/avi, video/mpeg, video/3gpp, etc.

Example A: inline base64 video (small file)

curl https://api.portal.aiin1.ai/v1beta/models/gemini-3.1-pro-preview:generateContent \
  -H "x-goog-api-key: sk-nex-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [
        {"text": "Which colors appear in this video, in order? List them comma-separated."},
        {"inline_data": {"mime_type": "video/mp4", "data": "<base64 of the video file>"}}
      ]
    }]
  }'

Example B: public URL video (large file)

curl https://api.portal.aiin1.ai/v1beta/models/gemini-3.1-pro-preview:generateContent \
  -H "Authorization: Bearer sk-nex-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [
        {"text": "What animal is the main character in this video? Answer in one sentence."},
        {"file_data": {"mime_type": "video/mp4", "file_uri": "https://example.com/sample-video.mp4"}}
      ]
    }]
  }'

Image understanding works the same way: set mime_type to image/jpeg / image/png (inline inline_data or file_data with a URL).

Timeout: video understanding takes anywhere from tens of seconds to minutes depending on video length and model; with a public URL, add the time for the upstream to fetch that URL. Set your HTTP timeout to ≥ 300 seconds.

Google File API upload is not supported (/upload/v1beta/files and files/{id} references).

⚠️ For material larger than ~15 MB, use Large file upload: a public https:// URL in file_data only gets its first ~15 MB read by the upstream — anything beyond that is silently dropped (no error, but the model only "sees" the opening segment). To have the model understand a large file in full, first get a gs:// reference from the Large file upload endpoint, then use it as file_data.file_uri.

Streaming Request — streamGenerateContent

Append ?alt=sse to the endpoint URL. The response is returned as SSE (Server-Sent Events) chunks.

Example

curl https://api.portal.aiin1.ai/v1beta/models/gemini-2.5-flash:streamGenerateContent?alt=sse \
  -H "Authorization: Bearer sk-nex-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "Write a poem about spring"}]}
    ],
    "generationConfig": {
      "maxOutputTokens": 512
    }
  }'

SSE Response Format

data: {"candidates":[{"content":{"parts":[{"text":"Spring"}],"role":"model"},"index":0}],"usageMetadata":{"promptTokenCount":8,"candidatesTokenCount":2,"totalTokenCount":10}}

data: {"candidates":[{"content":{"parts":[{"text":" breeze blows,"}],"role":"model"},"index":0}],"usageMetadata":{"promptTokenCount":8,"candidatesTokenCount":5,"totalTokenCount":13}}

data: {"candidates":[{"content":{"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":8,"candidatesTokenCount":28,"totalTokenCount":36}}

Each data: line is an independent JSON object. usageMetadata values are cumulative — the last chunk contains the final usage totals.

Note: Image generation models do not support streamGenerateContent. Use generateContent instead.

Python SDK Example

import google.generativeai as genai
 
genai.configure(
    api_key="sk-nex-your-key-here",
    transport="rest",
    client_options={"api_endpoint": "https://api.portal.aiin1.ai"},
)
 
model = genai.GenerativeModel("gemini-2.5-flash")
response = model.generate_content("Explain quantum computing in one sentence")
print(response.text)

Node.js SDK Example

import { GoogleGenerativeAI } from "@google/generative-ai";
 
const genAI = new GoogleGenerativeAI("sk-nex-your-key-here");
// Custom endpoint configuration required
const model = genAI.getGenerativeModel({ model: "gemini-2.5-flash" });
 
const result = await model.generateContent("Explain quantum computing in one sentence");
console.log(result.response.text());

Note: The official Google SDK may not directly support custom endpoints. If you encounter this limitation, we recommend using direct HTTP calls or a third-party library that supports custom Base URLs.

Comparison with OpenAI-Compatible Format

Both formats access the same set of models and upstream channels. Choose based on your client's requirements.

Limitations & Notes

1. Authentication: Use your AIone sk-nex- API Key, not a Google API Key; four carriers accepted — Authorization / x-goog-api-key / x-api-key headers and the ?key= query param (see Authentication methods)
2. Image models do not support streaming: streamGenerateContent returns 503 for image generation models — use generateContent instead
3. Supported actions: Only generateContent and streamGenerateContent are supported; countTokens, embedContent, etc. are not available
4. Timeout settings: For image generation (especially 4K), set your HTTP timeout to at least 600 seconds; for video understanding, at least 300 seconds
5. Multimodal input limit: inline inline_data is bounded by the 20 MB whole-body cap (raw file ≈ 15 MB); use file_data with a public URL for larger files. Google File API upload is not supported (/upload/v1beta/files)
6. Byte-level passthrough: Both requests and responses are passed through at the byte level — the gateway performs no format conversion