Gemini-compatible API

Moonez.ai supports the Google Gemini request and response format. Use the official google-genai SDK or a Gemini-compatible client with your Moonez.ai key.

Base URL

https://api.moonez.ai/api/gemini/v1beta

Enter this complete address in the Base URL field of a custom Gemini provider, including in Android apps. Use the authentication header x-goog-api-key: <MOONEZ_API_KEY>.

The client should append /models/... to this address, not another /v1beta. For the Python SDK, set base_url_resource_scope=types.ResourceScope.COLLECTION — see the complete configuration in the SDK quickstart.

For example, the full Nano Banana 2.1 generation URL is:

https://api.moonez.ai/api/gemini/v1beta/models/gemini-nano-banana-2.1:generateContent

How it differs from the native API

	Native API	Gemini-compatible API
Base path	`/api/v1`	`/api/gemini/v1beta`
Generation result	`202 Accepted`, then poll `/jobs/{job_id}`	JSON response or SSE stream
Authentication	`Authorization: Bearer <API_KEY>`	`x-goog-api-key: <API_KEY>`
Image result	`result.image_url` download link	Base64 image in `inlineData`
Webhooks	Supported	Not used

Both APIs use the same Moonez.ai key and balance. Clients do not need to poll jobs for Gemini-compatible generation requests.

Authentication

Send your Moonez.ai key in the x-goog-api-key header; the SDK adds it when you set api_key. A ?key= query parameter is also supported.

The key must have permission for the requested model; otherwise, the API returns 403 PERMISSION_DENIED. See Authentication.

Models

The complete model catalog covers every active model and its API interface. The tables below describe models served by Gemini content and music interfaces; Veo uses the separate Interactions endpoint.

Image models

Model	Gemini API ID	Sizes
Nano Banana	`gemini-2.5-flash-image`	1K
Nano Banana 2 Lite	`gemini-3.1-flash-lite-image`	1K only
Nano Banana 2	`gemini-3.1-flash-image`	512px · 1K · 2K · 4K
Nano Banana Pro	`gemini-3-pro-image`	1K · 2K · 4K
Nano Banana 2.1	`gemini-nano-banana-2.1`	1K · 2K · 4K

Nano Banana, Nano Banana 2, and Nano Banana Pro also accept their -preview aliases. Use gemini-3.1-flash-lite-image and gemini-nano-banana-2.1 without that suffix. Nano Banana 2 Lite requires its own permission and has only a 1K tariff; see Lite generation.

Nano Banana 2.1 is also available through the native API: Text-to-image and Image-to-image.

Text models

gemini-4-argon
gemini-3.8-flash
gemini-3-flash-preview
gemini-3.1-flash-lite
gemini-3.1-pro-preview
gemini-3.5-flash
gemini-3.5-flash-lite
gemini-3.6-flash
gemini-3.7-flash

See Text models for details.

Multimodal model

gemini-omni-1.1-flash uses this same content interface and token-based billing. Available input and output modalities depend on the provider. Its dashboard controls are in the multimedia category; see Gemini Omni.

Music models

Model	Method
`lyria-002`	`predict`
`lyria-3-clip-preview`	`interactions` (JSON or SSE)
`lyria-3-pro-preview`	`interactions` (JSON or SSE)
`lyria-3.5`	`interactions` (JSON or SSE)
`lyria-realtime-exp`	WebSocket `BidiGenerateMusic`

Music requires MUSIC permission and a configured price. RealTime uses the separate /ws/google.ai.generativelanguage.v1alpha.GenerativeService.BidiGenerateMusic endpoint, not an HTTP content method. See Music models for SDK setup, native controls, and exact billing behavior.

Image parameters

Set the image size and aspect ratio in generationConfig.imageConfig using imageSize and aspectRatio, respectively. In the Python SDK, these fields are image_size and aspect_ratio inside types.ImageConfig.

aspectRatio is optional. When it is omitted, Moonez.ai does not insert a default value: the model chooses the aspect ratio. Explicit parameters are sent to the provider unchanged, and the provider validates them.

Do not confuse this with the required aspect_ratio field in the native API. See Aspect ratios and Resolutions.

gemini-embedding-2 and gemini-embedding-2-preview use embedContent and batchEmbedContents, not content generation. See Embeddings.

Supported methods

All paths below are appended to the base URL. Provider support for individual methods and parameters can vary.

Method	HTTP request	Result
`generateContent`	`POST /models/{model}:generateContent`	Gemini JSON response
`streamGenerateContent`	`POST /models/{model}:streamGenerateContent?alt=sse`	SSE stream
`countTokens`	`POST /models/{model}:countTokens`	Provider token count, free of charge
`predict`	`POST /models/lyria-002:predict`	Lyria 2 predictions
`interactions`	`POST /interactions`	Lyria 3 native JSON or SSE (`stream: true`)
`models.list`	`GET /models`	Permitted image, text, music, and Omni models; no Veo models or pagination

Music models do not support generateContent, streamGenerateContent, or countTokens. The existing video Interactions endpoint is unchanged. Lyria RealTime is WebSocket-only; use the music guide.

The generationConfig, safetySettings, systemInstruction, and tools fields are passed to the provider unchanged. Responses preserve Gemini fields, including usageMetadata, finishReason, and safetyRatings, when returned by the provider.

Billing

Images are billed by the requested size. The minimum rate is 1K; 512px is billed as 1K, while 2K and 4K have their own rates.
Text is billed using confirmed usageMetadata, with input and output tokens counted separately.
Music is billed per completed track; RealTime per second of delivered audio. Music without final audio is free. An unconfigured price blocks generation.
An amount is reserved during generation, then settled or released.
countTokens is free of charge; availability depends on the model and provider.

See the SDK quickstart for request examples.