Tutoriales

GPT Image 2.5 por MCP en Claude, Claude Code y Cursor

Ejecuta GPT Image 2.5 con el servidor MCP de Kubeez desde Claude, Claude Code y Cursor: descubre el modelo, genera, consulta el estado y lanza lotes por ratios.

2026-09-09 · Kubeez

OpenAI anunció GPT Image 2.5 el 8 de septiembre de 2026. Llegó a Kubeez al día siguiente y aterrizó al mismo tiempo en el servidor MCP de Kubeez y en la API REST de Kubeez. Así que, si trabajas dentro de Claude, Claude Code o Cursor, puedes ejecutar GPT Image 2.5 sin abrir una pestaña del navegador: describes la toma, el agente llama a la herramienta y el PNG terminado aterriza en tu biblioteca de Kubeez.

Este artículo es la versión práctica. Todas las imágenes que ves aquí se generaron exactamente con el flujo descrito abajo, a través del servidor MCP de Kubeez, en el carril gpt-image-2-5-flare, a 16:9 y 1K, por 15 créditos cada una.

Si nunca has conectado el servidor MCP de Kubeez, empieza por la guía de automatización con MCP y API o por la primera imagen desde Cursor, y luego vuelve aquí. Para el panorama más amplio está cómo usar Kubeez desde Claude y, para la generación anterior de este mismo stack, GPT Image 2 con la API y el MCP de Kubeez. Este artículo da por hecho que el servidor ya está conectado y se centra en GPT Image 2.5.

Dos carriles, dos ids de modelo

GPT Image 2.5 llega al servidor MCP como dos ids de modelo, no como un modelo con un interruptor de calidad:

Lee la columna de precio dos veces. Los dos carriles cuestan lo mismo en cada resolución, así que el precio no desempata. Flare es el que eliges cuando importa el tiempo de respuesta. Sunburst es el que eliges cuando vas a seguir editando el mismo material y quieres que se mantenga coherente en toda la cadena. Ninguno es un nivel superior al otro y, si quieres la versión larga del argumento, la comparativa Flare frente a Sunburst lo trata a fondo.

Ambos carriles comparten el mismo sobre técnico: texto a imagen e imagen a imagen, hasta 16 imágenes de entrada, prompts de hasta 20.000 caracteres, resoluciones de 1K, 2K y 4K, trece relaciones de aspecto documentadas y ningún prompt negativo.

Paso 1: deja que el agente descubra el modelo

No escribas un id de modelo a fuego sacado de un artículo, ni siquiera de este. Pregúntale al servidor qué tiene:

get_models(model_type="image")

La fila que devuelve para el carril rápido, recortada a los campos que importan:

{
  "model_id": "gpt-image-2-5-flare",
  "display_name": "GPT Image 2.5 Flare",
  "provider": "OpenAI",
  "generation_types": ["text-to-image", "image-to-image"],
  "capabilities": {
    "prompt_max_chars": 20000,
    "aspect_ratio_options": ["auto", "1:1", "3:2", "2:3", "4:3", "3:4",
                             "16:9", "9:16", "21:9", "27:16", "16:27",
                             "9:8", "8:9"],
    "resolution_options": ["1K", "2K", "4K"],
    "max_input_images": 16,
    "supports_negative_prompt": false
  }
}

Esa sola llamada es la razón por la que la ruta MCP se siente distinta de una integración de API escrita a mano. El agente no tiene que adivinar si 21:9 está permitido ni si puede enviar un prompt negativo. Lee aspect_ratio_options, ve trece entradas documentadas, ve supports_negative_prompt: false y construye la llamada bien a la primera.

Una restricción que conviene aprenderse de memoria, porque get_models la indica en sus notas de uso y pilla a mucha gente: 4:5 no está en la lista en ninguno de los dos carriles. Si un cliente necesita un retrato 4:5, ese es trabajo de otro modelo.

Paso 2: comprueba la cifra antes de gastarla

Kubeez no reembolsa una generación completada, así que las dos llamadas baratas antes de un lote caro merecen los dos segundos:

get_balance()
estimate(model="gpt-image-2-5-flare")

Aquí va una trampa real, encontrada al escribir este artículo. estimate no recibe una resolución, así que, sin nada con lo que acotar, cotiza el techo de la familia. Respondió con 28 créditos, que es la cifra de 4K. El trabajo que ejecuté de verdad, a 1K, descontó 15. Trata un estimate sin resolución como un techo, usa la tabla de arriba para lo que pagarás realmente en cada resolución y confírmalo después con el campo credits_deducted de la fila de la generación terminada.

Paso 3: genera

generate_media(
  model="gpt-image-2-5-flare",
  prompt="Fotografía editorial, plano cenital sobre una mesa de luz. Copias mates de la misma tetera de vidrio azul cobalto con collarín de latón, cada una recortada en una proporción distinta, en abanico sobre cinta negra de dibujo...",
  aspect_ratio="16:9",
  resolution="1K"
)

La respuesta es inmediata y asíncrona:

{
  "generation_id": "f90ce320-3b7e-42ce-818a-8c90760067ff",
  "status": "pending",
  "model": "gpt-image-2-5-flare",
  "estimated_cost_credits": 15,
  "billing_mode": "prepaid"
}

Para imagen a imagen mantienes la misma llamada y añades source_media_urls con entre una y dieciséis URLs públicas de imagen. No hace falta cambiar un modo a mano: enviar material de origen enruta automáticamente la petición por la vía de imagen a imagen. Si tu referencia está en el portátil y no en una URL, get_upload_url te da primero la dirección de subida.

Paso 4: consulta el estado

Aquí es donde se rompen casi todos los primeros intentos, así que conviene decirlo sin rodeos: las herramientas de consulta reciben id, no generation_id. El campo se llama generation_id al salir de generate_media y id al entrar en el consultor de estado.

get_status(id="f90ce320-3b7e-42ce-818a-8c90760067ff")

Sigue consultando hasta que status sea completed y la URL de salida sea una dirección de media.kubeez.com. En una de las cuatro imágenes de este artículo, la primera consulta con éxito devolvió una URL temporal de trabajo y la siguiente, unos segundos después, devolvió la copia duradera de la biblioteca con cdn_ready: true. Si guardas en un CMS la primera URL que ves, publicarás un enlace que caduca. Espera a la dirección de la biblioteca.

Cuando quieras la fila completa en lugar de un simple estado, get_generation(id=...) devuelve el prompt, los parámetros resueltos, processing_time_ms, credits_deducted y las salidas. Para que conste: los cuatro renders de Flare de este artículo tardaron 70, 76, 85 y 121 segundos, y descontaron 15 créditos cada uno.

El lote que sí compensa

Este es el flujo que hace que la ruta MCP merezca la configuración. No escribes cinco llamadas. Escribes una frase:

Coge este prompt y renderízalo en Flare a 1K en 16:9, 9:16, 21:9, 1:1 y 3:2. Consúltalos todos y dame las URLs de la biblioteca.

El agente lo despliega en cinco llamadas a generate_media con un solo campo cambiado:

for ratio in ["16:9", "9:16", "21:9", "1:1", "3:2"]:
    generate_media(
      model="gpt-image-2-5-flare",
      prompt=PROMPT,
      aspect_ratio=ratio,
      resolution="1K",
    )

Ese despliegue son cinco renders a 75 créditos desde una sola instrucción, y vuelves a encontrarte con una cabecera, un fotograma de story, un banner ultrapanorámico, una publicación cuadrada y un 3:2 apto para imprenta, todo desde una única decisión creativa. La infraestructura acepta las llamadas en paralelo, así que el lote termina más o menos en el tiempo del render más lento, no en la suma de los cinco.

Hay aquí un detalle que quien venga de GPT Image 2 va a agradecer. En GPT Image 2, cualquier cosa por encima de 1K exigía una relación de aspecto explícita que no fuera auto ni 1:1. En los dos carriles de GPT Image 2.5, cada relación de aspecto es válida en cada resolución, así que un cuadrado a 4K es una petición normal y no un error que sortear. Si estás valorando el salto, la comparativa 2.5 frente a 2 entra en detalle.

Deja que el agente elija el carril y la resolución

La tentación es fijar gpt-image-2-5-sunburst y 4K en un archivo de configuración y olvidarse. Resístete. Como los dos carriles cuestan lo mismo, la elección depende solo de la forma del trabajo, y ese es justo el tipo de criterio que un agente que acaba de leer get_models aplica bien:

• Bocetos, miniaturas, iterar sobre un prompt: Flare a 1K. Rápido y lo bastante barato como para ser desechable.
• Una cabecera de blog o una pieza de social: Flare a 1K o 2K. Todas las imágenes de este artículo son Flare a 1K.
• Un material que vas a editar varias veces, o creatividad de campaña que tiene que aguantar: Sunburst, con la resolución que pida el sitio donde se imprima o se coloque.
• Imprenta, gran formato, cualquier cosa que se recortará mucho después: 4K, 28 créditos, cualquiera de los dos carriles.

Dile esa regla a tu agente una vez, en un archivo de instrucciones del proyecto, y la aplicará trabajo por trabajo en lugar de pagar de más por cada miniatura.

Dónde aterrizan las imágenes

Todo lo que generas por MCP aterriza en la misma biblioteca de Kubeez que todo lo que generas en la aplicación. No hay un depósito de API aparte que reconciliar. list_assets permite al agente mirar atrás en lo que ya ha hecho, y eso importa más de lo que parece: en una sesión larga, el agente puede reutilizar una referencia que generó hace una hora en vez de pagar por regenerarla.

A partir de ahí, el material se comporta como cualquier otra salida de Kubeez. Puedes abrirlo en las herramientas de imagen, devolverlo como referencia para una pasada de imagen a imagen o pasar la URL directamente a lo que esté construyendo tu página.

Los mismos ids funcionan en la API REST

Los ids de modelo no son exclusivos de MCP. gpt-image-2-5-flare y gpt-image-2-5-sunburst son las mismas cadenas que envías a la API REST, con los mismos parámetros:

POST /v1/generate/media      -> devuelve generation_id
GET  /v1/generate/media/{id} -> consulta hasta completed
POST /v1/upload/media        -> obtienes una URL para source_media_urls

Esa es la razón práctica para prototipar por MCP. Dejas que el agente encuentre los parámetros que funcionan, lo ves trabajar en el chat y, cuando la receta está bien, mueves exactamente los mismos ids y campos a tu backend. No hay nada que traducir. La visión para desarrolladores y API tiene toda la superficie, y los modelos disponibles son la lista canónica de ids.

Cuatro cosas que no conviene hacer

1. No fijes las capacidades a fuego. Llama a get_models. Las trece relaciones de aspecto documentadas incluyen superficie realmente nueva, y una lista obsoleta escrita a mano es justo la forma de rechazar una petición que el modelo habría aceptado.
2. No envíes prompt negativo. Ninguno de los dos carriles lo admite. Pon las exclusiones dentro del propio prompt, en lenguaje llano, al final.
3. No tomes un estimate sin resolución como tu precio. Cotiza el techo. Lee después credits_deducted para saber la verdad.
4. No guardes la primera URL que veas. Consulta hasta que sea una dirección de media.kubeez.com.

Preguntas frecuentes

¿Qué carril de GPT Image 2.5 debería usar mi agente por defecto?

Flare. Es el carril rápido, tiene más calidad que GPT Image 2 y cuesta exactamente lo mismo que Sunburst. Cambia a Sunburst cuando un mismo material vaya a pasar por varias rondas de edición y quieras control estricto en toda la cadena.

¿Cuántos créditos cuesta GPT Image 2.5 en Kubeez?

15 créditos a 1K, 20 a 2K y 28 a 4K, idéntico en gpt-image-2-5-flare y en gpt-image-2-5-sunburst, tanto en texto a imagen como en imagen a imagen.

¿Puedo usar GPT Image 2.5 para editar imágenes por MCP?

Sí. Los dos carriles aceptan imagen a imagen con entre una y dieciséis imágenes de entrada. Envía source_media_urls en la llamada normal a generate_media y la petición se enruta sola. Usa antes get_upload_url si el origen es un archivo local.

¿Por qué mi consulta devuelve una URL que no está en media.kubeez.com?

Porque el render terminó antes de que la copia duradera estuviera del todo en su sitio. Consulta una vez más. La URL de la biblioteca, en media.kubeez.com, es la que hay que guardar.

¿Funciona en Claude Code y Cursor o solo en Claude?

En los tres, y en cualquier otra cosa que hable MCP. El servidor es el mismo, las herramientas son las mismas y lo único que cambia es cómo guarda su configuración cada cliente. Los ajustes de MCP tienen los datos de conexión y la visión general de MCP tiene la lista completa de herramientas.

Empieza con un solo render

Conecta el servidor, pídele a tu agente un render de Flare a 1K y mira dónde aterriza. Quince créditos, alrededor de un minuto, y sabrás con un solo trabajo si el resto de tu pipeline de imágenes pertenece a tu editor y no a una pestaña del navegador.

Si lo que quieres es el contexto del lanzamiento y no la guía práctica, GPT Image 2.5 en Kubeez cuenta lo que salió. Y si estás eligiendo entre familias, hay comparativas directas con Nano Banana 2, Midjourney v8 y Seedream 5 Pro.