Firefly 生成式擴充與填補是做什麼的？

兩個相關但用途不同的 API，用於修改現有影像。擴充會擴大畫布，並在新增區域生成新內容。填補則透過遮罩引導，修改或取代現有畫布內的區域。選擇正確的 API 是成功的一半，另一半則取決於遮罩品質。

何時使用此技能

在以下情況使用此技能：

使用者想要向任何方向延伸影像的畫布
使用者想要取代或修改影像中的區域（背景、物體、文字區域）
行銷活動需要從單一素材產生多種長寬比
創意團隊想要從影像中移除不需要的物體
使用者提到修飾、外繪、擴充或填補

請勿在以下情況使用此技能：

使用者想要一張全新的影像——請使用 firefly-generate-image-v3-async
使用者想要現有影像的風格變體——請使用 firefly-generate-similar
轉換僅是純點陣編輯（銳利化、色彩校正）——請使用 Lightroom API

擴充 vs 填補 — 決策表

需求	端點
擴大畫布，在新區域生成內容	擴充
變更影像長寬比（1:1 → 16:9）	擴充
移除物體並修補區域	填補
保留主體同時替換背景	填補（遮罩覆蓋背景）
替換特定區域（天空、地面、人物的衣服）	填補
修補受損或不需要的區域	填補
外繪（經典 AI 藝術「生成超出畫面」）	擴充

簡而言之：畫布變大 = 擴充。畫布不變 = 填補。

生成式擴充

步驟 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": "一片廣闊的沙漠景觀，持續延伸至遠方",
    "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` 欄位

提示描述新（擴充）區域應包含的內容。原始影像保持不變。範例：

原始影像	提示	結果
人物肖像	"穿著商務西裝的身體其餘部分"	原始頭部 + 新身體
白色背景上的產品	"一個早晨光線下的廚房檯面"	產品融入場景
風景特寫	"上方有散落雲朵的廣闊天空"	場景向上延伸

留空提示，讓 Firefly 以風格延伸現有內容（常見於裁切/重新裁切工作流程）。

長寬比配方

常見生產使用案例：

從	到	`size`	`placement.alignment`
1024×1024 (1:1)	1408×768 (16:9 橫向)	寬 1408，高 768	center, center
1024×1024 (1:1)	768×1408 (9:16 直向)	寬 768，高 1408	center, top (下半臉)
1408×768 (主視覺)	2304×1280 (電影級)	寬 2304，高 1280	center, center
1024×1024 (方形)	1024×1792 (限時動態直向)	寬 1024，高 1792	center, top

生成式填補

步驟 1 — 準備遮罩

填補需要一個遮罩來告訴 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": "一個現代簡約的客廳背景",
    "numVariations": 2
  }'

傳回非同步工作模式——輪詢直到完成。

填補的 `prompt` 欄位

提示描述遮罩區域內應顯示的內容。未遮罩的區域保持不變。

遮罩覆蓋範圍	提示	結果
產品拍攝的背景	"大理石廚房檯面"	產品不變，新背景
一個不需要的人物	"空長椅"	人物移除，長椅填滿區域
標籤區域	"極簡白色空間"	標籤消失，區域清除
車輛的顏色區域	"消光紅漆"	車輛現在是紅色

遮罩生成策略

策略	工具	時機
手動遮罩	Photoshop、影像編輯器	一次性創意工作
程式化遮罩	`sharp`、`pillow`	幾何區域（上半部、左三分之一）
主體偵測	Photoshop API `select_subject` 或自訂分割	取代背景、隔離主體
色彩鍵遮罩	`sharp` 閾值	取代特定顏色區域
AI 分割	SAM (Segment Anything)、Mediapipe	生產分割管線

對於高產量工作流程（每日數百個主視覺素材的背景延伸），遮罩是透過主體偵測程式化生成的——絕不手動。

在管線中結合擴充與填補

一個常見的生產管線：

來源主視覺 (1408×768)
  ↓ 擴充（至 2304×1280，提示延伸場景）
擴充後的影像
  ↓ 填補（遮罩覆蓋文字區域，提示：「乾淨背景」）
清理後的電影級版本
  ↓ 套用 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: '自然地延續場景',
    numVariations: 2,
  })),
);

三個提交，平行產生約 6 個輸出。每個輸出都帶有長寬比標籤保存，供下游創意團隊使用。

模式：大規模背景替換

用於品牌活動創作者背景交換：

來源影像
  ↓ Photoshop API: select_subject → 遮罩（主體白色，背景黑色）
  ↓ 反轉遮罩（主體黑色，背景白色）—— Sharp/Pillow
使用反轉遮罩的填補請求
  ↓ prompt: "<品牌對齊背景>"
輸出：主體保留，新背景

反轉步驟至關重要——Photoshop 的 select_subject 提供主體遮罩；對於背景替換，您需要的是反轉版本。

驗證

當滿足以下條件時，擴充/填補管線已準備好投入生產：

每個使用案例都記錄了擴充與填補之間的決策
遮罩生成是自動化的，而非手動（對於任何超過 50 的數量）
遮罩在提交前已驗證正確的尺寸和正確的極性
輸出在標記為成功之前，已與來源進行視覺檢查
多長寬比管線平行提交，而非依序
placement 決策符合品牌安全區域指南

故障排除與邊緣情況

擴充輸出在原始與新內容之間有明顯接縫： 原始影像可能有異常顏色或顆粒感。嘗試變更種子重新生成，或擴充提示以描述來源影像的品質。
填補提示被忽略： 遮罩可能反轉（白色 = 保留，黑色 = 填補，而非相反）。重新檢查遮罩極性。
填補輸出超出遮罩邊界： 遮罩邊緣太柔和（嚴重的高斯模糊）。銳利化遮罩邊緣，或使用二值遮罩。
擴充意外變更主體位置： 明確設定 placement.alignment——預設值可能會移動主體。
遮罩太大（>8MB）： 壓縮遮罩。單通道灰階 PNG 搭配有限調色盤通常可良好壓縮。
擴充到極端長寬比看起來不自然： 分兩步驟擴充：原始 → 中等 → 最終。每個步驟的跨度較小。
填補完全移除主體： 遮罩與主體重疊。將遮罩限制為僅背景。

與其他技能串聯

firefly-services-storage-refs — 遮罩 + 來源上傳
firefly-generate-image-v3-async — 相同的非同步模式
photoshop-api-actions — 用於自動化遮罩生成（select_subject）
firefly-services-rate-limits — 用於批次管線

Firefly 生成式擴充與填補