Repository Public
1This guide outlines architectural strategies for building libraries, platforms,2and gateways on top of the Gemini API. It details the technical trade-offs3between using the official GenAI SDKs, the Direct API (REST/gRPC), and the4OpenAI compatibility layer.56Use this guide if you are building tools for other developers, such as7open-source frameworks, enterprise gateways, or SaaS aggregators, and need to8optimize for dependency hygiene, bundle size, or feature parity.910## What is partner integration?1112> [!CAUTION]13> **Caution:** If you are building an end-user application (e.g., a customer support bot, a travel planner), skip this guide and use the [Gemini API14> Get started guide](https://ai.google.dev/gemini-api/docs/get-started). The [GenAI15> SDK](https://ai.google.dev/gemini-api/docs/libraries) is the recommended choice for you.1617A partner is anyone building an integration between the Gemini API and end-user18developers. We categorize partners into four archetypes. Identifying which one19you match most closely will help you choose the right integration path.2021#### Ecosystem framework2223- **Who you are:** Maintainer of an open-source framework (e.g., LangChain, LlamaIndex, Spring AI) or language-specific clients.24- **Your goal:** Broad compatibility. You want your library to work in any environment your user chooses without forcing conflicts.2526#### Runtime and edge platform2728- **Who you are:** SaaS platforms, AI Gateways, or cloud infrastructure providers (e.g., Vercel, Cloudflare, Zapier) where code execution happens in restricted environments.29- **Your goal:** Performance. You need low latency, minimal bundle size, and rapid cold starts.3031#### Aggregator3233- **Who you are:** Platforms, proxies, or internal "Model Gardens" that normalize access across many different LLM providers (e.g. OpenAI, Anthropic, Google) into a single interface.34- **Your goal:** Portability and uniformity.3536#### Enterprise gateway3738- **Who you are:** Internal Platform Engineering teams at large companies building "Golden Paths" for hundreds of internal developers.39- **Your goal:** Standardization, governance, and unified authentication.4041## Comparison at a glance4243**Global best practice:** All partners must send the [`x-goog-api-client`44header](https://ai.google.dev/gemini-api/docs/partner-integration#client-id) regardless of the path chosen.4546| If you are... | Recommended path | Key benefit | Key trade-off | Best practice |47|---|---|---|---|---|48| **Enterprise gateway, ecosystem framework** | **[Google GenAI SDK](https://ai.google.dev/gemini-api/docs/partner-integration#genai-sdk)** | **Gemini Enterprise Agent Platform parity \& speed.** Built-in handling for types, auth, and complex features (e.g., file uploads). Seamless migration to Google Cloud. | **Dependency weight.** Transitive dependencies can be complex and outside of your control. Limited to supported languages (Python/Node/Go/Java). | **Lock versions.** Pin SDK versions in your internal base images to ensure stability across teams. |49| **Ecosystem framework, edge platforms, and aggregators** | **[Direct API](https://ai.google.dev/gemini-api/docs/partner-integration#rest)** *(REST / gRPC)* | **Zero dependencies.** You control the HTTP client and exact bundle size. Full access to all API and model features. | **High developer overhead.** JSON structures can be deeply nested and require strict manual validation and type-checking. | **Use OpenAPI specs.** Automate type generation using our official specs rather than writing them by hand. |50| **Aggregator using OpenAI SDKs that only require text-based workflows** *(Optimizing for legacy portability)* | **[OpenAI compatibility](https://ai.google.dev/gemini-api/docs/partner-integration#openai)** | **Instant portability.** Reuse existing OpenAI-compatible code or libraries. | **Feature ceiling.** Model-specific features (Native video, Caching) may not be available. | **Migration plan.** Use this for rapid validation, but plan to upgrade to Direct API for complete API feature. |5152## Google GenAI SDK integration5354For frameworks, implementing the [Google GenAI SDK](https://ai.google.dev/gemini-api/docs/libraries)55is often the simplest path, given the fewest lines of code in supported56languages.5758For internal platform teams, your primary deliverable is often a "golden path"59that allows product engineers to move fast while complying with security60policies.6162**Benefits:**6364- **Unified interface for Gemini Enterprise Agent Platform migration:** Internal developers often prototype using API Keys (Gemini API) and deploy to Gemini Enterprise Agent Platform (IAM) for production compliance. The SDK abstracts these authentication differences. Similarly for frameworks, you can implement one codepath and support two sets of users.65- **Client-side helpers:** The SDK includes idiomatic utilities that reduce boilerplate for complex tasks.66 - *Examples:* Supporting `PIL` image objects directly in prompts, automatic function calling, and comprehensive types.67- **Day-zero feature access:** New API features are available at launch-time through the SDKs.68- **Improved code generation support:** Local SDK installation exposes type definitions and docstrings to coding assistants (e.g., Cursor, Copilot). This context improves code generation accuracy compared to generating raw REST requests.6970**The trade-off:**7172- **Dependency weight \& complexity:** The SDKs have their own dependencies, which can increase bundle size and potentially supply-chain risk.73- **Versioning:** New API features are often pinned to minimum SDK versions. You may need to push updates to users to access new features or models, which in some cases may require changes in transitive dependencies that affect your users.74- **Protocol limits:** The SDKs only support HTTPS for the main API and WebSockets (WSS) for the Live API. gRPC is not supported using the high-level SDK clients.75- **Language support:** The SDKs support *current* language versions. If you need to support EOL versions (e.g., Python 3.9), you would need to maintain a fork.7677**Best practice:**7879- **Lock versions:** Pin the SDK version in your internal base images to ensure stability across teams.8081## Direct API integration8283If you are distributing a library to thousands of developers, running in a84constrained environment, or building an aggregator that requires Gemini's85bleeding-edge features, you may need to integrate with the API directly using86REST or gRPC.8788**Benefits:**8990- **Full feature access:** Unlike the OpenAI compatibility layer, using the API directly enables Gemini-specific features, such as uploading to the File API, creating content caching and using the bi-directional Live API.91- **Minimal dependencies:** In an environment where dependencies are sensitive due to size or auditing costs. Using the API directly through a standard library like `fetch` or through a wrapper like `httpx` ensures your library remains lightweight.92- **Language agnostic:** This is the only path for languages not covered by the SDKs, such as Rust, PHP, and Ruby, as there are no language restrictions.93- **Performance:** The Direct API has zero initialization overhead, minimizing cold starts in serverless functions.9495**The trade-off:**9697- **Manual Gemini Enterprise Agent Platform implementation:** Unlike the SDK, using the API directly does not automatically handle the authentication differences between AI Studio (API Key) and Gemini Enterprise Agent Platform (IAM). You must implement separate auth handlers if you want to support both environments.98- **No native types or helpers:** You do not get code completions or compile- time checks for request objects unless you implement them yourself. There are no client "helpers" (e.g., function-to-schema converters), so you must manually write this logic yourself.99100**Best practice**101102We expose a machine-readable specification that you can use to generate type103definitions for your library, saving you from writing them by hand. Download the104spec during your build process, generate the types, and ship the compiled code.105106- **Endpoint:** `https://generativelanguage.googleapis.com/$discovery/OPENAPI3_0`107108## OpenAI SDK integration109110If you are a platform that prioritizes a unified schema (OpenAI Chat111Completions) over model-specific features, this is your fastest route.112113**Benefits:**114115- **Low friction:** You can often add Gemini support by changing the `baseURL` and `apiKey`. This is a fast way to integrate "Bring Your Own Key" implementations, adding Gemini support without writing new code.116- **Constraints:** This path is only recommended if you are restricted to the OpenAI SDK and don't require advanced Gemini features like the File API, or manually adding support for tools like Grounding with Google Search.117118**The trade-off:**119120- **Feature limitations:** The compatibility layer provides limitations to core Gemini capabilities. The available server-side tools differ between platforms, and may require manual handling to work with the Gemini API tools.121- **Translation overhead:** Because the OpenAI schema does not map 1:1 to Gemini's architecture, relying on the compatibility layer introduces some complexities that require extra implementation work to solve, such as mapping a user "search" tool to the right platform tool. If you need a significant amount of special-casing, it may be more value to use a dedicated SDK or API for each platform.122123**Best practice**124125Where possible, integrate directly with the Gemini API. However for maximum126compatibility consider using a library that is aware of different providers and127can handle tool and message mapping for you.128129## Best practice for all partners: client identification130131When making calls to the Gemini API as a platform or library, you must132identify your client using the `x-goog-api-client` header.133134This allows Google to identify your specific traffic segments, and if135your library is producing a specific error pattern, we can reach out to help136debug.137138Use the format `company-product/version` (e.g., `acme-framework/1.2.0`).139140### Implementation examples141142### GenAI SDK143144By providing the API client, the SDK automatically appends your custom145header to its internal headers.146147 from google import genai148149 client = genai.Client(150 api_key="...",151 http_options={152 "headers": {153 "x-goog-api-client": "acme-framework/1.2.0",154 }155 }156 )157158### Direct API (REST)159160 curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent?key=$GEMINI_API_KEY" \161 -H 'Content-Type: application/json' \162 -H 'x-goog-api-client: acme-framework/1.2.0' \163 -d '{...}'164165### OpenAI SDK166167 from openai import OpenAI168169 client = OpenAI(170 api_key="...",171 base_url="https://generativelanguage.googleapis.com/v1beta/openai/",172 default_headers={173 "x-goog-api-client": "acme-framework-oai/1.2.0",174 }175 )176177## Next steps178179- Visit the [library overview](https://ai.google.dev/gemini-api/docs/libraries) to learn about the GenAI SDKs180- Browse the [API reference](https://ai.google.dev/api)181- Read the [OpenAI compatibility guide](https://ai.google.dev/gemini-api/docs/openai)