> ## Documentation Index > Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt > Use this file to discover all available pages before exploring further. # Integracao com SDK nativo do Gemini > Integre o AIHubMix atraves do SDK @google/genai para acessar Interactions, Embeddings, Context Caching e todas as capacidades nativas da API Gemini ## Visao geral O Google fornece dois SDKs oficiais: `@google/genai` (JavaScript / TypeScript) e `google-genai` (Python), cobrindo todos os endpoints da API Gemini. Ao apontar a `baseUrl` para o gateway do AIHubMix e usar sua API Key da plataforma, voce pode invocar Interactions, Embeddings, Context Caching e outras capacidades nao cobertas pela camada compativel com OpenAI atraves do SDK nativo, sem modificar nenhum codigo de negocio. ## Inicio rapido ### Instalacao ```bash JavaScript / TypeScript theme={null} npm install @google/genai # Requer >= 2.0.0; recomendado instalar latest ``` ```bash Python theme={null} pip install -U google-genai # Requer >= 2.0.0 ``` A Interactions API requer `@google/genai` **>= 2.0.0** ou `google-genai` **>= 2.0.0**. Requisicoes com versoes anteriores do SDK serao rejeitadas pelo backend do Google (`legacy Interactions schema no longer supported`). ### Inicializar o cliente ```js JavaScript theme={null} import { GoogleGenAI } from "@google/genai"; const ai = new GoogleGenAI({ apiKey: "sk-***", // Substitua pela sua API Key gerada no AIHubMix httpOptions: { baseUrl: "https://aihubmix.com/gemini", }, }); ``` ```python Python theme={null} from google import genai client = genai.Client( api_key="sk-***", # Substitua pela sua API Key gerada no AIHubMix http_options={"base_url": "https://aihubmix.com/gemini"}, ) ``` A `baseUrl` e fixa: `https://aihubmix.com/gemini`, diferente do endpoint compativel com OpenAI `https://aihubmix.com/v1`. *** ## Interactions API Interactions e a interface de inferencia de nova geracao do Gemini. Ela retorna objetos `Interaction` estruturados e suporta geracao de texto, geracao nativa de imagens (Nano Banana) e raciocinio em multiplas etapas. Atualmente o **modo sincrono** (`interactions.create()`) e suportado; o modo assincrono (Background Interactions: `get` / `cancel` / `delete`) estara disponivel em breve. ### Geracao de texto Chame `interactions.create()` para iniciar uma inferencia. O objeto `Interaction` retornado fornece a propriedade de conveniencia `output_text` para obter diretamente a ultima saida de texto do modelo. ```js JavaScript theme={null} const interaction = await ai.interactions.create({ model: "gemini-3.5-flash", input: "Explique a computacao quantica em uma frase", }); console.log(interaction.output_text); console.log(interaction.usage); // { total_tokens, total_input_tokens, total_output_tokens, ... } ``` ```python Python theme={null} interaction = client.interactions.create( model="gemini-3.5-flash", input="Explique a computacao quantica em uma frase", ) print(interaction.output_text) ``` ### Geracao nativa de imagens Configure a modalidade de saida como imagem via `response_format`. O objeto `Interaction` retornado fornece a propriedade de conveniencia `output_image`, cujo campo `data` contem os dados da imagem codificados em Base64. * Modelo recomendado: `gemini-3.1-flash-image` (Nano Banana 2, modelo universal de geracao de imagens). * Os valores de `response_modalities` devem estar em **minusculas**: `['text', 'image']`; maiusculas sao a sintaxe da API `generateContent` e retornam um `400` na Interactions API. * Nao envie `delivery: 'inline'` (`400 Image delivery mode is not supported`) -- a Interactions API retorna dados de imagem em modo inline por padrao. **Parametros de `response_format`:** | Campo | Descricao | Valores possiveis | | -------------- | ------------------ | ----------------------------------------- | | `type` | Tipo de saida | `"image"` | | `aspect_ratio` | Proporcao | `"1:1"` `"3:4"` `"4:3"` `"9:16"` `"16:9"` | | `image_size` | Resolucao de saida | `"1K"` `"2K"` `"4K"` | | `mime_type` | Formato da imagem | `"image/png"` `"image/jpeg"` | ```js JavaScript theme={null} import fs from "node:fs"; const interaction = await ai.interactions.create({ model: "gemini-3.1-flash-image", input: "A translucent banana-shaped glass lamp on a white desk, soft studio lighting.", response_modalities: ["text", "image"], response_format: { type: "image", aspect_ratio: "1:1", image_size: "1K" }, }); // Metodo 1: propriedade de conveniencia output_image (ultima imagem gerada) if (interaction.output_image?.data) { fs.writeFileSync("output.png", Buffer.from(interaction.output_image.data, "base64")); } // Metodo 2: percorrer steps, adequado para saidas mistas de multiplas etapas for (const step of interaction.steps ?? []) { for (const block of step.content ?? []) { if (block.type === "image" && block.data) { fs.writeFileSync("output.png", Buffer.from(block.data, "base64")); } } } ``` ```python Python theme={null} import base64 interaction = client.interactions.create( model="gemini-3.1-flash-image", input="A translucent banana-shaped glass lamp on a white desk, soft studio lighting.", response_format={ "type": "image", "aspect_ratio": "1:1", "image_size": "1K", }, ) # Propriedade de conveniencia output_image if interaction.output_image: with open("output.png", "wb") as f: f.write(base64.b64decode(interaction.output_image.data)) ``` ### Saida em streaming Passe `stream: true` para habilitar a transmissao em streaming via Server-Sent Events (SSE). Os eventos chegam na seguinte ordem: ``` interaction.created → status_update → step.start → step.delta → step.stop → interaction.completed ``` O texto incremental e obtido via `event.delta.text`; o campo de tipo de evento e `event_type`. ```js JavaScript theme={null} const stream = await ai.interactions.create({ model: "gemini-3.5-flash", input: "Escreva um haiku sobre a lua", stream: true, }); for await (const event of stream) { if (event.event_type === "step.delta" && event.delta?.type === "text") { process.stdout.write(event.delta.text); } if (event.event_type === "interaction.completed") { console.log("\nUsage:", JSON.stringify(event.interaction?.usage)); } } ``` *** ## Embeddings Obtenha representacoes vetoriais (embeddings) de conteudo textual ou multimodal atraves do endpoint `embedContent`. Para o endpoint compativel com OpenAI `/v1/embeddings`, consulte [Embeddings vetoriais](/pt/api/EBD). ### embedContent ```js JavaScript theme={null} const response = await ai.models.embedContent({ model: "gemini-embedding-2-preview", contents: "What is the meaning of life?", config: { outputDimensionality: 768, // Opcional: especificar dimensao de saida (128-3072), padrao 3072 }, }); console.log("dimensions:", response.embeddings[0].values.length); // 768 ``` ```python Python theme={null} from google.genai import types result = client.models.embed_content( model="gemini-embedding-2-preview", contents="What is the meaning of life?", config=types.EmbedContentConfig( output_dimensionality=768, # Opcional: especificar dimensao de saida (128-3072), padrao 3072 ), ) print(f"dimensions: {len(result.embeddings[0].values)}") # 768 ``` ### Obter embeddings em lote Passe um array de `Content` ao parametro `contents` de `embedContent` para obter embeddings de multiplos textos em uma unica chamada: ```js JavaScript theme={null} const response = await ai.models.embedContent({ model: "gemini-embedding-2-preview", contents: [ { parts: [{ text: "Primeiro texto" }] }, { parts: [{ text: "Segundo texto" }] }, ], }); console.log("count:", response.embeddings.length); // 2 for (const emb of response.embeddings) { console.log("dimensions:", emb.values.length); } ``` ### Modelos e parametros disponiveis | Modelo | Limite de tokens de entrada | Dimensao de saida padrao | Modalidades de entrada | Descricao | | ---------------------------- | --------------------------- | ------------------------ | -------------------------------- | --------------------------------------------------------------------------- | | `gemini-embedding-2-preview` | 8.192 | 3.072 (recomendado: 768) | Texto, imagem, video, audio, PDF | Modelo de embedding multimodal mais recente, suporta `outputDimensionality` | | `gemini-embedding-001` | 2.048 | 3.072 | Apenas texto | Modelo de embedding de texto anterior, suporta `taskType` | `gemini-embedding-001` suporta a especificacao do proposito do embedding via `config.taskType` para otimizar a qualidade vetorial em tarefas posteriores especificas: | `taskType` | Proposito | | --------------------- | ----------------------------------------- | | `SEMANTIC_SIMILARITY` | Calculo de similaridade semantica | | `RETRIEVAL_DOCUMENT` | Indexacao de documentos (lado recuperado) | | `RETRIEVAL_QUERY` | Consulta de busca (lado que recupera) | | `CLASSIFICATION` | Classificacao de texto | | `CLUSTERING` | Agrupamento de texto | `gemini-embedding-2-preview` nao suporta o parametro `taskType`. Em vez disso, o tipo de tarefa e especificado por um prefixo no prompt (p. ex., `search_query: ...` ou `search_document: ...`). *** ## Context Caching (Cache explicito) O cache explicito permite que desenvolvedores criem, consultem, referenciem e excluam manualmente objetos `CachedContent`, ideal para cenarios onde o mesmo contexto longo precisa ser reutilizado em multiplas requisicoes. Diferentemente do [cache implicito](/pt/api/Gemini-Guides#cache-de-contexto), o cache explicito gerencia ativamente o ciclo de vida pelo lado da aplicacao. O cache explicito esta disponivel apenas para a API `generateContent`. A Interactions API suporta apenas cache implicito. Modelos sem precos de armazenamento configurados serao bloqueados pelo gateway em requisicoes de criacao de cache (`context caching is not available for model`), para evitar custos de armazenamento nao contabilizados. Os modelos principais (gemini-2.5-flash, gemini-2.5-pro, etc.) ja estao configurados. ### Criar CachedContent Crie um cache via `caches.create()`. `ttl` (Time-To-Live) controla o periodo de validade do cache; ao expirar, e excluido automaticamente. ```js JavaScript theme={null} const longDocument = "Texto longo referenciado repetidamente...".repeat(500); const cache = await ai.caches.create({ model: "gemini-3.5-flash", config: { contents: longDocument, ttl: "300s", }, }); console.log("CachedContent name:", cache.name); // Formato: cachedContents/xxx ``` ```python Python theme={null} long_document = "Texto longo referenciado repetidamente..." * 500 cache = client.caches.create( model="gemini-3.5-flash", config={ "contents": long_document, "ttl": "300s", }, ) print(f"CachedContent name: {cache.name}") ``` ### Referenciar cache em generateContent Passe `cache.name` ao parametro `cachedContent` (JS) ou `cached_content` (Python) para utilizar o cache durante a inferencia. O numero de tokens em cache utilizados e refletido em `usageMetadata.cachedContentTokenCount`. ```js JavaScript theme={null} const response = await ai.models.generateContent({ model: "gemini-3.5-flash", contents: "Resuma os pontos-chave do documento acima", config: { cachedContent: cache.name }, }); console.log(response.text); console.log("cached tokens:", response.usageMetadata?.cachedContentTokenCount); ``` ```python Python theme={null} response = client.models.generate_content( model="gemini-3.5-flash", contents="Resuma os pontos-chave do documento acima", config={"cached_content": cache.name}, ) print(response.text) print(f"cached tokens: {response.usage_metadata.cached_content_token_count}") ``` ### Consultar e excluir ```js JavaScript theme={null} // Consultar metadados do CachedContent const info = await ai.caches.get({ name: cache.name }); console.log("model:", info.model, "expireTime:", info.expireTime); // Excluir cache await ai.caches.delete({ name: cache.name }); ``` ```python Python theme={null} # Consultar metadados do CachedContent info = client.caches.get(name=cache.name) print(f"model: {info.model} expire_time: {info.expire_time}") # Excluir cache client.caches.delete(name=cache.name) ``` *** ## Matriz de capacidades suportadas | Capacidade | Status | Descricao | | ---------------------------------------- | ------ | ------------------------------------------------------------- | | `generateContent` | ✅ | Sem streaming + streaming | | `systemInstruction` / `generationConfig` | ✅ | temperature, maxOutputTokens, etc. | | Structured Output (`responseSchema`) | ✅ | Modo JSON | | Function Calling | ✅ | Declaracao de ferramentas `functionDeclarations` | | `thinkingConfig` | ✅ | Saida de cadeia de pensamento | | Entrada multimodal | ✅ | Imagem / audio / video / PDF via `inlineData` + Files API | | Google Search Grounding | ✅ | Enriquecimento por busca | | `countTokens` | ✅ | Contagem de tokens | | Imagen (`generateImages`) | ✅ | Geracao de imagens Imagen 3 | | Veo (`generateVideos`) | ✅ | Geracao de video | | TTS | ✅ | Saida de sintese de voz | | Files API | ✅ | Upload e referencia de arquivos grandes | | Interactions API | ✅ | Interface de inferencia de nova geracao (texto + Nano Banana) | | Embeddings (`embedContent`) | ✅ | Embeddings vetoriais nativos | | Context Caching CRUD | ✅ | Gerenciamento de cache explicito | | Live API (WebSocket) | ❌ | Ainda nao suportado | *** ## Perguntas frequentes A versao do SDK esta muito antiga. `@google/genai` deve ser >= 2.0.0 e `google-genai` deve ser >= 2.0.0. Execute `npm install @google/genai@latest` ou `pip install -U google-genai` para atualizar para a versao mais recente. Alguns nomes de modelos anteriores (como `gemini-2.5-flash-image-preview`) foram descontinuados na Interactions API. Use identificadores de modelos atuais como `gemini-3.1-flash-image` (Nano Banana 2). A API `generateContent` nao e afetada. Os valores de `response_modalities` na Interactions API devem estar em minusculas (`"text"`, `"image"`). Maiusculas `"TEXT"` / `"IMAGE"` sao a sintaxe da API `generateContent` e nao sao aceitas na Interactions API. Nao. O modo `vertexai: true` do SDK requer GCP OAuth + parametros project/location, e e incompativel com `apiKey` (o SDK lanca `Project/location and API key are mutually exclusive`). Ao integrar via AIHubMix, use a forma Gemini Developer API -- o backend roteia automaticamente. O gateway bloqueia requisicoes `caches.create()` para modelos sem precos de armazenamento configurados, para evitar custos de armazenamento nao contabilizados. Os modelos principais (gemini-2.5-flash, gemini-2.5-pro, etc.) ja estao configurados. Se encontrar esse erro, verifique se o modelo suporta cache explicito. *** Ultima atualizacao: 2026-07-07