Authentication

Create an API key in the Moonez.ai dashboard. Use the same key and prepaid balance for both API interfaces, but send the header expected by the endpoint:

Interface	Header
Native jobs, job polling, and balance (/api/v1)	Authorization: Bearer <MOONEZ_API_KEY>
Gemini-compatible content methods and Interactions (/api/gemini/v1beta)	x-goog-api-key: <MOONEZ_API_KEY>

Keep keys in server-side environment variables or a secrets manager. Never include them in browser code, public repositories, or client-visible logs.

Model permissions

A valid key is not enough: enable the required permission for your model.

Permission	Models
Nano Banana	gemini-2.5-flash-image
Nano Banana 2	gemini-3.1-flash-image
Nano Banana 2 Lite	gemini-3.1-flash-lite-image
Nano Banana Pro	gemini-3-pro-image
Nano Banana 2.1	gemini-nano-banana-2.1
Music (MUSIC)	All five Lyria models, including RealTime
Gemini Text	All nine text models, including gemini-4-argon and gemini-3.8-flash; also Gemini Omni and the three Veo variants

Nano Banana 2 Lite has its own permission. An existing Nano Banana 2 key is not automatically permitted to use Lite. A key without the required model permission receives 403.

GET /api/gemini/v1beta/models lists permitted image, text, music, and Omni models. It does not list Veo. See the model catalog.

Existing keys do not receive MUSIC automatically. Enable Lyria music models explicitly in API Keys; an account price must also be configured. RealTime uses the same key and whitelist, checked before the WebSocket upgrade.

IP whitelist

Before your first API request, add your server’s public egress IP to IP Whitelist in the dashboard. The whitelist is required for API access: an empty list or a request from an unlisted IP returns 403.

Use the address from which your server reaches the API, not its private network address. Update the list if your hosting provider changes the egress IP. Dashboard sign-in remains available so you can manage the whitelist.

Idempotency

POST /api/v1/generations accepts an optional Idempotency-Key header. Retrying the same logical request with the same key returns the original job_id instead of creating a duplicate job. Use a fresh key for a new request; do not reuse it for a different model or payload.

This native-job behavior does not extend to Gemini generateContent, streaming, or the Interactions endpoint. Do not assume that adding this header to those methods makes retries idempotent.

curl -sS https://api.moonez.ai/api/v1/generations \
  -H "Authorization: Bearer $MOONEZ_API_KEY" \
  -H "Idempotency-Key: 9f1c8b1e-7c2a-4a86-9b6e-2c5fa0b7d8e1" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-lite-image",
    "prompt": "A ceramic cup in soft studio lighting.",
    "aspect_ratio": "1:1",
    "resolution": "1K"
  }'

Replace the example idempotency key for each new logical generation. See API errors and Gemini-compatible errors for the different response formats.