> ## 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.
# Integracion con SDK nativo de Gemini
> Integra AIHubMix mediante el SDK @google/genai para acceder a Interactions, Embeddings, Context Caching y todas las capacidades nativas de la API de Gemini
## 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
```bash JavaScript / TypeScript theme={null}
npm install @google/genai
# Requiere >= 2.0.0; se recomienda instalar latest
```
```bash Python theme={null}
pip install -U google-genai
# Requiere >= 2.0.0
```
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
```js JavaScript theme={null}
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",
},
});
```
```python Python theme={null}
from google import genai
client = genai.Client(
api_key="sk-***", # Reemplaza con tu API Key generada en AIHubMix
http_options={"base_url": "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.
```js JavaScript theme={null}
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, ... }
```
```python Python theme={null}
interaction = client.interactions.create(
model="gemini-3.5-flash",
input="Explica la computacion cuantica en una frase",
)
print(interaction.output_text)
```
### 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`:**
| Campo | Descripcion | Valores posibles |
| -------------- | -------------------- | ----------------------------------------- |
| `type` | Tipo de salida | `"image"` |
| `aspect_ratio` | Relacion de aspecto | `"1:1"` `"3:4"` `"4:3"` `"9:16"` `"16:9"` |
| `image_size` | Resolucion de salida | `"1K"` `"2K"` `"4K"` |
| `mime_type` | Formato de imagen | `"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: 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"));
}
}
}
```
```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",
},
)
# Propiedad de conveniencia output_image
if interaction.output_image:
with open("output.png", "wb") as f:
f.write(base64.b64decode(interaction.output_image.data))
```
### 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`.
```js JavaScript theme={null}
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](/es/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 dimension de salida (128-3072), por defecto 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 dimension de salida (128-3072), por defecto 3072
),
)
print(f"dimensions: {len(result.embeddings[0].values)}") # 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:
```js JavaScript theme={null}
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
| Modelo | Limite de tokens de entrada | Dimension de salida por defecto | Modalidades de entrada | Descripcion |
| ---------------------------- | --------------------------- | ------------------------------- | -------------------------------- | -------------------------------------------------------------------------- |
| `gemini-embedding-2-preview` | 8.192 | 3.072 (recomendado: 768) | Texto, imagen, video, audio, PDF | Modelo de embedding multimodal mas reciente, admite `outputDimensionality` |
| `gemini-embedding-001` | 2.048 | 3.072 | Solo texto | Modelo 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:
| `taskType` | Proposito |
| --------------------- | ------------------------------------------ |
| `SEMANTIC_SIMILARITY` | Calculo de similitud semantica |
| `RETRIEVAL_DOCUMENT` | Indexacion de documentos (lado recuperado) |
| `RETRIEVAL_QUERY` | Consulta de busqueda (lado que recupera) |
| `CLASSIFICATION` | Clasificacion de texto |
| `CLUSTERING` | Agrupamiento 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](/es/api/Gemini-Guides#cache-de-contexto), 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.
```js JavaScript theme={null}
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
```
```python Python theme={null}
long_document = "Texto extenso que se referencia 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 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`.
```js JavaScript theme={null}
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);
```
```python Python theme={null}
response = client.models.generate_content(
model="gemini-3.5-flash",
contents="Resume los puntos clave del documento anterior",
config={"cached_content": cache.name},
)
print(response.text)
print(f"cached tokens: {response.usage_metadata.cached_content_token_count}")
```
### Consultar y eliminar
```js JavaScript theme={null}
// 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 });
```
```python Python theme={null}
# Consultar metadatos de CachedContent
info = client.caches.get(name=cache.name)
print(f"model: {info.model} expire_time: {info.expire_time}")
# Eliminar cache
client.caches.delete(name=cache.name)
```
***
## Matriz de capacidades admitidas
| Capacidad | Estado | Descripcion |
| ---------------------------------------- | ------ | ---------------------------------------------------------------- |
| `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