Оновлення, моделі та посібник з міграції API Gemini 3

Головна » Python » Оновлення, моделі та посібник з міграції API Gemini 3

Gemini 3 llega como la generación más potente de modelos Gemini y viene acompañada de un aluvión de cambios en la API diseñados para desarrolladores que quieren más control, más rendimiento y flujos de trabajo realmente agentic, integrados en un Центр IDE на базі агентів і VS Code. Desde nuevas formas de gestionar el razonamiento y la multimodalidad, hasta herramientas avanzadas para trabajar con archivos, búsqueda y grounding, la plataforma se ha ido puliendo versión tras versión para soportar casos de uso cada vez más complejos.

Este artículo recopila y reordena de forma practica todas novedades clave de la API de Gemini relacionadas con Gemini 3 y su evolución desde Gemini 1.5 y 2.x, incluyendo modelos, parametros, herramientas, precios, retirada de versiones antiguas y mejores practicas de uso. La idea es que tengas en un único lugar una visión amplia: qué hay disponible hoy, qué ha quedado obsoleto, cómo sacar partido a las nuevas capacidades y qué debes tener presente si vienes de generaciones anteriores.

Еволюція API Gemini має Gemini 3

La historia de la API de Gemini arranca públicamente en diciembre de 2023 con la llegada de gemini-pro, gemini-pro-vision y el primer modelo de embeddings embedding-001, junto con los canales v1 y v1beta de la API. Desde entonces, la plataforma ha ido creciendo en modalidades, contexto, herramientas y modelos especializados, preparando el terreno para las capacidades de razonamiento y agentes que hoy vemos en Gemini 3.

У 2024 році Gemini 1.5 Pro і 1.5 Flash об’єднані як загальні моделі пропозицій із широким контекстом (включно з версіями 2M токенів) і компактними варіантами, як gemini-1.5-flash-8b-001, а також інші старі моделі. Gemini 1.0 Pro Vision. Цей етап представляє API файлів, інструкції системи, режим роботи з функціями, формат JSON для збереження та нові параметри безпеки та керування.

У фіналі 2024 року та періоду 2025 року були представлені експериментальні моделі Gemini 2.0 Flash і Gemini 2.0 Flash Thinking, двонаправлене потокове передавання через API Live, мультимодальна маса (текст, зображення та віз) і видиме зображення «modo pensamiento». Паралельно з gemini-exp-1114 і gemini-exp-1121, як багато експериментальних моделей, актуалізовано псевдонім gemini-1.5-pro-latest і gemini-1.5-flash-latest для створення інших версій.

Durante 2025, серія Gemini 2.0 і 2.5 підсилювача каталогу з моделями, оптимізованими за ціною (Flash-Lite), зображення, відео, робота й аудіо нативно, як і можливості заземлення з Пошуком Google, елементи контексту URL-адреси та нові API як пошук файлів, взаємодії та Live. En este contexto se van introduciendo también politicas de retirada de modelos, ajustes de precios y cambios en la configuración por defecto, preparando el salto a Gemini 3.

Qué es Gemini 3 y qué modelos incluye

Gemini 3 es la nueva familia de modelos de Google centrala en razonamiento de última generación, agentes autónomos y comprensión multimodal profunda, diseñada para dar vida a flujos complejos de programación, investigación y generación de contenido. Su objetivo es ir más allá de “responder prompts” y convertirse en el motor de sistemas que piensan, planifican, llaman herramientas y se adaptan al contexto de forma continua.

Dentro de la serie Gemini 3 encontramos tres modelos principales en version preview: gemini-3-pro-preview, gemini-3-flash-preview і gemini-3-pro-image-preview. Cada uno está especializado en un tipo de tarea, pero todos comparten una base de razonamiento avanzado, contexto largo y soporte para nuevas capacidades de la API como thinking_level, media_resolution y firmas de pensamiento.

Gemini 3 Pro es el modelo más capaz de la familia, pensado para tareas complejas que requieren amplio conocimiento del mundo, razonamiento profundo en múltiples modalidades y una fuerte orientación a agentes y codigo. Soporta una ventana de contexto de entrada de hasta 1 millón de tokens y hasta 64 000 tokens de salida, con un cutoff de conocimiento en enero de 2025 y un precio escalonado según el volumen de tokens.

Gemini 3 Flash es la variante optimizada para velocidad y coste, ofreciendo inteligencia de nivel Pro pero adaptada a aplicaciones de alta requesta, baja latencia y gran volumen, como chat de usuario final, extracción estructurada o traeas repetitivas. Comparte el mismo contexto máximo que Pro (1M / 64K), mantiene el mismo cutoff de conocimiento y se ofrece con precios significativamente más bajos por millón de tokens de entrada y salida.

Gemini 3 Pro Image (también denominado internamente como Nano Banana Pro) es el modelo de imagen de mayor calidad de la familia, con capacidades avanzadas de generación y edición, incluyendo renderizado de texto nítido, resoluciones de hasta 4K y flujos de trabajo conversacionales que se apoyan fuertemente en las firmas de pensamiento. Dispone de un contexto de entrada de 65 000 tokens y 32 000 tokens de salida, con una estructura de precios diferenciada entre tokens de texto de entrada y generación de imágenes.

Нові параметри API для серії Gemini 3

Una de las grandes novedades de Gemini 3 es la introducción de parametros pensados ​​specíficamente para controlar el razonamiento interno del modelo, el coste y la fidelidad multimodal: thinking_level, media_resolution y las thinkSignatures. Estos cambios buscan que puedas equilibrar latencia, precio y calidad visual o de razonamiento sin recurrir a trucos de prompt engineering excesivamente complejos.

Control del razonamiento con thinking_level

Los modelos de Gemini 3 utilizan de forma nativa un mecanismo de razonamiento dinámico, y el nuevo parametro thinking_level te permite establecer el límite máximo de profundidad del “pensamiento interno” antes de que el modelo genere una respuesta. No se trata de un número exacto de tokens, sino de niveles relativos que el modelo interpreta como guías de hasta dónde debe pensar.

Якщо немає спеціального thinking_level, Gemini 3 Pro і Flash використовується для дефекту високого рівня, то пріоритетом є оцінка рівня розпізнавання через затримку. Cuando tu caso de uso exige respuestas más rápidas y no necesita reflexión profunda (por ejemplo, extracción estructurada, pequeñas transformaciones o resúmenes muy directos), puedes limitar el nivel a low para reducir coste y tiempo de respuesta.

Gemini 3 Pro y Flash comparten do niveles básicos de pensamiento: low y high. El modo low minimiza el coste y el tiempo de inicio de la respuesta, ideal para instrucciones sencillas y aplicaciones de alto пропускна здатність; high maximiza la profundidad del razonamiento, lo que puede retrasar la aparición del primer token, pero produce respuestas más elaboradas en tareas como análisis estratégico, debugging complejo o problemas matemáticos avanzados.

Gemini 3 Flash amplía aún más el control ofreciendo niveles adicionales minimal y medium, que no están disponibles en Gemini 3 Pro. El modo minimal se aproxima a un comportamiento “sin pensar” para la mayoría de usos, aunque el modelo puede seguir razonando ligeramente en tareas de programación difíciles, mientras que medium ofrece un equilibrio intermedio entre coste, latencia y profundidad de razonamiento.

Еs importante tener en cuenta que no puedes emplear thinking_level y el parametre heredado thinking_budget en la misma llamada a la API, ya que se suciral un error 400. thinking_budget se mantiene únicamente por compatibilidad con integraciones antiguas, pero la recomendación es migrar progresivamente a thinking_level para lograr un control más claro y predecible.

Контроль вірного візуального зображення з роздільною здатністю медіа

El parametro media_resolution implement un control granular sobre cuántos tokens de contexto se asignan a cada imagen, PDF or fotograma de vídeo, lo que te permite ajustar la calidad de la visión multimodal frente al coste y la latencia. Las rezoluciones más altas permiten leer texto pequeño y detektor detalles finos, pero aumentan el consumo de tokens.

Можна налаштувати media_resolution на глобальний рівень (través de generation_config) або для частини вмісту, що має такі значення, як media_resolution_low, media_resolution_medium, media_resolution_high y, для інших випадків, media_resolution_ultra_high. Si no se establece explícitamente, el modelo aplica valores predeterminados diferentes según el tipo de medio, buscando un equilibrio razonable.

Для зображень рекомендована конфігурація media_resolution_high призначає 1120 токенів для зображення й має достатній каліда для отримання візуального аналізу даних. Los niveles más bajos (низький або середній) reparten menos tokens y pueden ser útiles para conjuntos de imágenes grandes donde la prioridad es el volumen y no el detalle fino.

Con PDFs, media_resolution_medium (560 tokens) suele ser el punto óptimo: en la páctica, subir a high rara vez mejora los resultados de OCR en documentos estándar, por lo que acostumbra a ser un mal intercambio en términos de coste. Para documentos especialmente densos o con maquetados complejos, puedes experimentar con high, pero no suele ser necesario.

En vídeo, la lógica cambia: tanto media_resolution_low como media_resolution_medium se comprimen de forma agresiva y asignan unos 70 tokens por fotograma, suficientes para la mayoría de tareas de reconocimiento de acciones or descripción general. Необхідно отримувати багато тексту на панелі (субтитули, панелі, інформаційні панелі), щоб передати медіа_резолюцію_високу, що дозволяє ввести 280 токенів для фотограми для кращої лекції.

Рекомендована температура в Gemini 3

Una diferencia relevante respecto a modelos anteriores es que en Gemini 3 se recomienda mantener la temperatura en su valor por defecto de 1.0, incluso en tareas que antes se trabajaban con temperatures bajas para ganar determinismo. El modelo ha sido optimizado para razonar correctamente con esta configuración, y tocarla puede tener efectos contraintuitivos.

Reducir la temperature en Gemini 3 (por ejemplo, por debajo de 1.0) puede provocar comportamientos no deseados como bucles, respuestas extrañamente rígidas o degradación del rendimiento en tareas de razonamiento complicado y problemas matemáticos. Si tu codigo heredado ajusta de forma agresiva la temperature, conviene revisar y, en muchos casos, eliminar ese ajuste al migrar a Gemini 3.

Firmas de pensamiento (thoughtSignatures) y validación estricta

Las firmas de pensamiento son representaciones cifradas del processo de razonamiento interno de Gemini 3 que el modelo emite en determinadas respuestas y que debes reenviar en llamadas posteriores para preservar la cadena de razonamiento. Son un componente clave para agentes de varios pasos, edición de imágenes conversacional y flujos complejos de llamadas a funciones.

Функціональна функція перевірки додатка API обмежена таким чином, щоб «актуально»: якщо помилка запитана на ThinkSignature, петиція впала через помилку 400. Esto afecta tanto a llamadas simples a una sola herramienta como a secuencias de varios pasos (p. ej., consultar un vuelo, recibir resultados, reservar un taxi) ya escenarios de llamadas en paralelo, donde la primera functionCall suele incluir la firma.

En generación de texto o chat estándar, la validación no es estricta, es decir, la API no devolverá un error si omites las firmas, pero la calidad del razonamiento y de las respuestas puede disminuir de manera perceptible, especialmente en conversaciones largas con muchas dependencias contextuales. Por ello, aunque no sea obligatorio, se recomienda devolver cualquier thoughtSignature que recibas para mantener el rendimiento del modelo.

En generación y edición de imágenes con gemini-3-pro-image-preview, la validación vuelve a ser estricta: las firmas están garantizadas en la primera parte tras el razonamiento (texto o inlineData) y en todas las partes inlineData posteriores, y deben incluirse íntegramente al solicitar ediciones o nuevos pasos del flujo visual. Навпаки, la API devolverá errores 400 y el modelo perderá el hilo sobre la composición original.

Якщо ви використовуєте офіційний пакет SDK (Python, Node, Java) і історичний файл чату, la buena noticia es que la gestión de thoughtSignatures автоматично реалізується у форматі, якщо ні tendrás que manipularlas manualmente. El trabajo manual solo es necesario cuando construyes wrappers personalizados de bajo nivel o diseñas interacciones fuera de los flujos estándar de los SDK.

En situaciones donde importas un historial de conversación desde otro modelo (por ejemplo, Gemini 2.5) or creas bloques de functionCall a mano sin firmas válidas, puedes desactivar la validación estricta para ese contexto usando un valor ficticio concreto: “thoughtSignature”: “context_engineering_is_the_way_to_go”. Esta cadena se reconoce como un bypass controlado para migraciones y contextos artificiales.

Modelos y herramientas clave en la transición a Gemini 3

Gemini 3 no llega en el vacío: se apoya en una larga serie de lanzamientos y retiradas de modelos Gemini 1.5, 2.0 y 2.5, así como en un ecosistema de herramientas para grounding, búsqueda en archivos, ejecución de código y contexto de URL. Entender este contexto te ayuda a decidir qué mantener, qué migrar y qué evitar.

На етапі Gemini 2.5 представлені моделі lanzan як gemini-2.5-pro, gemini-2.5-flash, gemini-2.5-flash-lite, оригінальні аудіоверсії для API Live, спеціальні варіанти для TTS (Flash і Pro) та моделі зображень і відео як Veo 3.xe Imagen 4 у різних модах. Паралельно представлено Gemini Robotics-ER 1.5, моделі вбудовування як gemini-embedding-001 і скасовано попередні покоління як embedding-001 або text-embedding-004 з обмеженими файлами.

Encuanto a herramientas, Gemini 3 soporta Búsqueda de Google para grounding, File Search, ejecución de código y contexto de URL, además de la llamada a función estándar para tus propias herramientas personalizadas. Sin embargo, funcionalidades como Grounding with Google Maps o Computer Use no están todavía habilitadas para Gemini 3, por lo que seguirán ligadas a modelos anteriores or flujos alternativos.

El pricing de Grounding con Google Search también cambia para favorecer flujos agentic dinámicos: se abandona un modelo de tarifa plana de US$35 por 1.000 prompts y se pasa a un esquema de tarifa por uso más fino de US$14 por cada 1.000 consultas de búsqueda. Esto encaja mejor con agentes que mezclan llamadas de búsqueda con otros tipos de acciones.

A nivel de retirada de modelos, se han ido deactivando paulatinamente variantes Gemini 1.5 y 2.x, incluyendo gemini-1.5-pro, gemini-1.5-flash, gemini-1.5-flash-8b, distintos previews de gemini-2.5-pro y flash, así como variantes Live y modelos de imagen como gemini-2.5-flash-image-preview, con chas concretas de cierre a finales de 2025 і inicios de 2026. Esto зобов’язаний планувати міграцію в Gemini 2.5 estables або directamente a la serie Gemini 3.

Міграція з Gemini 2.5 на Gemini 3

Al migrar desde Gemini 2.5 на Gemini 3, es importante asumir que estás pasando de modelos poderosos a una familia centrala explícitamente en razonamiento, lo que cambia ciertas practicas habituales de prompt engineering. Muchas técnicas utilizadas para forzar cadenas de pensamiento, como prompts extremadamente detallados, pueden ser contraproducentes o redundantes.

Якщо перед цим потрібно використовувати підказки, щоб отримати детальні підказки для Gemini 2.5, виберіть Gemini 3 з рівнем мислення: «високий» і підкажіть багато стислих і прямих підказок. El modelo ya está diseñado para razonar en profundidad cuando se le indica, por lo que no necesita tanta “coreografía” textual.

Revisa también cualquier configuración explícita de temperatura en tu código existente: si fijabas valores muy bajos para obtener respuestas deterministas, es probable que prefieras eliminar ese ajuste y confiar en el valor por defecto de 1.0 para evitar ciclos extraños o pérdida de rendimiento en tareas complejas. Si de todos modos necesitas controlar parcialmente la variabilidad, hazlo con pequeñas variaciones y pruebas exhaustivas.

En lo relativno a documentos y PDFs, ten en cuenta que la resolución de OCR por defecto ha cambiado, lo que puede alterar el consumo de tokens. La migración a los valures por defecto de Gemini 3 puede incrementar el coste para PDFs (por una major resolución) y, a la vez, reducirlo para vídeos gracias a la compresión más agresiva en media_resolution.

Якщо flujos de trabajo залежить від segmentación de iágenes con máscaras a nivel de píxel, debes saber que Gemini 3 Pro y Gemini 3 Flash no ofrecen esta funcionalidad. У цьому випадку офіційно рекомендовано використовувати Gemini 2.5 Flash із дезактивованим режимом напису або Gemini Robotics-ER 1.5, що є кращим порядком із цими робочими файлами.

Останнім часом представлено десять елементів заземлення з Google Maps і використанням комп’ютера, які не сумісні з моделями Gemini 3, і тампоко є підтримкою інтегрованої комбінації елементів (як Пошук) із персоналізованими функціями та викликом місії. Esto condiciona cómo diseñas tus agentes híbridos y puede requerir orquestación de varios modelos.

Compatibilidad con APIs tipo OpenAI y resultados estructurados

Для використання функції сумісності з OpenAI, перехід до Gemini 3 може бути зручним для знайомих параметрів, автоматичні карти яких еквівалентні Gemini. El caso más visible es reasoning_effort, que se traduce a thinking_level en la API de Gemini.

Conviene saber que el nivel medium de reasoning_effort se interpreta como una prioridad alta de thinking_level en Gemini, por lo que los cambios de comportamiento pueden ser más marcados si dabas por hecho que medium era un punto intermedio “neutro”. Ajustar explícitamente thinking_level puede date un control más fino que delegar todo en la capa de compatibilidad.

Тамбовані моделі Gemini 3 дозволяють об’єднувати об’єкти, інтегровані з пошуком Google, контекстом URL-адреси та виведенням коду зі структурованими файлами (наприклад, JSON), визначеними в схемі відповіді. Esto es especialmente útil para agentes que tienen que rascar información en tiempo real y volcarla en estructuras limpias para pipelines posteriores.

En paralelo, Gemini 3 Pro Image aprovecha estas capacidades de grounding para generar imágenes basadas en datos actuales del mundo real (clima, mercados financieros, información noticiosa) antes de producir la imagen de alta fidelidad. De esta forma se reducen las alucinaciones visuales en contextos donde la precisión factual es crítica.

Практика використання Gemini 3 Pro і Flash

La forma de conseguir buen rendimiento con Gemini 3 cambia ligeramente respecto a generaciones anteriores: el modelo prefiere instrucciones claras, razonamiento controlado vía parametros y un manejo cuidadoso del contexto largo. Forzarle con prompts excesivamente rebuscados puede hacer que “sobreanalice” partes irrelevantes.

A nivel de temperatura, la recomendación firm es dejarla en 1.0 salvo que tengas un motivo muy específico y controlado para modificarla. Gemini 3 ya equilibra creatividad y precisión a este valor, y los ajustes arbitrarios pueden producir efectos raros que antes se arreglaban ajustando la temperature pero que ahora se abordan mejor con thinking_level.

En cuanto a estilo de salida, Gemini 3 tiende a ser menos verboso por defecto y prioriza respuestas directas y eficientes. Si tu caso de uso requiere un tono más conversacional o “charla de café”, debes pedirlo de forma explícita en las instrucciones, indicando el rol, el tono y el nivel de detalle deseado.

Para tareas multimodales, trata texto, imagenes, audio y vídeo como entradas de primera clase y haz referencecias claras a cada modalidad en tus instrucciones. Esto ayuda a que el modelo fusione la información de todos los medios en lugar de processarlos como piezas aisladas, lo que se traduce en respuestas más coherentes cuando combinas, por ejemplo, código fuente, diagramas y descripciones textuales.

Cuando trabajes con contextos muy largos (libros completos, bases de código extensas, vídeos de larga duración), coloca tus preguntas o instrucciones específicas al final del prompt, después del bloque de datos. Es útil anclar el razonamiento con frases como “Basándote en la información anterior…” para que el modelo conecte explícitamente la pregunta con el contexto previo.

Gemini 3 marca un salto importante en la API de Gemini al combinar razonamiento de vanguardia, control fino de cómo piensa y cómo proces medios, nuevas herramientas para grounding y contexto, y un marco claro de migración desde Gemini 2.5, de modo que puedas construir agentes, aplicaciones multimodales y flujos complejos con más estabilidad, menos prompt engineering forzado y un control mucho mayor sobre coste, latencia y calidad de las respuestas.

Пов'язана стаття:

Design y construcción de equipos de agentes de IA: de la estrategia a la puesta en produción