AIR

Google Gemini

Import: from air.providers.gemini import GeminiProvider

Class name: GeminiProvider

Provider name: "gemini"

Constructor

python
GeminiProvider(
    api_key: str,
    model: str,
    base_url: str = "https://generativelanguage.googleapis.com/v1beta",
    timeout: float = 60.0,
    transport: httpx.AsyncBaseTransport | None = None,
)
  • api_key (required): your Gemini API key. Raises AuthenticationError immediately if empty.
  • model (required): for example "gemini-2.5-flash", unless overridden per request by ChatRequest.model.
  • base_url, timeout, transport: same meaning as the other providers.

Authentication

No environment variable is read automatically. Pass your key explicitly, for example os.environ["GEMINI_API_KEY"].

Minimal setup

python
import os
from air import AIR
from air.providers.gemini import GeminiProvider
 
air = AIR()
air.add_provider(GeminiProvider(api_key=os.environ["GEMINI_API_KEY"], model="gemini-2.5-flash"))
response = await air.chat("Hello")

Request format

Sends a POST to {base_url}/models/{model}:generateContent with the API key in an x-goog-api-key header. AIR Message roles map to Gemini's contents format: Role.USER to "user", Role.ASSISTANT to "model". Role.SYSTEM messages are joined and sent separately as system_instruction, matching Gemini's request shape rather than being included in contents. temperature and max_tokens (as maxOutputTokens) are included in generationConfig if set.

Response parsing

Concatenates the text parts of candidates[0].content.parts for the reply. Reads usageMetadata.promptTokenCount, usageMetadata.candidatesTokenCount, and usageMetadata.totalTokenCount into Usage if present.

Error behavior

  • HTTP 401: AuthenticationError.
  • HTTP 403: QuotaExceededError if the error status is RESOURCE_EXHAUSTED and the message mentions quota, credit, or billing; otherwise AuthenticationError.
  • HTTP 429: QuotaExceededError under the same RESOURCE_EXHAUSTED plus keyword condition as above, otherwise RateLimitError.
  • Any other HTTP 400+: ProviderAPIError.
  • Network timeout: ProviderTimeoutError.
  • Other network/connection errors: ProviderAPIError.
  • Non-JSON or unexpected response shape: ProviderResponseError.

Limitations

Gemini's standard error envelope uses the same HTTP status and status value (RESOURCE_EXHAUSTED) for both hard quota exhaustion and ordinary rate limiting, so GeminiProvider also inspects the error message text to tell them apart. This is a best effort heuristic, not a guaranteed classification. Gemini does not expose a remaining-quota endpoint; capacity tracking only reflects usage Gemini reports on each response.