Gemini API

Overview

Ahena checks your Gemini API key (the Gemini Developer API, with keys from Google AI Studio) and that your configured model exists and supports generateContent, reports the model's token limits, and generates an adapter behind the common ahena.ai interface using the official @google/genai SDK. Your app calls the Gemini API directly. Ahena is never in the inference path, and its checks never call generateContent on your key.

Vertex AI is a different product. It serves Gemini models through Google Cloud projects, service accounts and IAM, on other hosts. Ahena doesn't integrate Vertex AI yet; this provider only talks to generativelanguage.googleapis.com with an API key.

Package: @ahena/provider-gemini · Category: ai · Default model: gemini-3.8-flash Capabilities: text-generation, model-availability

Maturity: verified against a fake of the API; not yet verified against the real service.

Connection

GEMINI_API_KEY (secret), created in Google AI Studio.

GEMINI_API_KEY=… ahena connect gemini -e production

Ahena sends the key only in the x-goog-api-key header, never as a ?key= query parameter, so it can't end up in URL logs.

Permissions

Gemini API keys carry no scopes Ahena can read, so Ahena only checks that the key works (permissionCheck: "authentication-only"). It calls models.list and models.get, nothing else. Every Gemini API key belongs to a Google Cloud project, which holds its billing and quota. Restrict the key to the Gemini API (Generative Language API): if its API restrictions exclude it, the API answers 403 and Ahena says so.

Capabilities

Network: only generativelanguage.googleapis.com (enforced). models.list is read with pageSize=1000, following nextPageToken until there is none.

Configure

There's nothing to plan or apply: Ahena changes nothing in your Google account. You choose the provider and model in ahena.config.ts (models/… prefixes are accepted and dropped):

ai: {
  provider: { development: "ollama", production: "gemini" },
  model: { development: "llama3.2", production: "gemini-3.8-flash" },
},

Generate

ahena generate gemini writes:

• src/ahena/ai/types.ts: the shared AiAdapter interface.
• src/ahena/ai/providers/gemini.ts: adapter() creates new GoogleGenAI({ apiKey, vertexai: false }) (so GOOGLE_GENAI_USE_VERTEXAI can't silently switch it to Vertex AI) and calls models.generateContent with the system prompt as systemInstruction and maxTokens as maxOutputTokens. A blocked prompt (promptFeedback.blockReason) becomes a clear error.
• .env.example.gemini: GEMINI_API_KEY=.

Limitations

• Quota, rate limits and billing tier aren't visible. The Gemini API doesn't report a key's limits, quota use, or whether its Cloud project has billing. Doctor says so (gemini.quota, INFO) instead of guessing. Check them in Google AI Studio.
• Data-use terms depend on billing, which Ahena can't see. Under Google's Gemini API Additional Terms, unpaid services may use your prompts and responses to improve Google's products (with human review), while paid services (a project with an active Cloud Billing account) don't. In the EEA, Switzerland and the UK the paid-service data terms apply to unpaid use too. Read the terms; Ahena only points to them.
• Vertex AI (service accounts, GCP projects, regional endpoints) isn't supported.
• The common interface covers text generation. Multimodal input, tools, structured output, streaming and thinking settings use ahena.ai.raw.
• ahena drift doesn't track AI providers.

Manual steps

1. Create a key in Google AI Studio (https://aistudio.google.com/apikey) in a project you use for this app, and restrict it to the Gemini API.
2. Decide whether the project needs billing (rate limits and data-use terms differ) and set it up in Google AI Studio.
3. Set GEMINI_API_KEY (and AI_PROVIDER=gemini if several adapters exist) where your app runs.

Doctor checks

Set up step by step

1. Create the key. Open Google AI Studio (https://aistudio.google.com/apikey), go to API Keys, choose Create API key and pick (or create) the Google Cloud project it belongs to. Copy the key.

2. Minimum permissions. Keys have no scopes. Restrict the key to the Gemini API (Generative Language API); nothing else is needed. Ahena only lists and reads models.

3. Connect.

   GEMINI_API_KEY=… ahena connect gemini -e production

4. Verify the connection. ahena inspect gemini -e production lists the models the key can see, with their token limits.

5. Run Doctor. ahena doctor -e production checks the key and your ai.model.

6. Plan. ahena plan -e production lists no Gemini changes: there's nothing to apply.

7. Make a change. Set ai.provider and ai.model in ahena.config.ts, then run ahena generate -e production to write the adapter. Billing and key restrictions are changed in Google AI Studio or Google Cloud.

8. Verify. Run ahena doctor -e production again: gemini.model should be PASS.

9. Troubleshooting.

   Symptom	Cause	What to do
   gemini.key FAIL, connection expired	Invalid, deleted or mistyped key	Create a new key in Google AI Studio and reconnect.
   "reported as leaked"	Google blocked the key	Create a new key; remove the old one from wherever it was exposed.
   Connection needs action (403)	The key's API restrictions exclude the Gemini API	Allow the Generative Language API on the key, or create a new key.
   gemini.model FAIL	Model id wrong, retired, or not a text model	Use a current model from https://ai.google.dev/gemini-api/docs/models.
   HTTP 429 from your app	Rate limit or quota reached	Check the project's limits in Google AI Studio; enable billing for higher limits.
   400 FAILED_PRECONDITION from your app	A prerequisite such as billing or regional availability isn't met	Check the project's billing and region in Google AI Studio.

10. Disconnect and revoke. ahena disconnect gemini -e production removes the stored key. Then delete the key in Google AI Studio (API Keys).

Disconnect behavior

Removes the connection and the key Ahena stored. Delete the key in Google AI Studio (https://aistudio.google.com/apikey). Nothing in your Google account is changed.