Saltar al contenido principal

​
Descripcion general

Google ofrece dos SDKs oficiales: @google/genai (JavaScript / TypeScript) y google-genai (Python), que cubren todos los endpoints de la API de Gemini. Al apuntar la baseUrl al gateway de AIHubMix y usar tu API Key de la plataforma, puedes invocar Interactions, Embeddings, Context Caching y otras capacidades no cubiertas por la capa compatible con OpenAI a traves del SDK nativo, sin modificar ningun codigo de negocio.

​
Inicio rapido

​
Instalacion

npm install @google/genai
# Requiere >= 2.0.0; se recomienda instalar latest
La Interactions API requiere @google/genai >= 2.0.0 o google-genai >= 2.0.0. Las solicitudes con versiones anteriores del SDK seran rechazadas por el backend de Google (legacy Interactions schema no longer supported).

​
Inicializar el cliente

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({
  apiKey: "sk-***", // Reemplaza con tu API Key generada en AIHubMix
  httpOptions: {
    baseUrl: "https://aihubmix.com/gemini",
  },
});
La baseUrl es fija: https://aihubmix.com/gemini, diferente del endpoint compatible con OpenAI https://aihubmix.com/v1.

​
Interactions API

Interactions es la interfaz de inferencia de nueva generacion de Gemini. Devuelve objetos Interaction estructurados y admite generacion de texto, generacion nativa de imagenes (Nano Banana) y razonamiento en multiples pasos. Actualmente se admite el modo sincrono (interactions.create()); el modo asincrono (Background Interactions: get / cancel / delete) estara disponible proximamente.

​
Generacion de texto

Llama a interactions.create() para iniciar una inferencia. El objeto Interaction devuelto proporciona la propiedad de conveniencia output_text para obtener directamente la ultima salida de texto del modelo. 
const interaction = await ai.interactions.create({
  model: "gemini-3.5-flash",
  input: "Explica la computacion cuantica en una frase",
});

console.log(interaction.output_text);
console.log(interaction.usage);
// { total_tokens, total_input_tokens, total_output_tokens, ... }

​
Generacion nativa de imagenes

Configura la modalidad de salida como imagen mediante response_format. El objeto Interaction devuelto proporciona la propiedad de conveniencia output_image, cuyo campo data contiene los datos de imagen codificados en Base64.
  • Modelo recomendado: gemini-3.1-flash-image (Nano Banana 2, modelo universal de generacion de imagenes).
  • Los valores de response_modalities deben estar en minusculas: ['text', 'image']; las mayusculas son la sintaxis de la API generateContent y devuelven un 400 en la Interactions API.
  • No envies delivery: 'inline' (400 Image delivery mode is not supported) — la Interactions API devuelve datos de imagen en modo inline por defecto.
Parametros de response_format:
CampoDescripcionValores posibles
typeTipo de salida"image"
aspect_ratioRelacion de aspecto"1:1" "3:4" "4:3" "9:16" "16:9"
image_sizeResolucion de salida"1K" "2K" "4K"
mime_typeFormato de imagen"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: propiedad de conveniencia output_image (ultima imagen generada)
if (interaction.output_image?.data) {
  fs.writeFileSync("output.png", Buffer.from(interaction.output_image.data, "base64"));
}

// Metodo 2: recorrer steps, adecuado para salidas mixtas de multiples pasos
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"));
    }
  }
}

​
Salida en streaming

Pasa stream: true para habilitar la transmision en streaming mediante Server-Sent Events (SSE). Los eventos llegan en el siguiente orden: 
interaction.created → status_update → step.start → step.delta → step.stop → interaction.completed
El texto incremental se obtiene mediante event.delta.text; el campo de tipo de evento es event_type.
JavaScript
const stream = await ai.interactions.create({
  model: "gemini-3.5-flash",
  input: "Escribe un haiku sobre la luna",
  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

Obtiene representaciones vectoriales (embeddings) de contenido textual o multimodal a traves del endpoint embedContent.
Para el endpoint compatible con OpenAI /v1/embeddings, consulta Embeddings vectoriales.

​
embedContent

const response = await ai.models.embedContent({
  model: "gemini-embedding-2-preview",
  contents: "What is the meaning of life?",
  config: {
    outputDimensionality: 768, // Opcional: especificar dimension de salida (128-3072), por defecto 3072
  },
});

console.log("dimensions:", response.embeddings[0].values.length); // 768

​
Obtener embeddings por lotes

Pasa un array de Content al parametro contents de embedContent para obtener embeddings de multiples textos en una sola llamada:
JavaScript
const response = await ai.models.embedContent({
  model: "gemini-embedding-2-preview",
  contents: [
    { parts: [{ text: "Primer 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 y parametros disponibles

ModeloLimite de tokens de entradaDimension de salida por defectoModalidades de entradaDescripcion
gemini-embedding-2-preview8.1923.072 (recomendado: 768)Texto, imagen, video, audio, PDFModelo de embedding multimodal mas reciente, admite outputDimensionality
gemini-embedding-0012.0483.072Solo textoModelo de embedding de texto anterior, admite taskType
gemini-embedding-001 admite la especificacion del proposito del embedding mediante config.taskType para optimizar la calidad vectorial en tareas posteriores especificas:
taskTypeProposito
SEMANTIC_SIMILARITYCalculo de similitud semantica
RETRIEVAL_DOCUMENTIndexacion de documentos (lado recuperado)
RETRIEVAL_QUERYConsulta de busqueda (lado que recupera)
CLASSIFICATIONClasificacion de texto
CLUSTERINGAgrupamiento de texto
gemini-embedding-2-preview no admite el parametro taskType. En su lugar, el tipo de tarea se especifica mediante un prefijo en el prompt (p. ej., search_query: ... o search_document: ...).

​
Context Caching (Cache explicito)

El cache explicito permite a los desarrolladores crear, consultar, referenciar y eliminar manualmente objetos CachedContent, ideal para escenarios donde el mismo contexto extenso necesita reutilizarse en multiples solicitudes. A diferencia del cache implicito, el cache explicito gestiona activamente el ciclo de vida desde el lado de la aplicacion.
El cache explicito solo esta disponible para la API generateContent. La Interactions API solo admite cache implicito.
Los modelos sin precios de almacenamiento configurados seran bloqueados por el gateway en solicitudes de creacion de cache (context caching is not available for model), para evitar costos de almacenamiento no contabilizados. Los modelos principales (gemini-2.5-flash, gemini-2.5-pro, etc.) ya estan configurados.

​
Crear CachedContent

Crea un cache mediante caches.create(). ttl (Time-To-Live) controla el periodo de validez del cache; al expirar, se elimina automaticamente. 
const longDocument = "Texto extenso que se referencia 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 en generateContent

Pasa cache.name al parametro cachedContent (JS) o cached_content (Python) para utilizar el cache durante la inferencia. El numero de tokens acertados se refleja en usageMetadata.cachedContentTokenCount. 
const response = await ai.models.generateContent({
  model: "gemini-3.5-flash",
  contents: "Resume los puntos clave del documento anterior",
  config: { cachedContent: cache.name },
});

console.log(response.text);
console.log("cached tokens:", response.usageMetadata?.cachedContentTokenCount);

​
Consultar y eliminar

// Consultar metadatos de CachedContent
const info = await ai.caches.get({ name: cache.name });
console.log("model:", info.model, "expireTime:", info.expireTime);

// Eliminar cache
await ai.caches.delete({ name: cache.name });

​
Matriz de capacidades admitidas

CapacidadEstadoDescripcion
generateContent✅Sin streaming + streaming
systemInstruction / generationConfig✅temperature, maxOutputTokens, etc.
Structured Output (responseSchema)✅Modo JSON
Function Calling✅Declaracion de herramientas functionDeclarations
thinkingConfig✅Salida de cadena de pensamiento
Entrada multimodal✅Imagen / audio / video / PDF via inlineData + Files API
Google Search Grounding✅Mejora por busqueda
countTokens✅Conteo de tokens
Imagen (generateImages)✅Generacion de imagenes Imagen 3
Veo (generateVideos)✅Generacion de video
TTS✅Salida de sintesis de voz
Files API✅Subida y referencia de archivos grandes
Interactions API✅Interfaz de inferencia de nueva generacion (texto + Nano Banana)
Embeddings (embedContent)✅Embeddings vectoriales nativos
Context Caching CRUD✅Gestion de cache explicito
Live API (WebSocket)❌Aun no disponible

​
Preguntas frecuentes

La version del SDK es demasiado antigua. @google/genai debe ser >= 2.0.0 y google-genai debe ser >= 2.0.0. Ejecuta npm install @google/genai@latest o pip install -U google-genai para actualizar a la ultima version.
Algunos nombres de modelos anteriores (como gemini-2.5-flash-image-preview) han sido retirados de la Interactions API. Usa identificadores de modelo actuales como gemini-3.1-flash-image (Nano Banana 2). La API generateContent no se ve afectada.
Los valores de response_modalities en la Interactions API deben estar en minusculas ("text", "image"). Las mayusculas "TEXT" / "IMAGE" son la sintaxis de la API generateContent y no son aceptadas en la Interactions API.
No. El modo vertexai: true del SDK requiere GCP OAuth + parametros project/location, y es incompatible con apiKey (el SDK lanza Project/location and API key are mutually exclusive). Al integrarte a traves de AIHubMix, usa la forma Gemini Developer API — el backend enruta automaticamente.
El gateway bloquea las solicitudes caches.create() para modelos sin precios de almacenamiento configurados, para evitar costos de almacenamiento no contabilizados. Los modelos principales (gemini-2.5-flash, gemini-2.5-pro, etc.) ya estan configurados. Si encuentras este error, verifica que el modelo admita cache explicito.
Ultima actualizacion: 2026-07-07