API de expansión del lienzo: convierte fotos de producto en formatos publicitarios

Image Expander en SpicyAPI (spicyapi.ai) es la forma rápida de sacar de una foto cuadrada de producto un banner horizontal y una historia vertical: envías una imagen y una relación de aspecto, y devuelve la foto colocada dentro de un marco mayor con nueva escena pintada alrededor. Cuesta $0.024 por imagen sea cual sea la proporción, no admite prompt ni máscara, y siempre devuelve un lado largo de 1536 px. La contrapartida es que también redibuja parte de tu foto, así que sirve para fondos, no para el detalle exacto del producto. Un envase con píxeles exactos necesita el original superpuesto encima. Si necesitas controlar qué se pinta, genera en su lugar la escena en la nueva proporción con un modelo de edición de imagen basado en prompt; la guía de fotos de producto a diseños publicitarios lo hace para los mismos tres formatos.

Recortar, maquetar o expandir

• Recorta cuando la foto ya tiene escena de sobra en los lados que necesitas. Es gratis y conserva cada píxel.
• Diseña el lienzo (color plano o panel junto a la foto) cuando el titular necesita una zona limpia garantizada. La escena generada no puede prometer eso.
• Expande cuando el destino necesita más imagen de la que fotografiaste y un color plano quedaría mal: cielo sobre un vertical, encimera y pared junto a un cuadrado. Los cambios de forma moderados se mezclan mejor; cuanto más se aleje la forma nueva del original, más escena se inventa.

Tamaños de salida para las siete proporciones

El lado largo es siempre 1536 px y el lado corto sigue la proporción. La tarea es spicyapi/image-expander-v1/edit y admite estos valores:

Dos consecuencias importan al planificar. Primera, 4:5 y 1.91:1 no se ofrecen: usa 3:4 y recorta 96 px de alto para llegar a 4:5 (1152 × 1440), o usa 16:9 y recorta unos 60 px para 1.91:1 (1536 × 804). Segunda, la fuente se escala para encajar, así que un resultado 16:9 a partir de una foto cuadrada muestra tu producto como mucho con 864 px de alto, por grande que fuera el original. Si el destino necesita más píxeles, amplía la imagen final con el flujo de la guía de ampliación de imágenes en lugar de partir de una fuente de menor calidad.

Cuánta escena nueva pide cada salto

La foto se escala con un único factor para que quepa dentro del lienzo destino; todo lo demás se pinta. Para un cuadrado de 1200 × 1200, el factor es 0.72 tanto para 16:9 como para 9:16, lo que deja una foto de 864 × 864 en el centro del marco y 672 px de escena nueva (44 % del lienzo). Pasar una foto 16:9 a 9:16 es mucho más difícil: la foto se reduce a 864 × 486 y el 68 % del marco es inventado.

Los saltos grandes también funcionan. Un ejemplo publicado convierte un retrato de terraza de 1280 × 720 en un marco de historia de cuerpo entero de 864 × 1536, pintando el resto del vestido, las baldosas del suelo y el cielo:

El otro va en sentido contrario: un retrato 2:3 cerrado se convierte en una cabecera de 1536 × 864 con la pared oscura continuando a ambos lados, que es exactamente el espacio de titular que necesita un banner.

Qué le hace el modelo a tu foto

Los ejemplos publicados de Image Expander muestran tres cosas que deciden cómo usas la salida:

1. La foto se escala para encajar, no se ancla a un borde. En el resultado de la terraza está a 462 px del borde superior y 588 px del inferior; en el resultado de retrato, a 453 px del lado izquierdo y 507 px del derecho. En ambos casos la foto quedó ligeramente descentrada, así que no cuentes con un centrado exacto, y además no puedes moverla: no hay campo de ancla ni de relleno. Coloca las zonas de texto donde dejen las partes libres, o desplaza el producto recortando el lado contrario del resultado.
2. La propia foto se redibuja en parte. En el resultado de la terraza, la cara, el pelo, las hojas de limón y las balaustradas de la derecha difieren de la fuente (el cambio medio de píxel dentro del área de origen es 30 sobre 255, incluyendo diferencias de remuestreo y compresión). La escena se lee como la misma toma, pero los detalles finos se regeneran.
3. Los bordes son el punto débil. El cielo, el papel de estudio, el yeso y la arena son los que mejor continúan. Una cara, una mano o una letra cortada por el borde hay que inventarlas.

Compara tu fuente con el resultado antes de publicar: un cambio de píxel grande en una zona de logotipo o etiqueta significa que esa zona debe venir del original. La regla práctica: usa el resultado como fondo y vuelve a colocar encima el producto real cuando deba ser exacto. Para una bolsa o botella con etiqueta, recorta el producto del original con el flujo de eliminación de fondo, colócalo sobre la escena ampliada al tamaño que necesite el diseño y vuelve a dibujar la sombra de contacto. La guía de fotos de producto a diseños publicitarios cubre los pasos de diseño y protección de etiqueta para los mismos tres formatos, así que no se repiten aquí.

Elige una fuente que se amplíe bien

• Deja margen alrededor del producto y mantenlo despejado del borde desde el que crecerá. Un producto completo con espacio vacío al lado se amplía de forma más segura que un recorte cerrado.
• Prefiere entornos sencillos: papel sin costura, pared de yeso, cielo, una encimera con una única línea de horizonte clara. Los patrones repetidos como baldosas o rayas pueden desfasarse en la unión.
• Elige la proporción más cercana. Si un marketplace quiere 5:4, parte de 1:1 o de 4:3 en lugar de desde una fuente 9:16.

Pruébalo primero en el Playground

1. Abre la página de la tarea Image Expander y quédate en la pestaña Playground, en la vista Form. Inicia sesión con una cuenta con saldo para ejecutar.
2. En Input image, deja tu foto, o usa Asset URL para un enlace directo (JPG, PNG o WebP, hasta 10 MB).
3. Elige una proporción en Aspect ratio (no Auto, que la API no admite) para el destino, por ejemplo 16:9 para una cabecera o 9:16 para una historia. Output format es PNG por defecto; elige JPEG o WebP para archivos más pequeños.
4. Comprueba la estimación de precio y ejecuta. Prueba primero las proporciones que necesitas con tu fuente más difícil: una unión mala aquí será mala desde la API.

El cuerpo de la solicitud que se muestra bajo el formulario es el mismo JSON que acepta la API, así que una configuración que funciona aquí se copia tal cual al código.

Luego llámalo desde el código

Instala el SDK de Python (pip install spicyapi), define SPICY_API_KEY en el entorno y ejecuta una llamada por fuente y proporción:

import uuid

from spicyapi import SpicyClient, output_assets

client = SpicyClient()  # reads SPICY_API_KEY from the environment

photo = client.upload_file("./product-square.png")  # local files become spicy:// URIs

task = client.create_task(
    model="spicyapi/image-expander-v1/edit",
    input_data={"image_url": photo["uri"], "aspect_ratio": "9:16", "output_format": "png"},
    idempotency_key=str(uuid.uuid4()),  # new key per new request; reuse only to retry the same one
)

final = client.wait_for_terminal(task["taskId"])
if final["state"] != "succeeded":
    raise RuntimeError(f"Task {task['taskId']} ended as {final['state']}")

print(output_assets(final)[0]["url"])  # copy it to your own storage now

Las subidas, la espera, los errores y los reintentos están en la referencia del SDK de Python y en la guía de tareas asíncronas. Cambia aspect_ratio y la clave de idempotencia para cada formato adicional; solo se cobra una tarea completada con éxito.

O deja que un agente lo ejecute

Si un asistente debe producir los formatos por ti, dale la CLI o el servidor MCP. Ambos muestran el precio y te piden confirmación antes de una llamada de pago. La Skill añade instrucciones por encima de cualquiera de los dos.

• CLI. spicyapi ejecuta una tarea desde una terminal o un script (npx @spicyapi/cli funciona sin instalar):

``bash spicyapi files upload ./product-square.png # prints a spicy:// URI spicyapi tasks create --model spicyapi/image-expander-v1/edit \ --input-file input.json --idempotency-key product-square-9x16-v1 --wait ``

input.json contiene el mismo objeto input que arriba, con la URI spicy://.

• Servidor MCP. Añade el servidor MCP a tu asistente y luego pregunta: "Expand ./product-square.png to 9:16 and 16:9 with Image Expander." Llama a spicyapi_upload_file, después a spicyapi_task_create (que se detiene para tu confirmación de precio) y después a spicyapi_task_wait.

``json { "mcpServers": { "spicyapi": { "command": "npx", "args": ["--yes", "--package=@spicyapi/mcp", "spicyapi-mcp"], "env": { "SPICY_API_KEY": "YOUR_SPICY_API_KEY" } } } } ``

• Skill. npx skills add spicyapi-ai/spicy-skill instala el Agent Skill, que enseña a un asistente de programación a leer el esquema actual y reutilizar claves de idempotencia en lugar de adivinar. No puede ejecutar tareas por sí mismo, así que úsalo junto con la CLI o MCP.

Revisa cada resultado en tres pasadas

1. Producto: mismo número de piezas, silueta, color, etiqueta y asa o tapa. Un logotipo cambiado o una segunda taza en la zona nueva es un rechazo, no una decisión de estilo.
2. Unión: sigue el borde de la encimera, el patrón de la pared, el horizonte y la dirección de la luz a través del borde antiguo. Una costura detrás del producto importa; una en una esquina que vas a recortar, no.
3. Diseño: superpón la caja del titular y las zonas de superposición de la plataforma. Una historia vertical puede ocultar el producto bajo los controles de la interfaz, así que consulta la guía actual de zona segura de esa colocación.

Si el problema queda fuera de tu recorte, recórtalo. Si cruza el producto o la zona de texto, cambia la fuente (original más amplio, encuadre menos cerrado, fondo más liso) o vuelve a un lienzo diseñado. Una nueva generación con la misma fuente es un sorteo nuevo, no una reparación, así que cambia algo primero.

Coste de un conjunto de tres formatos

Cada salida completada cuesta $0.024, así que un 16:9 y un 9:16 desde una misma fuente son 2 × $0.024 = $0.048, y tres salidas (por ejemplo 1:1, 16:9 y 9:16 desde una fuente 4:3) son $0.072. Un lote de 20 fuentes a dos proporciones son 40 llamadas, o $0.96; si 5 fuentes necesitan un intento más con una fuente mejor, 45 llamadas, o $1.08. Esto excluye los recortes, la ampliación y el tiempo de diseño. Una solicitud completada se factura sea cual sea el aspecto del resultado, así que corrige la fuente antes de volver a ejecutar en lugar de repetir a ciegas.

Preguntas frecuentes

¿Qué pasa si mi foto mide más de 1536 px? Vuelve con 1536 en el lado largo, así que puede quedar más pequeña que el original. Amplía después si el destino necesita más píxeles.

¿Puedo usarla para hacer un primer fotograma 9:16 de vídeo? Sí, si la persona y la pose ya están completas; consulta la guía para convertir un retrato horizontal en vídeo vertical con IA. La página del modelo tiene el esquema y el precio actuales.