AI models

Gemini API integration

Ahena works with the Gemini API (the Gemini Developer API, with keys from Google AI Studio): it checks your key and that your configured model exists and supports generateContent, reports its token limits, and generates an adapter behind the common ahena.ai interface using the official @google/genai SDK. Vertex AI is a different product that Ahena doesn't integrate yet. Your app calls the Gemini API directly.

BetaFull Gemini API docs

What Ahena inspects

Read-only: inspecting and Doctor never change anything at Gemini API.

Whether the key is accepted, sent only in the x-goog-api-key header, never in a URL.
The models the key can see (ahena inspect gemini), with input and output token limits and supported methods.

Nothing to configure

Gemini API has nothing to plan or apply. Ahena gives you Doctor, model discovery and a generated adapter behind the common ahena.ai interface, so each environment can use a different AI provider. See AI providers.

Generated code: src/ahena/ai/providers/gemini.ts behind ahena.ai.generate(), on the official @google/genai SDK (Gemini Developer API, vertexai: false); ahena.ai.raw is the client.

How Ahena verifies

There's nothing to read back: Ahena changes nothing in your Google account, so there's no plan, apply or VERIFIED state. Doctor runs read-only checks and records PASS, INFO, WARNING or FAIL findings.

Checks use only models.list and models.get. The API doesn't expose quota, rate limits or billing tier, and Doctor says so.

What Doctor diagnoses

Key checks from ahena doctor. Each finding says why it matters, where, the impact and whether Ahena can fix it. The full list is in the Gemini API docs.

Check	What it means
`gemini.key`	Key accepted; FAIL for an invalid or leaked key, or one restricted away from the Gemini API.
`gemini.model`	Configured model exists and supports `generateContent`.
`gemini.model_limits`	Input and output token limits (INFO).
`gemini.quota`	Quota and billing tier aren't visible through the API (INFO); in production, check billing and the data-use terms.

More on findings, health and continuous checks: Doctor.

Approvals

There's nothing to approve: connecting, Doctor, ahena inspect and ahena generate change nothing in your Gemini API account. Generated code is written to your repository, where you review it like any other change.

Manual steps

Ahena can't do these for you:

Create a key in Google AI Studio and restrict it to the Gemini API.
Decide whether the key's project needs billing: rate limits and Google's data-use terms differ for unpaid use.
Set GEMINI_API_KEY (and AI_PROVIDER=gemini if several adapters exist) where your app runs.

Credentials and permissions

Name	Secret	Notes
`GEMINI_API_KEY`	Yes	A Gemini API key from Google AI Studio, not a Vertex AI service account.

Least privilege

Gemini API keys have no scopes Ahena can read, so it only checks that the key works.
Restrict the key to the Gemini API (Generative Language API); Ahena only lists and reads models.

Each credential Ahena stores gets its own key and is envelope-encrypted, bound to the environment. See security.

Workflow example

Connect, check, then generate. There's no plan or apply step for an AI provider.

GEMINI_API_KEY=… ahena connect gemini -e production

Connect a Google AI Studio key.

```
ahena doctor -e production
```
Check the key and the configured model.
```
ahena inspect gemini -e production
```
List the models this key can see.
```
ahena generate -e production
```
Write the ahena.ai adapter for this environment's provider.

Verification status

Beta

Available in beta. Every capability is validated by Ahena's automated provider contract and conformance tests; verification against the real service is next.

How Gemini API is tested

Tested against a simulated version of the Gemini API (models.list with page tokens, models.get, invalid, leaked and restricted keys); not yet verified against the real service.
The generated adapter is typechecked against the @google/genai SDK, not run.

The providers overview explains Ahena's testing methodology and what has been verified for every provider.

Limitations

Quota, rate limits and billing tier aren't exposed by the API, so Ahena can't check them.
Vertex AI (service accounts, Google Cloud projects) isn't supported.
The common interface covers text generation. Multimodal input, tools, structured output and streaming use ahena.ai.raw.

Disconnecting

ahena disconnect gemini removes the stored key (delete it in Google AI Studio); nothing in your Google account is changed.