AiHubMix Documentation Hub

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

npm install @google/genai
# Requer >= 2.0.0; recomendado instalar latest

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

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",
  },
});

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.

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, ... }

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"`

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"));
    }
  }
}

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.

JavaScript

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.

embedContent

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

Obter embeddings em lote

Passe um array de Content ao parametro contents de embedContent para obter embeddings de multiplos textos em uma unica chamada:

JavaScript

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, 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.

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

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.

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);

Consultar e excluir

// 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 });

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

interactions.create() retorna um erro de legacy schema

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.

O modelo retorna 404 Not Found

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.

response_modalities retorna 400 Bad Request

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.

E possivel usar vertexai: true?

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.

A criacao do cache reporta: context caching is not available for model

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

​Visao geral

​Inicio rapido

​Instalacao

​Inicializar o cliente

​Interactions API

​Geracao de texto

​Geracao nativa de imagens

​Saida em streaming

​Embeddings

​embedContent

​Obter embeddings em lote

​Modelos e parametros disponiveis

​Context Caching (Cache explicito)

​Criar CachedContent

​Referenciar cache em generateContent

​Consultar e excluir

​Matriz de capacidades suportadas

​Perguntas frequentes

Visao geral

Inicio rapido

Instalacao

Inicializar o cliente

Interactions API

Geracao de texto

Geracao nativa de imagens

Saida em streaming

Embeddings

embedContent

Obter embeddings em lote

Modelos e parametros disponiveis

Context Caching (Cache explicito)

Criar CachedContent

Referenciar cache em generateContent

Consultar e excluir

Matriz de capacidades suportadas

Perguntas frequentes