API rozszerzania kadru: ze zdjęć produktowych w formaty reklamowe

Image Expander w SpicyAPI (spicyapi.ai) to najszybszy sposób, aby z kwadratowego zdjęcia produktu zrobić baner poziomy i pionowe story: wysyłasz jeden obraz i jedną proporcję, a narzędzie zwraca zdjęcie osadzone w większej ramce z nową scenerią namalowaną dookoła. Kosztuje 0,024 $ za obraz niezależnie od wybranej proporcji, nie wymaga promptu ani maski i zawsze zwraca dłuższy bok 1536 px. Problem polega na tym, że częściowo przerysowuje też samo zdjęcie, więc nadaje się do tła, a nie do dokładnych detali produktu. Opakowanie wymagające co do piksela zgodności z oryginałem trzeba złożyć ponownie, kładąc oryginał na wierzchu. Jeśli musisz kontrolować, co zostanie namalowane, wygeneruj scenę w nowej proporcji modelem do edycji obrazu opartego na prompcie; przewodnik od zdjęcia produktowego do układów reklamowych robi dokładnie to dla tych samych trzech formatów.

Przytnij, ułóż kadr albo rozszerz

• Przytnij, gdy na potrzebnych bokach zdjęcia jest już zapas scenerii. Jest to za darmo i zachowuje każdy piksel.
• Zaprojektuj kadr (jednolity kolor albo panel obok zdjęcia), gdy nagłówek potrzebuje gwarantowanej czystej powierzchni. Wygenerowana sceneria nie może tego zagwarantować.
• Rozszerz, gdy miejsce docelowe wymaga więcej obrazu, niż zarejestrowano, a jednolity kolor wyglądałby źle: niebo nad pionowym kadrem, blat i ściana obok kwadratu. Umiarkowane zmiany kształtów mieszczą się najlepiej; im bardziej nowy kształt odbiega od oryginału, tym więcej scenerii zostaje wymyślone.

Rozmiary wyniku dla siedmiu proporcji

Dłuższy bok to zawsze 1536 px, a krótszy wynika z proporcji. Zadanie to spicyapi/image-expander-v1/edit i obsługuje następujące wartości:

Dwa wnioski są ważne przy planowaniu. Po pierwsze, 4:5 i 1.91:1 nie są oferowane: użyj 3:4 i przytnij 96 px wysokości, aby uzyskać 4:5 (1152 × 1440), albo użyj 16:9 i przytnij około 60 px, aby uzyskać 1.91:1 (1536 × 804). Po drugie, źródło jest skalowane, aby się zmieścić, więc wynik 16:9 ze zdjęcia kwadratowego pokazuje produkt najwyżej 864 px wysoko, niezależnie od tego, jak duże było pierwotne zdjęcie. Jeśli miejsce docelowe wymaga większej liczby pikseli, powiększ gotowy obraz procedurą z przewodnika po skalowaniu obrazów, zamiast wychodzić ze źródła gorszej jakości.

Ile nowej scenerii wymaga każde przejście

Zdjęcie jest skalowane jednym współczynnikiem, aby zmieścić się w docelowym płótnie; wszystko inne jest malowane. Dla kwadratu 1200 × 1200 współczynnik wynosi 0.72 zarówno dla 16:9, jak i dla 9:16, co zostawia zdjęcie 864 × 864 na środku ramki i 672 px nowej scenerii (44% płótna). Zdjęcie 16:9 zamienione w 9:16 jest dużo trudniejsze: zdjęcie zmniejsza się do 864 × 486, a 68% ramki jest wymyślone.

Duże przeskoki także działają. Jeden opublikowany przykład zamienia portret z tarasu 1280 × 720 w pełnokształtną ramkę story 864 × 1536, malując resztę sukienki, płytki podłogowe i niebo:

Drugi działa w przeciwną stronę: ciasny portret 2:3 staje się nagłówkiem 1536 × 864, w którym ciemna ściana ciągnie się po obu bokach, a to dokładnie ta przestrzeń na nagłówek, której potrzebuje baner.

Co model robi z Twoim zdjęciem

Opublikowane przykłady Image Expander pokazują trzy rzeczy, które decydują o tym, jak wykorzystasz wynik:

1. Zdjęcie jest skalowane, aby się zmieścić, a nie przyklejone do krawędzi. W wyniku z tarasu leży 462 px od góry i 588 px od dołu; w wyniku z portretem 453 px od lewej i 507 px od prawej. W obu przypadkach zdjęcie leży trochę poza środkiem, więc nie licz na dokładne wycentrowanie, a przesunąć go nie można: nie ma pola kotwicy ani marginesu. Umieszczaj strefy tekstu tam, gdzie zostawiają miejsce boki, albo przesuń produkt, przycinając przeciwną stronę wyniku.
2. Samo zdjęcie jest częściowo przerysowywane. W wyniku z tarasu twarz, włosy, liście cytryny i balustrady po prawej różnią się od źródła (średnia zmiana pikseli w obrębie obszaru źródła to 30 na 255, wliczając różnice z próbkowania i kompresji). Scena czyta się jak to samo ujęcie, ale drobne szczegóły są generowane od nowa.
3. Krawędzie to słaby punkt. Niebo, tło studyjne, tynk i piasek kontynuują się najlepiej. Twarz, dłoń albo napis ucięte przez ramkę muszą zostać wymyślone.

Porównaj źródło z wynikiem przed wysyłką: duża zmiana pikseli w obszarze logo lub etykiety oznacza, że ten obszar musi pochodzić z oryginału. Praktyczna zasada: użyj wyniku jako tła i połóż ponownie prawdziwy produkt na wierzchu, gdy musi być dokładny. W przypadku torby lub butelki z etykietą wytnij produkt z oryginału procedurą usuwania tła, umieść go na rozszerzonej scenie w rozmiarze, którego wymaga układ, i narysuj ponownie cień kontaktowy. Przewodnik od zdjęcia produktowego do układów reklamowych omawia kroki układu i ochrony etykiety dla tych samych trzech formatów, więc tutaj ich nie powtarzamy.

Wybierz źródło, które dobrze się rozszerza

• Zostaw margines wokół produktu i trzymaj go z dala od krawędzi, od której będzie się rozrastał. Kompletny produkt z pustą przestrzenią obok rozszerza się bezpieczniej niż ciasne kadrowanie.
• Preferuj proste otoczenie: papier bez spoiny, tynkowa ściana, niebo, blat z jedną wyraźną linią horyzontu. Powtarzające się wzory, takie jak kafelki czy paski, mogą rozjechać się fazowo przy połączeniu.
• Wybierz najbliższą proporcję. Jeśli sklep internetowy chce 5:4, wyjdź z 1:1 albo 4:3, a nie ze źródła 9:16.

Najpierw sprawdź to w Playground

1. Otwórz stronę zadania Image Expander i zostań w karcie Playground w widoku Form. Zaloguj się kontem z saldem, aby uruchomić.
2. W polu Input image upuść zdjęcie albo wklej bezpośredni link przez Asset URL (JPG, PNG lub WebP, do 10 MB).
3. Wybierz proporcję w polu Aspect ratio (nie Auto, którego API nie przyjmuje) odpowiednią do miejsca docelowego, na przykład 16:9 dla nagłówka albo 9:16 dla story. Output format domyślnie to PNG; wybierz JPEG lub WebP, jeśli pliki mają być mniejsze.
4. Sprawdź szacunkową cenę, a potem uruchom. Najpierw wypróbuj potrzebne proporcje na najtrudniejszym źródle: złe połączenie tutaj będzie złe także przez API.

Treść żądania pokazana pod formularzem to ten sam JSON, który przyjmuje API, więc konfiguracja działająca tutaj przenosi się wprost do kodu.

Potem wywołaj to z kodu

Zainstaluj Python SDK (pip install spicyapi), ustaw SPICY_API_KEY w swoim środowisku i wykonaj po jednym wywołaniu dla każdego źródła i proporcji:

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

Wgrywanie, oczekiwanie, błędy i ponowienia opisuje referencja Python SDK oraz przewodnik po zadaniach asynchronicznych. Dla każdego dodatkowego formatu zmień aspect_ratio i klucz idempotencji; rozliczane jest tylko zakończone powodzeniem zadanie.

Albo niech wykona to Agent

Jeśli asystent ma przygotować formaty za Ciebie, daj mu CLI albo serwer MCP. Oba pokazują cenę i proszą o potwierdzenie przed płatnym wywołaniem. Skill dodaje instrukcje do obu.

• CLI. spicyapi wykonuje jedno zadanie z terminala lub skryptu (npx @spicyapi/cli działa bez instalacji):

``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 ``

W input.json znajduje się ten sam obiekt input co wyżej, z identyfikatorem spicy://.

• Serwer MCP. Dodaj serwer MCP do swojego asystenta, a potem zapytaj: "Expand ./product-square.png to 9:16 and 16:9 with Image Expander." Wywołuje spicyapi_upload_file, następnie spicyapi_task_create (który zatrzymuje się na potwierdzenie ceny), a następnie 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 instaluje Agent Skill, dzięki któremu asystent programistyczny czyta bieżący schemat zamiast zgadywać pola, a klucze idempotencji wykorzystuje ponownie. Sam nie uruchomi zadań, więc używaj go razem z CLI lub MCP.

Oceń każdy wynik w trzech przejściach

1. Produkt: ta sama liczba sztuk, sylwetka, kolor, etykieta oraz uchwyt albo nakrętka. Zmienione logo albo drugi kubek w nowym miejscu to odrzucenie, a nie wybór stylu.
2. Połączenie: prześledź krawędź blatu, wzór ściany, horyzont i kierunek światła przez dawną granicę. Szew za produktem ma znaczenie; szew w rogu, który i tak przytniesz, nie.
3. Układ: nałóż ramkę nagłówka i obszary nakładki platformy. Pionowe story może ukryć produkt pod elementami sterującymi interfejsu, więc sprawdź aktualne wskazówki dotyczące bezpiecznego obszaru dla tego umiejscowienia.

Jeśli problem leży poza Twoim kadrem, przytnij go. Jeśli przecina produkt albo strefę tekstu, zmień źródło (szerszy oryginał, mniej ciasne kadrowanie, bardziej jednolite tło) albo wróć do zaprojektowanego płótna. Nowa generacja z tym samym źródłem to nowe losowanie, a nie naprawa, więc najpierw coś zmień.

Koszt zestawu trzech formatów

Każdy ukończony wynik kosztuje 0,024 $, więc 16:9 i 9:16 z jednego źródła to 2 x 0,024 $ = 0,048 $, a trzy wyniki (na przykład 1:1, 16:9 i 9:16 ze źródła 4:3) to 0,072 $. Partia 20 źródeł w dwóch proporcjach to 40 wywołań, czyli 0,96 $; jeśli 5 źródeł wymaga jeszcze jednej próby z lepszym źródłem, 45 wywołań, czyli 1,08 $. Nie obejmuje to wycinania, skalowania w górę ani czasu pracy nad projektem. Zakończone żądanie jest rozliczane niezależnie od tego, jak wygląda wynik, więc popraw źródło przed ponownym uruchomieniem, zamiast po prostu losować jeszcze raz.

Częste pytania

A co jeśli moje zdjęcie jest większe niż 1536 px? Wróci z 1536 px na dłuższym boku, więc może być mniejsze od oryginału. Jeśli miejsce docelowe wymaga większej liczby pikseli, przeskaluj je później.

Czy mogę użyć tego do zrobienia pierwszej klatki 9:16 dla wideo? Tak, jeśli osoba i poza są już w pełni ujęte; zobacz przewodnik o zamianie poziomego portretu na pionowe wideo AI. Strona modelu podaje bieżący schemat i cenę.