Google Gemini models

Google Gemini is a BYOK (bring-your-own-key) LLM provider in ModuleX. You connect your own Google AI API key, then use Gemini models in the LLM node, the Agent node, chat, and the Assistant. Because Gemini is BYOK, Google bills you directly for token usage and ModuleX adds no credit charge on top — see BYOK billing below. For the full list of provider types and how managed versus BYOK selection works, see LLM providers. If you would rather have ModuleX provision and meter the model for you in credits, use ModuleX-managed models instead.

What you need

A Google AI API key

Create a key in Google AI Studio: click Create API Key, select (or create) a Google Cloud project, then copy the key. Google AI keys start with AIza (for example AIzaSy…). ModuleX validates the key against the pattern ^AIza[0-9A-Za-z\-_]{35}$ before saving it.

A ModuleX organization and an owner/admin role

Credentials are scoped to an organization. Connecting and managing integrations requires the owner or admin role — the member role is retired. See roles & permissions.

A ModuleX API key (for programmatic setup)

To connect Gemini over the API or an SDK, you need a ModuleX API key (mx_live_…) and your organization id. See authentication.

Connect Gemini

You connect Gemini by storing your Google AI API key as a credential for the gemini integration. You can do this in the app or programmatically.

In the app

Open the integrations catalog and select Gemini, or open Settings → Credentials.
Choose API Key Authentication and paste your Google AI key.
Optionally set a custom Base URL (defaults to https://generativelanguage.googleapis.com/v1beta) — only needed for Google AI-compatible gateways.
Save. ModuleX validates the key with a minimal request before storing it (see Test a key before saving).

Gemini exposes a single authentication scheme — api_key. Its fields are:

string

required

Your Google AI API key. Stored encrypted and never returned in plaintext. Marked sensitive. Pattern ^AIza[0-9A-Za-z\-_]{35}$; sample format AIzaSyXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.

string

Optional custom API base URL, only needed when pointing at a Google AI-compatible API. Not required and not sensitive. Must match ^https?://.*.

Over the API or an SDK

Create the credential with POST /credentials. ModuleX detects the credential type from the body: an auth_data.api_key value is stored as an api_key credential. Set make_default: true to make this the default Gemini credential for the organization. Every request authenticates with Authorization: Bearer mx_live_… plus the X-Organization-ID header (see authentication).

curl -X POST https://api.modulex.dev/credentials \
  -H "Authorization: Bearer mx_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-Organization-ID: 6f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f" \
  -H "Content-Type: application/json" \
  -d '{
        "integration_name": "gemini",
        "display_name": "Gemini production key",
        "make_default": true,
        "auth_data": { "api_key": "AIzaSy..." }
      }'

import asyncio
from modulex import Modulex

async def main():
    async with Modulex(
        api_key="mx_live_xxxxxxxxxxxxxxxxxxxxxxxx",   # or MODULEX_API_KEY
        organization_id="6f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
    ) as client:
        cred = await client.credentials.create(
            integration_name="gemini",
            display_name="Gemini production key",
            make_default=True,
            auth_data={"api_key": "AIzaSy..."},
        )
        print(cred.id)

asyncio.run(main())

import { Modulex } from "modulex-js";

const client = new Modulex({
  apiKey: "mx_live_xxxxxxxxxxxxxxxxxxxxxxxx",         // or process.env.MODULEX_API_KEY
  organizationId: "6f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
});

const cred = await client.credentials.create({
  integration_name: "gemini",
  display_name: "Gemini production key",
  make_default: true,
  auth_data: { api_key: "AIzaSy..." },
});
console.log(cred.id);

string

The new credential’s identifier. A 201 response returns the credential metadata; the secret is never echoed back.

Creating, listing, and managing credentials and the integration catalog requires the owner or admin role in the organization. A caller without that role receives a 403. The integration-catalog read routes (for example GET /integrations/llm-providers/gemini) are also owner/admin-gated.

Test a key before saving

Use POST /credentials/test-temporary to validate a Gemini key without storing it. ModuleX runs the provider’s test call — a 10-token POST to https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash-lite:generateContent with the header x-goog-api-key set to your key — and reports success when the response status is 200 and includes a candidates field.

curl -X POST https://api.modulex.dev/credentials/test-temporary \
  -H "Authorization: Bearer mx_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-Organization-ID: 6f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f" \
  -H "Content-Type: application/json" \
  -d '{
        "integration_name": "gemini",
        "auth_type": "api_key",
        "auth_data": { "api_key": "AIzaSy..." }
      }'

result = await client.credentials.test_temporary(
    integration_name="gemini",
    auth_type="api_key",
    auth_data={"api_key": "AIzaSy..."},
)
print(result.is_valid, result.status_code)

const result = await client.credentials.testTemporary({
  integration_name: "gemini",
  auth_type: "api_key",
  auth_data: { api_key: "AIzaSy..." },
});
console.log(result.is_valid, result.status_code);

boolean

true when the test call succeeds.

integer

The HTTP status returned by Google’s test endpoint (200 on success).

string

How the credential was validated. For Gemini this is api_call.

string

The cost class of the test call. For Gemini this is minimal (a 10-token request).

Available models

ModuleX serves Gemini models from the catalog at GET /integrations/llm-providers/gemini. The catalog is read-only metadata used by the credential UI and the builder — it is not the execution path. The models below are the ones ModuleX currently advertises for Gemini. Every Gemini model supports vision (image input) and a 1,048,576-token context window.

Model id	Display name	Max input tokens	Max output tokens	Vision	Input $/1M	Output $/1M
`gemini-2.5-pro`	Gemini 2.5 Pro	1,048,576	65,536	Yes	`$2.50`	`$15.00`
`gemini-2.5-flash`	Gemini 2.5 Flash	1,048,576	65,536	Yes	`$0.30`	`$2.50`
`gemini-2.5-flash-lite`	Gemini 2.5 Flash Lite	1,048,576	65,536	Yes	`$0.10`	`$0.40`

Prices in the table are Google’s per-token rates as recorded in the ModuleX catalog, in USD per 1,000,000 tokens. Because Gemini is BYOK, these are the rates Google charges you directly — they are not ModuleX credits. See BYOK billing.

Each model id is the catalog id you select in the app and in node configuration. ModuleX maps the catalog id to the underlying Gemini wire model and request settings:

Show Gemini 2.5 Pro — full catalog fields

string

gemini-2.5-pro — the catalog id you select.

string

Gemini 2.5 Pro

string

Gemini

string

gemini — the routing provider slug.

integer

1048576

integer

65536

boolean

true

integer

5 (quality score, 1–5).

integer

2 (latency score, 1–5; higher is faster).

string

2025-01-01 (knowledge cutoff).

number

2.5

number

15.0

string

ModuleX sends the wire model gemini-2.5-pro (the body_extra.model value). No extra headers are set (headers_extra is empty).

Show Gemini 2.5 Flash — full catalog fields

string

gemini-2.5-flash

string

Gemini 2.5 Flash

string

gemini

integer

1048576

integer

65536

boolean

true

integer

3

integer

3

string

2025-01-01

number

0.3

number

2.5

string

Wire model gemini-2.5-flash (the body_extra.model value); no extra headers.

Show Gemini 2.5 Flash Lite — full catalog fields

string

gemini-2.5-flash-lite

string

Gemini 2.5 Flash Lite

string

gemini

integer

1048576

integer

65536

boolean

true

integer

2

integer

4

string

2025-01-01

number

0.1

number

0.4

string

Wire model gemini-2.5-flash-lite (the body_extra.model value); no extra headers.

The catalog max_output_tokens is the model’s hard ceiling. Separately, ModuleX applies a per-scenario output cap that is lower than the model ceiling and is not exposed through any catalog API response — for every Gemini model it is 8000 for simple chat, 10000 for chat with knowledge, 4000 for an LLM node, 12000 for an Agent node, 32000 for the main Composer agent, and 4000 for a Composer subagent. These caps are internal defaults and may change.

The model list is served from the ModuleX catalog and may change as Google releases or deprecates models. Always read GET /integrations/llm-providers/gemini for the current set rather than hard-coding ids. Catalog reads are cached for up to 10 minutes.

Read the model catalog

curl https://api.modulex.dev/integrations/llm-providers/gemini \
  -H "Authorization: Bearer mx_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-Organization-ID: 6f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f"

detail = await client.integrations.llm_provider_detail("gemini")
for model in detail.models:
    print(model["id"], model["display_name"])

const detail = await client.integrations.llmProvider("gemini");
for (const model of detail.models) {
  console.log(model.id, model.display_name);
}

The response is an integration-detail object whose models array contains the entries shown above, plus an auth_schemas array describing the api_key scheme. A truncated example:

Catalog detail (truncated)

{
  "name": "gemini",
  "display_name": "Gemini",
  "description": "Google's Gemini models for advanced reasoning, multimodal tasks, and long-context processing",
  "integration_type": "llm_provider",
  "version": "1.0.0",
  "categories": ["AI & LLM Providers", "ai", "chat", "reasoning", "multimodal"],
  "auth_schemas": [
    {
      "auth_type": "api_key",
      "display_name": "API Key Authentication",
      "description": "Connect using Google AI API Key"
    }
  ],
  "models": [
    {
      "id": "gemini-2.5-pro",
      "display_name": "Gemini 2.5 Pro",
      "provider_id": "gemini",
      "max_input_tokens": 1048576,
      "max_output_tokens": 65536,
      "supports_vision": true,
      "input_usd_per_1m_tokens": 2.5,
      "output_usd_per_1m_tokens": 15.0
    }
  ]
}

Use Gemini in ModuleX

Once Gemini is connected, select a Gemini model id wherever a model can be chosen:

LLM node

Call Gemini with prompts, variables, and structured output inside a workflow.

Agent node

Run an autonomous step where Gemini can call tools and loop.

Chat

Pick Gemini as the model for a chat conversation.

Assistant

Configure the Assistant to reason and act with a Gemini model.

If your organization holds more than one Gemini credential, ModuleX uses the credential marked default for the gemini integration. Set a different default with POST /credentials/{credential_id}/set-default. See managing credentials.

BYOK billing

Gemini is bring-your-own-key, which changes how usage is billed compared with ModuleX-managed models.

BYOK (Gemini)

Token usage is billed by Google against your own API key. ModuleX adds no credit charge and no markup for the model call itself. BYOK usage is recorded for analytics only — it does not consume ModuleX credits.

Managed (modulexai)

ModuleX provisions the model and bills it in credits through the usage gate, applying a system margin. Use this when you do not want to manage a provider account.

What this means in practice:

No ModuleX credit cost for tokens. A Gemini call made with your Google AI key is not metered in credits. Google invoices you directly at its own rates (the per-million-token prices in the model table).
Other ModuleX usage still applies. Running a workflow or a turn through the Assistant can still consume the flat per-run credit and may pass through the billing gate even when the model itself is BYOK. See credits & metering and usage gating & limits.
Rate limits and quotas are Google’s. Token-rate limits, monthly spend caps, and model availability for a BYOK key are governed by your Google AI account, not by ModuleX.

BYOK is available on all plans — there is no separate ModuleX entitlement that gates connecting your own Gemini key. The pricing matrix on the marketing site lists BYOK for every tier; the only ModuleX-side billing that applies to a BYOK call is the non-model usage described above. TBD: confirm with the billing owner that no per-call ModuleX surcharge applies to BYOK model calls before treating “no markup” as a guarantee.

Errors

Catalog and credential operations return ModuleX’s standard error shapes. See errors & status codes for the full taxonomy.

Status	When it happens	Shape
`400`	Invalid `auth_data`/`auth_type` on credential create, or asking a typed endpoint for the wrong integration type (for example `gemini` is not a tool).	`{detail: string}`
`401`	Missing or invalid `Authorization` / missing `X-Organization-ID`.	`{detail: string}`
`403`	Caller is not an owner/admin in the organization.	`{detail: string}`
`404`	Unknown provider, for example `GET /integrations/llm-providers/<unknown>` returns `LLM provider not found`.	`{detail: string}`
`422`	Query/parameter validation error.	`{detail: [ ... ]}`
`500`	Unhandled server error.	`{detail: string}`

A bad Gemini key does not surface as a ModuleX 401. Connection validation happens against Google: POST /credentials/test-temporary (or saving with validation) returns is_valid: false with the status Google returned (for example 400 from generativelanguage.googleapis.com for an invalid key). The ModuleX request itself still succeeds.

LLM providers

All providers, and how managed vs BYOK selection works.

ModuleX-managed models

The credit-billed managed alternative to BYOK.

Authentication & credentials

How integrations authenticate and the auth schema variants.

Managing credentials

Create, default, rotate, and scope credentials.

Using

Providers

Building

Tools

What you need

Connect Gemini

In the app

Over the API or an SDK

Test a key before saving

Available models

Read the model catalog

Use Gemini in ModuleX

LLM node

Agent node

Chat

Assistant

BYOK billing

BYOK (Gemini)

Managed (modulexai)

Errors

LLM providers

ModuleX-managed models

Authentication & credentials

Managing credentials

​What you need

​Connect Gemini

​In the app

​Over the API or an SDK

​Test a key before saving

​Available models

​Read the model catalog

​Use Gemini in ModuleX

LLM node

Agent node

Chat

Assistant

​BYOK billing

BYOK (Gemini)

Managed (modulexai)

​Errors

​Related

LLM providers

ModuleX-managed models

Authentication & credentials

Managing credentials

What you need

Connect Gemini

In the app

Over the API or an SDK

Test a key before saving

Available models

Read the model catalog

Use Gemini in ModuleX

BYOK billing

Errors

Related