API d'extension de cadre : transformer des photos produit en formats publicitaires

Image Expander sur SpicyAPI (spicyapi.ai) est le moyen rapide de tirer d'une photo carrée de produit une bannière paysage et une story verticale : vous envoyez une image et un rapport d'aspect, et il renvoie la photo placée dans un cadre plus grand, avec une nouvelle scène peinte autour. Cela coûte $0.024 par image quel que soit le ratio, ne demande ni prompt ni masque, et renvoie toujours un côté long de 1536 px. La contrepartie : il redessine aussi une partie de votre photo, ce qui convient aux arrière-plans, pas au détail exact du produit. Un emballage au pixel près exige de replacer l'original par-dessus. Si vous devez contrôler ce qui est peint, générez plutôt la scène au nouveau ratio avec un modèle d'édition d'image basé sur un prompt ; le guide photo produit vers maquettes publicitaires fait cela pour les trois mêmes formats.

Rogner, composer ou étendre

• Rognez quand la photo dispose déjà d'une marge de scène sur les côtés dont vous avez besoin. C'est gratuit et chaque pixel est conservé.
• Composez la toile (aplats ou panneau à côté de la photo) quand le titre a besoin d'une zone propre garantie. Une scène générée ne peut pas le promettre.
• Étendez quand la destination demande plus d'image que vous n'en avez prise et qu'un aplat ferait mauvais effet : ciel au-dessus d'un format vertical, plan de travail et mur à côté d'un carré. Les changements de forme modérés se fondent le mieux ; plus la nouvelle forme s'éloigne de l'original, plus de scène est inventée.

Tailles de sortie pour les sept ratios

Le côté long fait toujours 1536 px et le côté court suit le ratio. La tâche est spicyapi/image-expander-v1/edit, et elle accepte ces valeurs :

Deux conséquences comptent pour la planification. D'abord, 4:5 et 1.91:1 ne sont pas proposés : utilisez 3:4 et rognez 96 px de hauteur pour atteindre 4:5 (1152 × 1440), ou utilisez 16:9 et rognez environ 60 px pour 1.91:1 (1536 × 804). Ensuite, la source est mise à l'échelle pour tenir dans le cadre, donc un résultat 16:9 issu d'une photo carrée montre votre produit sur 864 px de haut au plus, quelle que soit la taille de l'original. Si la destination demande plus de pixels, agrandissez l'image finie avec le flux du guide d'agrandissement d'image plutôt que de partir d'une source de qualité inférieure.

Combien de scène nouvelle chaque saut demande

La photo est mise à l'échelle par un seul facteur afin de tenir dans la toile cible ; tout le reste est peint. Pour un carré de 1200 × 1200, ce facteur vaut 0.72 pour 16:9 comme pour 9:16, ce qui laisse une photo de 864 × 864 au centre du cadre et 672 px de scène nouvelle (44 % de la toile). Une photo 16:9 convertie en 9:16 est bien plus difficile : la photo rétrécit à 864 × 486 et 68 % du cadre est inventé.

Les grands sauts fonctionnent aussi. Un exemple publié transforme un portrait de terrasse en 1280 × 720 en cadre de story en pied de 864 × 1536, le reste de la robe, les dalles du sol et le ciel étant peints :

L'autre va dans le sens inverse : un portrait 2:3 serré devient un en-tête de 1536 × 864 où le mur sombre se prolonge des deux côtés, ce qui est exactement l'espace de titre dont une bannière a besoin.

Ce que le modèle fait à votre photo

Les exemples publiés d'Image Expander montrent trois choses qui décident de l'usage de la sortie :

1. La photo est mise à l'échelle pour tenir, pas ancrée à un bord. Sur le résultat de la terrasse, elle se trouve à 462 px du bord supérieur et 588 px du bord inférieur ; sur le résultat de portrait, à 453 px du bord gauche et 507 px du bord droit. Dans les deux cas la photo est légèrement hors centre, donc ne comptez pas sur un centrage exact, et vous ne pouvez pas la déplacer : il n'y a ni champ d'ancrage ni marge. Placez les zones de texte là où les côtés laissent de la place, ou décalez le produit en rognant le côté opposé du résultat.
2. La photo elle-même est partiellement redessinée. Sur le résultat de la terrasse, le visage, les cheveux, les feuilles de citronnier et les balustres à droite diffèrent de la source (la variation moyenne de pixel dans la zone source est de 30 sur 255, en incluant les différences de rééchantillonnage et de compression). La scène se lit comme la même prise, mais les détails fins sont régénérés.
3. Les bords sont le point faible. Ciel, papier de studio, plâtre et sable se prolongent le mieux. Un visage, une main ou une lettre coupés par la bordure doivent être inventés.

Comparez votre source avec le résultat avant la livraison : une forte variation de pixel sur une zone de logo ou d'étiquette signifie que cette zone doit venir de l'original. La règle pratique : utilisez le résultat comme arrière-plan et reposez le vrai produit par-dessus quand il doit être exact. Pour un sac ou une bouteille avec étiquette, détachez le produit de l'original avec le flux de suppression d'arrière-plan, placez-le sur la scène étendue à la taille dont la maquette a besoin, et redessinez l'ombre de contact. Le guide photo produit vers maquettes publicitaires couvre les étapes de maquette et de protection d'étiquette pour les trois mêmes formats ; elles ne sont donc pas répétées ici.

Choisissez une source qui s'étend bien

• Laissez une marge autour du produit et gardez-la dégagée de la bordure depuis laquelle il grandira. Un produit complet avec de l'espace vide à côté s'étend plus sûrement qu'un cadrage serré.
• Préférez des environnements simples : papier sans raccord, mur en plâtre, ciel, un plan de travail avec une seule ligne d'horizon nette. Les motifs répétitifs comme les carreaux ou les rayures peuvent se décaler de phase à la jointure.
• Prenez le ratio le plus proche. Si une marketplace veut 5:4, partez de 1:1 ou de 4:3 plutôt que d'une source 9:16.

Essayez d'abord dans le Playground

1. Ouvrez la page de tâche Image Expander et restez dans l'onglet Playground, en vue Form. Connectez-vous avec un compte approvisionné pour lancer l'exécution.
2. Sous Input image, déposez votre photo, ou utilisez Asset URL pour un lien direct (JPG, PNG ou WebP, jusqu'à 10 Mo).
3. Choisissez un ratio dans Aspect ratio (pas Auto, que l'API n'accepte pas) selon la destination, par exemple 16:9 pour un en-tête ou 9:16 pour une story. Output format est PNG par défaut ; choisissez JPEG ou WebP pour des fichiers plus légers.
4. Vérifiez l'estimation de prix, puis lancez. Testez d'abord les ratios dont vous avez besoin sur votre source la plus difficile : une mauvaise jointure ici sera mauvaise via l'API.

Le corps de requête affiché sous le formulaire est le même JSON que l'API accepte, donc une configuration qui fonctionne ici se copie telle quelle dans le code.

Appelez-le ensuite depuis le code

Installez le SDK Python (pip install spicyapi), définissez SPICY_API_KEY dans l'environnement et exécutez un appel par source et par ratio :

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

Les téléversements, l'attente, les erreurs et les nouvelles tentatives figurent dans la référence du SDK Python et le guide des tâches asynchrones. Changez aspect_ratio et la clé d'idempotence pour chaque format supplémentaire ; seule une tâche réussie est facturée.

Ou laissez un agent l'exécuter

Si un assistant doit produire les formats à votre place, donnez-lui la CLI ou le serveur MCP. Les deux affichent le prix et vous demandent une confirmation avant un appel payant. La Skill ajoute des instructions par-dessus l'un ou l'autre.

• CLI. spicyapi exécute une tâche depuis un terminal ou un script (npx @spicyapi/cli fonctionne sans installation) :

``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 contient le même objet input que ci-dessus, avec l'URI spicy://.

• Serveur MCP. Ajoutez le serveur MCP à votre assistant, puis demandez : "Expand ./product-square.png to 9:16 and 16:9 with Image Expander." Il appelle spicyapi_upload_file, puis spicyapi_task_create (qui s'arrête pour votre confirmation de prix), puis 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 installe l'Agent Skill, qui apprend à un assistant de code à lire le schéma actuel et à réutiliser les clés d'idempotence au lieu de deviner. Il ne peut pas exécuter de tâches à lui seul, utilisez-le donc avec la CLI ou MCP.

Vérifiez chaque résultat en trois passes

1. Produit : même nombre d'objets, silhouette, couleur, étiquette et anse ou bouchon. Un logo modifié ou une deuxième tasse dans la nouvelle zone impose un rejet, ce n'est pas un choix de style.
2. Jointure : suivez le bord du plan de travail, le motif du mur, l'horizon et le sens de la lumière à travers l'ancienne bordure. Une couture derrière le produit compte ; dans un coin que vous allez rogner, non.
3. Maquette : superposez le cadre de titre et les zones de recouvrement de la plateforme. Une story verticale peut masquer le produit sous les contrôles de l'interface : vérifiez les recommandations actuelles de zone sûre pour ce placement.

Si le problème est en dehors de votre recadrage, rognez-le. S'il traverse le produit ou la zone de texte, changez de source (original plus large, cadrage moins serré, fond plus neutre) ou revenez à une toile composée. Une nouvelle génération avec la même source est un nouveau tirage, pas une réparation : changez donc d'abord quelque chose.

Coût d'un lot de trois formats

Chaque sortie terminée coûte $0.024, donc un 16:9 et un 9:16 issus d'une même source font 2 × $0.024 = $0.048, et trois sorties (par exemple 1:1, 16:9 et 9:16 depuis une source 4:3) font $0.072. Un lot de 20 sources à deux ratios représente 40 appels, soit $0.96 ; si 5 sources ont besoin d'un essai supplémentaire avec une meilleure source, 45 appels, soit $1.08. Cela exclut les découpes, l'agrandissement et le temps de design. Une requête terminée est facturée quel que soit l'aspect du résultat : corrigez donc la source avant de relancer plutôt que de tirer au hasard.

FAQ

Et si ma photo dépasse 1536 px ? Elle revient à 1536 sur le côté long : le résultat peut donc être plus petit que l'original. Agrandissez ensuite si la destination demande plus de pixels.

Puis-je m'en servir pour faire une première image 9:16 pour vidéo ? Oui, si la personne et la pose sont déjà complètes ; voir le guide pour transformer un portrait paysage en vidéo verticale par IA. La page du modèle indique le schéma et le prix actuels.