Gemini-compatible API
Use the official Google Gemini SDK against Moonez.ai by overriding the base URL.
Moonez.ai speaks the Google Gemini generateContent wire format. You can keep using
Google’s official google-genai SDK — or any Gemini-compatible client — and just point
it at us.
Pass this as the SDK's base_url:
https://api.moonez.ai/api/gemini
The SDK appends /v1beta/models/... itself, so keep the /api/gemini suffix.
How it differs from the native API
Section titled “How it differs from the native API”The Gemini-compatible endpoint is synchronous: a single request returns the result inline, in Gemini JSON. There are no jobs to poll and no webhooks.
| Native API | Gemini-compatible API | |
|---|---|---|
| Style | Asynchronous (202 + poll /jobs) |
Synchronous (result returned inline) |
| Auth header | Authorization: Bearer <API_KEY> |
x-goog-api-key: <API_KEY> |
| Client | cURL / your HTTP client | Official google-genai SDK |
| Image result | Presigned image_url |
Base64 image in the response |
| Text result | — (image-only) | Token-streamed text |
| Webhooks | Supported | Not applicable |
Both APIs use the same Moonez.ai API key and the same balance. Pick whichever fits your stack.
Authentication
Section titled “Authentication”Send your Moonez.ai API key as x-goog-api-key. When you set api_key on the SDK
client, it adds this header for you. A ?key= query parameter is also accepted.
The key must be scoped for the model you request — see
Authentication. A key without permission for the model returns
403 PERMISSION_DENIED.
Models
Section titled “Models”Use any of the supported Gemini model IDs:
Image models
| Model | Gemini model IDs | Resolution |
|---|---|---|
| gemini-2.5-flash-image | gemini-2.5-flash-image-preview |
1K |
| gemini-3.1-flash-image | gemini-3.1-flash-image-preview |
512px · 1K · 2K · 4K |
| gemini-3-pro-image | gemini-3-pro-image-preview |
1K · 2K · 4K |
The -preview-suffixed IDs are aliases for the same models.
Text models (Gemini)
| Model | Notes |
|---|---|
gemini-3-flash-preview |
Preview |
gemini-3.1-flash-lite |
Latest lite |
gemini-3.1-pro-preview |
Preview pro |
gemini-3.5-flash |
Current fast line |
gemini-3.5-flash-lite |
Current lite |
gemini-3.6-flash |
Latest flash |
gemini-3.7-flash |
Latest flash |
Image parameters
Section titled “Image parameters”For image models, set the aspect ratio and size through imageConfig
(aspectRatio, imageSize). imageSize is passed through to and validated by the
model: supported values are 1K (default), 2K, 4K, plus 512px on gemini-3.1-flash-image.
An unsupported value returns 400 INVALID_ARGUMENT. See
Aspect ratios.
Supported methods
Section titled “Supported methods”| Method | Supported | Notes |
|---|---|---|
generateContent |
✅ | Image returned inline as base64; text in the standard Gemini response |
streamGenerateContent |
✅ | SSE (alt=sse) frames, exactly what the SDK consumes |
countTokens |
✅ | Proxied to Google for a real token count |
models.list (ListModels) |
❌ | Reference models by id directly (see the tables above) |
Both directions are a full passthrough: any generationConfig, safetySettings,
systemInstruction, or tools fields you send reach the model unchanged, and the
complete Gemini response — including usageMetadata, finishReason, and
safetyRatings — is returned verbatim.
Billing
Section titled “Billing”- Image models: billed per the requested size, with
1Kas the floor —512pxis billed at the1Krate.2Kand4Kare billed at their own rates. - Text models: billed per token (input and output separately), using the actual
usageMetadatareturned by the model. - A reservation is placed while a request is in flight and settled (or released) when it completes.
See SDK quickstart for end-to-end examples.