이미지 아웃페인팅 API: 상품 사진을 광고 포맷으로

SpicyAPI(spicyapi.ai)의 Image Expander는 정사각형 상품 사진에서 가로 배너와 세로 스토리를 빠르게 만드는 방법입니다. 이미지 하나와 화면 비율 하나를 보내면, 사진이 더 큰 프레임 안에 들어간 채 주변에 새로운 장면이 그려져 돌아옵니다. 어떤 비율을 고르든 이미지당 $0.024이며, prompt도 mask도 필요 없고, 출력의 긴 변은 항상 1536 px입니다. 대신 사진의 일부도 다시 그려지므로 배경에는 적합하지만 제품의 세부를 정확히 보존하지는 못합니다. 픽셀 단위로 정확한 패키지가 필요하면 원본을 위에 다시 합성해야 합니다. 무엇이 그려질지 직접 제어하려면 새 화면 비율의 장면을 prompt 기반 이미지 편집 모델로 생성하세요. 같은 세 가지 포맷을 다루는 상품 사진에서 광고 레이아웃으로 가이드가 그 방법을 설명합니다.

자르기, 레이아웃 설계, 확장 중 고르기

• 자르세요. 필요한 방향에 이미 여유 있는 장면이 있을 때입니다. 무료이며 모든 픽셀이 그대로 남습니다.
• 캔버스를 설계하세요. 단색이나 사진 옆의 패널로, 헤드라인에 확실한 빈 영역이 필요할 때입니다. 생성된 장면은 이를 보장할 수 없습니다.
• 확장하세요. 목적지 배치가 촬영한 것보다 더 많은 그림을 요구하고 단색으로는 어색할 때입니다. 세로 구도의 위쪽 하늘, 정사각형 옆의 조리대와 벽 같은 경우입니다. 형태 변화가 적을수록 자연스럽게 어울리고, 원본에서 멀어질수록 더 많은 장면이 만들어집니다.

일곱 가지 비율의 출력 크기

긴 변은 항상 1536 px이며 짧은 변은 비율을 따릅니다. 작업은 spicyapi/image-expander-v1/edit이며 다음 값을 지원합니다.

계획에 중요한 결과가 두 가지 있습니다. 첫째, 4:5와 1.91:1은 제공되지 않습니다. 3:4를 사용해 높이에서 96 px를 잘라 4:5(1152 × 1440)를 만들거나, 16:9를 사용해 약 60 px를 잘라 1.91:1(1536 × 804)을 만드세요. 둘째, 원본은 프레임에 맞춰 축소되므로, 정사각형 사진에서 나온 16:9 결과의 제품은 원본이 아무리 커도 높이가 최대 864 px입니다. 목적지에 더 많은 픽셀이 필요하면 화질이 낮은 원본에서 시작하지 말고 이미지 업스케일링 가이드의 작업 흐름으로 완성된 이미지를 확대하세요.

각 전환이 요구하는 새로운 장면의 양

사진은 목표 캔버스에 들어가도록 하나의 배율로 축소되고, 나머지는 전부 그려집니다. 1200 × 1200 정사각형이라면 16:9와 9:16 모두 배율이 0.72이며, 프레임 중앙에 864 × 864 사진이 남고 672 px의 새로운 장면이 생깁니다(캔버스의 44%). 16:9 사진을 9:16으로 바꾸는 것은 훨씬 어렵습니다. 사진이 864 × 486로 줄어들고 프레임의 68%는 만들어진 부분입니다.

큰 전환도 가능합니다. 공개된 예 하나로 1280 × 720 테라스 인물이 864 × 1536 전신 스토리 프레임으로 바뀌며, 남은 드레스, 바닥 타일, 하늘이 그려져 들어갑니다.

다른 하나는 반대 방향입니다. 좀 더 타이트한 2:3 인물이 1536 × 864 헤더가 되고 어두운 벽이 양쪽으로 이어집니다. 이는 배너에 필요한 헤드라인 공간 그 자체입니다.

모델이 사진에 무엇을 하는지

Image Expander의 공개 예시는 결과를 어떻게 쓰느냐를 결정하는 세 가지를 보여 줍니다.

1. 사진은 프레임에 맞춰 축소될 뿐, 가장자리에 고정되지 않습니다. 테라스 결과에서는 위쪽에서 462 px, 아래쪽에서 588 px 지점에 있고, 인물 결과에서는 왼쪽에서 453 px, 오른쪽에서 507 px 지점에 있습니다. 두 경우 모두 사진이 약간 중심에서 벗어나므로 정확한 중앙 배치를 기대하지 마세요. 사진을 직접 옮길 수도 없습니다. 앵커 필드도 패딩 필드도 없습니다. 텍스트 영역은 좌우로 남는 공간에 배치하거나, 결과의 반대쪽을 잘라 제품을 옮기세요.
2. 사진 자체도 일부 다시 그려집니다. 테라스 결과에서 얼굴, 머리카락, 레몬잎, 오른쪽 난간은 원본과 다릅니다(원본 영역 안의 평균 픽셀 변화는 리샘플링과 압축 차이를 포함해 255 중 30입니다). 장면은 같은 촬영으로 읽히지만 세밀한 디테일은 다시 생성됩니다.
3. 가장자리가 취약한 부분입니다. 하늘, 스튜디오 배경, 석고 벽, 모래가 가장 자연스럽게 이어집니다. 경계에 잘린 얼굴, 손, 글자는 만들어내야 합니다.

배포하기 전에 원본과 결과를 비교하세요. 로고나 라벨 영역에서 픽셀 변화가 크다면 그 영역은 원본에서 가져와야 합니다. 실무 규칙은 결과를 배경으로 쓰고, 정확해야 하는 자리에는 진짜 제품을 다시 올리는 것입니다. 라벨이 있는 봉투나 병에는 배경 제거 작업 흐름으로 원본에서 제품을 잘라내고, 레이아웃에 필요한 크기로 확장된 장면 위에 놓고, 접촉 그림자를 다시 그리세요. 같은 세 가지 포맷의 레이아웃과 라벨 보호 단계는 상품 사진에서 광고 레이아웃으로 가이드가 다루므로 여기서는 반복하지 않습니다.

잘 확장되는 원본 고르기

• 제품 둘레에 여백을 남기고, 그것이 커질 경계에서 떨어져 있게 하세요. 옆에 빈 공간이 있는 완성된 제품은 타이트하게 자른 것보다 안전하게 확장됩니다.
• 단순한 배경을 선호하세요: 이음매 없는 종이, 석고 벽, 하늘, 지평선이 하나로 또렷한 조리대. 타일이나 줄무늬 같은 반복 패턴은 이음부에서 위상이 어긋날 수 있습니다.
• 가장 가까운 비율을 고르세요. 마켓플레이스가 5:4를 원한다면 9:16 원본이 아니라 1:1이나 4:3에서 출발하세요.

먼저 Playground에서 해보기

1. Image Expander 작업 페이지를 열고 Playground 탭의 Form 보기에서 그대로 진행하세요. 실행하려면 잔액이 있는 계정으로 로그인합니다.
2. Input image에 사진을 놓거나, Asset URL로 직접 링크를 넣습니다(JPG, PNG 또는 WebP, 최대 10 MB).
3. Aspect ratio에서 목적지에 맞는 비율을 고르세요(API가 받지 않는 Auto는 안 됩니다). 헤더라면 16:9, 스토리라면 9:16 같은 식입니다. Output format은 기본이 PNG이며, 파일을 줄이려면 JPEG나 WebP를 고르세요.
4. 가격 예상치를 확인한 뒤 실행하세요. 필요한 비율을 먼저 가장 어려운 원본에 적용해 보세요. 여기서 이어 붙이기가 나쁘면 API로 불러도 나쁩니다.

폼 아래에 표시되는 요청 본문은 API가 받는 것과 같은 JSON이라, 여기서 동작한 설정을 그대로 코드로 옮길 수 있습니다.

그다음 코드에서 호출하기

Python SDK(pip install spicyapi)를 설치하고 환경에 SPICY_API_KEY를 설정한 뒤, 원본과 비율마다 한 번씩 호출하세요:

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

업로드, 대기, 오류, 재시도는 Python SDK 레퍼런스와 비동기 작업 가이드에 정리되어 있습니다. 포맷을 하나 추가할 때마다 aspect_ratio와 idempotency key를 바꾸세요. 과금은 성공한 작업에만 됩니다.

또는 Agent에게 맡기기

어시스턴트가 대신 포맷을 만들게 하려면 CLI나 MCP 서버를 넘기세요. 둘 다 가격을 보여 주고 유료 호출 전에 확인을 요청합니다. Skill은 그 위에 지시를 더합니다.

• CLI. spicyapi는 터미널이나 스크립트에서 작업 하나를 실행합니다(npx @spicyapi/cli는 설치 없이도 동작합니다).

``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에는 위와 같은 input 객체를 spicy:// URI와 함께 넣습니다.

• MCP 서버. 어시스턴트에 MCP 서버를 추가한 뒤 이렇게 물어보세요. "Expand ./product-square.png to 9:16 and 16:9 with Image Expander." spicyapi_upload_file을 호출하고, 이어서 가격 확인을 위해 spicyapi_task_create에서 멈춘 다음, 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은 Agent Skill을 설치합니다. 이 스킬은 코딩 어시스턴트가 추측하지 않고 최신 스키마를 읽고 idempotency key를 재사용하도록 알려 줍니다. 스스로는 작업을 실행하지 못하므로 CLI나 MCP와 함께 쓰세요.

결과를 세 번에 나눠 검토하기

1. 제품: 품목 수, 실루엣, 색, 라벨, 손잡이나 뚜껑이 같은지 확인합니다. 로고가 바뀌었거나 새 영역에 머그가 하나 더 있으면 스타일 선택이 아니라 탈락입니다.
2. 이음부: 조리대 모서리, 벽 무늬, 지평선, 빛의 방향을 옛 경계 너머로 따라가 봅니다. 제품 뒤의 이음은 문제가 되지만, 잘라 버릴 모서리의 이음은 그렇지 않습니다.
3. 레이아웃: 헤드라인 상자와 플랫폼의 오버레이 영역을 위에 올려 봅니다. 세로 스토리는 인터페이스 조작 요소 아래에 제품을 가릴 수 있으므로, 그 배치의 최신 안전 영역 지침을 확인하세요.

문제가 자른 범위 밖에 있다면 그곳을 잘라 버리세요. 제품이나 텍스트 영역을 가로지른다면 원본을 바꾸세요(더 넓은 원본, 덜 타이트한 프레이밍, 더 단정한 배경). 아니면 디자인한 캔버스로 돌아가세요. 같은 원본으로 다시 생성하는 것은 수선이 아니라 새로 뽑는 것이므로, 먼저 무언가를 바꾸세요.

세 가지 포맷 한 묶음의 비용

완료된 출력 하나는 $0.024이므로, 한 원본에서 16:9와 9:16을 만들면 2 x $0.024 = $0.048이고, 출력 세 개(예: 4:3 원본에서 1:1, 16:9, 9:16)는 $0.072입니다. 원본 20개를 두 비율로 처리하면 40회 호출로 $0.96이고, 5개의 원본에 더 나은 원본으로 한 번 더 시도가 필요하면 45회 호출로 $1.08입니다. 컷아웃, 업스케일링, 디자인 시간은 제외됩니다. 완료된 요청은 결과가 어떤 모습이든 과금되므로, 다시 돌리기 전에 원본을 고치세요.

자주 묻는 질문

제 사진이 1536 px보다 크면 어떻게 되나요? 긴 변이 1536으로 돌아오므로 원본보다 작아질 수 있습니다. 목적지에 더 많은 픽셀이 필요하면 나중에 업스케일링하세요.

영상의 9:16 첫 프레임 만드는 데 쓸 수 있나요? 사람과 포즈가 이미 완성되어 있다면 가능합니다. 가로형 인물을 세로 AI 영상으로 바꾸는 가이드를 참고하세요. 모델 페이지에 현재 스키마와 가격이 있습니다.