name: firefly-expand-fill
description: Adobe Firefly의 Generative Expand 및 Generative Fill API 사용 방법 — 각 API를 사용해야 하는 경우, 마스킹 전략, 배치 및 종횡비 제어, 깔끔한 확장 및 인페인팅을 위한 프롬프트 패턴, 채우기와 대체의 차이점. 사용자가 "generative expand", "extend canvas", "generative fill", "inpaint", "outpaint", "remove object", "replace background", "expand image", "fill image", "masking", "expand-async", "fill-async"를 언급하거나 기존 이미지를 확장/패치/수정하려는 경우 사용합니다. 핵심 아트 자산의 배경 확장 및 캠페인 크리에이터의 브랜드 정렬 배경 교체를 위한 프로덕션 패턴을 인코딩합니다.
license: Apache-2.0
compatibility: firefly_api, ff_apis 스코프 필요. 엔드포인트: firefly-api.adobe.io/v3/images/expand 및 /v3/images/fill. 소스 이미지는 스토리지 참조로 전달되어야 합니다.
allowed-tools: Bash(curl:) Bash(jq:) Read Write Edit
metadata:
version: "1.0.0"
category: image-editing
Firefly Generative Expand & Fill
기존 이미지를 수정하는 두 가지 관련 있지만 다른 API입니다. Expand는 캔버스를 확장하고 새 영역에 새 콘텐츠를 생성합니다. Fill은 마스크에 따라 기존 캔버스 내의 영역을 수정하거나 대체합니다. 올바른 API를 선택하는 것이 절반의 싸움이며, 나머지는 마스크 품질입니다.
이 스킬을 사용해야 하는 경우
다음과 같은 경우에 이 스킬을 사용하세요:
- 사용자가 이미지 캔버스를 어떤 방향으로든 확장하려는 경우
- 사용자가 이미지 영역(배경, 개체, 텍스트 영역)을 대체하거나 수정하려는 경우
- 단일 소스 자산에서 여러 종횡비가 필요한 캠페인이 있는 경우
- 크리에이티브 팀이 이미지에서 원하지 않는 개체를 제거하려는 경우
- 사용자가 인페인팅, 아웃페인팅, 확장 또는 채우기를 언급하는 경우
이 스킬을 사용하지 마십시오:
- 사용자가 완전히 새로운 이미지를 원하는 경우 —
firefly-generate-image-v3-async사용 - 사용자가 기존 이미지의 스타일 변형을 원하는 경우 —
firefly-generate-similar사용 - 변환이 순수 래스터 편집(선명하게, 색상 보정)인 경우 — Lightroom API 사용
Expand vs Fill — 결정 표
| 필요 사항 | 엔드포인트 |
|---|---|
| 캔버스 확장, 새 영역에 콘텐츠 생성 | Expand |
| 이미지 종횡비 변경 (1:1 → 16:9) | Expand |
| 개체 제거 및 영역 패치 | Fill |
| 피사체 유지하며 배경 교체 | 배경을 덮는 마스크와 함께 Fill |
| 특정 영역 교체 (하늘, 땅, 사람의 셔츠) | Fill |
| 손상되거나 원하지 않는 영역 인페인팅 | Fill |
| 아웃페인팅 (고전 AI 아트 "프레임을 넘어 생성") | Expand |
요약: 캔버스 확장 = Expand. 캔버스 유지 = Fill.
Generative Expand
1단계 — 확장 작업 제출
curl --silent -X POST 'https://firefly-api.adobe.io/v3/images/expand' \
-H "Authorization: Bearer $FIREFLY_SERVICES_ACCESS_TOKEN" \
-H "X-Api-Key: $FIREFLY_SERVICES_CLIENT_ID" \
-H 'Content-Type: application/json' \
-d '{
"image": {"source": {"uploadId": "$SOURCE_UPLOAD_ID"}},
"size": {"width": 2304, "height": 1280},
"prompt": "a sweeping desert landscape continuing into the distance",
"placement": {
"alignment": {"horizontal": "center", "vertical": "center"}
},
"numVariations": 2
}'
비동기 작업 패턴(jobId, statusUrl, cancelUrl)을 반환합니다 — firefly-generate-image-v3-async와 동일한 방식으로 폴링합니다.
placement 필드
placement은 원본 이미지가 새 (더 큰) 캔버스 내에 위치하는 위치를 제어합니다:
"placement": {
"alignment": {"horizontal": "center", "vertical": "center"},
"inset": {"left": 0, "top": 0, "right": 0, "bottom": 0}
}
| 정렬 | 효과 |
|---|---|
center, center | 원본이 중앙에, 모든 면에 균등하게 확장 |
left, center | 원본이 왼쪽에, 오른쪽으로 확장 |
right, top | 원본이 오른쪽 상단에, 아래와 왼쪽으로 확장 |
정밀한 픽셀 제어를 위해 inset을 사용하세요. 일반적인 패턴: 원본을 중앙에 배치하고 균등하게 확장합니다. 소셜 미디어 변형(가로 → 세로)의 경우, 피사체가 안전 영역에 있도록 원본을 중앙에서 벗어나 배치하세요.
확장을 위한 prompt 필드
프롬프트는 새 (확장된) 영역에 무엇이 포함되어야 하는지 설명합니다. 원본 이미지는 그대로 유지됩니다. 예시:
| 원본 | 프롬프트 | 결과 |
|---|---|---|
| 사람의 초상화 | "the rest of their body in a business suit" | 원본 머리 + 새 몸통 |
| 흰색 바탕의 제품 | "a kitchen counter with morning light" | 장면 속 제품 |
| 풍경 클로즈업 | "a vast sky with scattered clouds above" | 위로 장면 계속 |
프롬프트를 비워두면 Firefly가 기존 콘텐츠를 스타일리시하게 확장하도록 합니다(자르기/재자르기 워크플로우에 일반적).
종횡비 레시피
일반적인 프로덕션 사용 사례:
| From | To | size | placement.alignment |
|---|---|---|---|
| 1024×1024 (1:1) | 1408×768 (16:9 가로) | width 1408, height 768 | center, center |
| 1024×1024 (1:1) | 768×1408 (9:16 세로) | width 768, height 1408 | center, top (하단 얼굴의 경우) |
| 1408×768 (키 아트) | 2304×1280 (시네마틱) | width 2304, height 1280 | center, center |
| 1024×1024 (정사각형) | 1024×1792 (스토리 세로) | width 1024, height 1792 | center, top |
Generative Fill
1단계 — 마스크 준비
Fill은 Firefly에 수정할 영역을 알려주는 마스크가 필요합니다. 흰색 픽셀 = 채울 영역. 검은색 픽셀 = 유지. 회색조 = 부드러운 혼합.
마스크는 소스 이미지와 동일한 크기여야 합니다. 마스크를 클라이언트 측(이미지 편집기, Photoshop API, 또는 sharp / pillow로 프로그래밍 방식으로)에서 생성하고 스토리지 참조로 업로드합니다.
# 마스크 업로드
MASK_UPLOAD_ID=$(curl --silent -X POST 'https://firefly-api.adobe.io/v2/storage/image' \
-H "Authorization: Bearer $FIREFLY_SERVICES_ACCESS_TOKEN" \
-H "X-API-Key: $FIREFLY_SERVICES_CLIENT_ID" \
-H "Content-Type: image/png" \
--data-binary "@./mask.png" \
| jq -r '.images[0].id')
2단계 — 채우기 작업 제출
curl --silent -X POST 'https://firefly-api.adobe.io/v3/images/fill' \
-H "Authorization: Bearer $FIREFLY_SERVICES_ACCESS_TOKEN" \
-H "X-Api-Key: $FIREFLY_SERVICES_CLIENT_ID" \
-H 'Content-Type: application/json' \
-d '{
"image": {
"source": {"uploadId": "$SOURCE_UPLOAD_ID"},
"mask": {"source": {"uploadId": "$MASK_UPLOAD_ID"}}
},
"prompt": "a modern minimalist living room background",
"numVariations": 2
}'
비동기 작업 패턴을 반환합니다 — 완료를 위해 폴링합니다.
채우기를 위한 prompt 필드
프롬프트는 마스킹된 영역에 무엇이 나타나야 하는지 설명합니다. 마스킹되지 않은 영역은 그대로 유지됩니다.
| 마스크가 덮는 영역 | 프롬프트 | 결과 |
|---|---|---|
| 제품 사진의 배경 | "marble kitchen counter" | 제품 변경되지 않음, 새 배경 |
| 원하지 않는 사람 | "empty park bench" | 사람 제거, 벤치가 영역을 채움 |
| 레이블 영역 | "minimal white space" | 레이블 제거, 영역 정리 |
| 차량의 색상 영역 | "matte red paint" | 차량이 이제 빨간색 |
마스크 생성 전략
| 전략 | 도구 | 시기 |
|---|---|---|
| 수동 마스크 | Photoshop, 이미지 편집기 | 일회성 크리에이티브 작업 |
| 프로그래밍 방식 마스크 | sharp, pillow | 기하학적 영역 (상단 절반, 왼쪽 1/3) |
| 피사체 감지 | Photoshop API select_subject 또는 사용자 정의 세분화 | 배경 교체, 피사체 분리 |
| 색상 키 마스크 | sharp 임계값 | 특정 색상 영역 교체 |
| AI 세분화 | SAM (Segment Anything), Mediapipe | 프로덕션 세분화 파이프라인 |
대량 워크플로우(매일 수백 개의 핵심 아트 자산에 대한 배경 확장)의 경우, 마스크는 피사체 감지에서 프로그래밍 방식으로 생성됩니다. 절대 수동이 아닙니다.
파이프라인에서 Expand + Fill 결합
일반적인 프로덕션 파이프라인:
소스 키 아트 (1408×768)
↓ Expand (2304×1280으로, 장면을 확장하는 프롬프트)
확장된 이미지
↓ Fill (텍스트 영역을 덮는 마스크, 프롬프트: "clean background")
정리된 시네마틱 버전
↓ Photoshop API 작업 적용 (텍스트 오버레이, 레이어 합성)
최종 자산
이것은 축약된 표준 키 아트 생성 패턴입니다. 각 단계는 비동기 작업입니다. 파이프라인은 큐로 관리됩니다(firefly-services-rate-limits 참조).
프로덕션 패턴
패턴: 단일 소스에서 여러 종횡비 생성
하나의 정사각형 키 아트가 주어지면 가로, 세로, 스토리 형식을 생성합니다:
const aspects = [
{ name: 'landscape-16-9', size: { width: 1408, height: 768 }, alignment: { horizontal: 'center', vertical: 'center' } },
{ name: 'portrait-9-16', size: { width: 768, height: 1408 }, alignment: { horizontal: 'center', vertical: 'top' } },
{ name: 'story-9-16', size: { width: 1024, height: 1792 }, alignment: { horizontal: 'center', vertical: 'top' } },
];
const jobs = await Promise.all(
aspects.map(a => submitExpand({
sourceUploadId: SOURCE_ID,
size: a.size,
placement: { alignment: a.alignment },
prompt: 'continue the scene naturally',
numVariations: 2,
})),
);
세 개의 제출, ~6개의 출력을 병렬로 생성합니다. 각 출력을 종횡비 태그와 함께 유지하여 다운스트림 크리에이티브 팀이 사용할 수 있도록 합니다.
패턴: 규모가 있는 배경 교체
브랜드 캠페인 크리에이터 배경 교체용:
소스 이미지
↓ Photoshop API: select_subject → 마스크 (피사체 흰색, 배경 검은색)
↓ 마스크 반전 (피사체 검은색, 배경 흰색) — Sharp/Pillow
반전된 마스크로 채우기 요청
↓ 프롬프트: "<브랜드 정렬 배경>"
출력: 피사체 유지, 새 배경
반전 단계는 매우 중요합니다. Photoshop의 select_subject는 피사체 마스크를 제공하지만, 배경 교체에는 그 반대가 필요합니다.
검증
다음 조건이 충족되면 Expand/Fill 파이프라인이 프로덕션 준비 상태입니다:
- Expand와 Fill 사이의 결정이 사용 사례별로 문서화됨
- 마스크 생성이 자동화되어 있고 수동이 아님 (50개 이상의 볼륨의 경우)
- 마스크가 제출 전에 올바른 크기와 극성으로 검증됨
- 출력이 성공으로 표시되기 전에 소스와 시각적으로 비교 검사됨
- 다중 종횡비 파이프라인이 순차가 아닌 병렬로 제출됨
placement결정이 브랜드 안전 영역 지침과 일치함
문제 해결 및 에지 케이스
- Expand 출력에 원본과 새 콘텐츠 사이에 눈에 띄는 이음새가 있음: 원본에 비정상적인 색상 또는 그레인이 있을 수 있습니다. 시드를 변경하여 재생성하거나, 소스의 품질을 설명하는 프롬프트를 확장해 보세요.
- Fill 프롬프트가 무시됨: 마스크가 반전되었을 가능성이 높습니다(흰색 = 유지, 검은색 = 채우기 대신 그 반대). 마스크 극성을 다시 확인하세요.
- Fill 출력이 마스크 외부로 번짐: 마스크 가장자리가 너무 부드럽습니다(심한 가우시안 블러). 마스크 가장자리를 선명하게 하거나 이진 마스크를 사용하세요.
- Expand가 피사체 배치를 예기치 않게 변경함:
placement.alignment를 명시적으로 설정하세요. 기본값이 피사체를 이동시킬 수 있습니다. - 마스크가 너무 큼(>8MB): 마스크를 압축하세요. 제한된 팔레트를 가진 단일 채널 회색조 PNG가 일반적으로 잘 압축됩니다.
- 극단적인 종횡비로의 Expand가 부자연스러워 보임: 두 단계로 확장하세요. 원본 → 중간 → 최종. 각 단계는 더 작은 도약입니다.
- Fill이 피사체를 완전히 제거함: 마스크가 피사체와 겹치고 있습니다. 마스크를 배경으로만 좁히세요.
다른 스킬과의 연결
firefly-services-storage-refs— 마스크 + 소스 업로드firefly-generate-image-v3-async— 동일한 비동기 패턴photoshop-api-actions— 자동화된 마스크 생성(select_subject)용firefly-services-rate-limits— 배치 파이프라인용