Firefly 生成式扩展与填充是做什么的？

两个相关但不同的 API，用于修改现有图像。Expand（扩展） 会增大画布并在新区域生成内容。Fill（填充） 通过遮罩修改或替换现有画布内的区域。选择正确的 API 是成功的一半；另一半则取决于遮罩的质量。

何时使用此技能

在以下情况使用此技能：

用户想要向任意方向扩展图像的画布
用户想要替换或修改图像中的某个区域（背景、物体、文字区域）
某个营销活动需要从单一源素材生成多种宽高比
创意团队想要从图像中移除不需要的物体
用户提到了内补绘制（inpainting）、外补绘制（outpainting）、扩展或填充

不要在以下情况使用此技能：

用户想要一张全新的图像 —— 请使用 firefly-generate-image-v3-async
用户想要对现有图像进行风格变化 —— 请使用 firefly-generate-similar
该操作纯粹是栅格编辑（锐化、色彩校正）—— 请使用 Lightroom API

扩展 vs 填充 —— 决策表

需求	端点
增大画布，在新区域生成内容	Expand
改变图像宽高比（1:1 → 16:9）	Expand
移除物体并修补区域	Fill
替换背景同时保留主体	Fill（使用覆盖背景的遮罩）
替换特定区域（天空、地面、人物的衬衫）	Fill
内补绘制受损或不想要的区域	Fill
外补绘制（经典的 AI 艺术“在画框外生成”）	Expand

简而言之：画布扩大 = Expand。画布不变 = Fill。

生成式扩展

第一步 —— 提交扩展任务

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

提示词描述新（扩展）区域应包含的内容。原始图像保持不变。示例：

原始图像	提示词	结果
人物肖像	"穿着商务套装的身体其余部分"	原始头部 + 新身体
白色背景上的产品	"带有晨光的厨房台面"	产品置于场景中
风景特写	"上方广阔的天空，散布着云朵"	场景向上延伸

留空 prompt 可让 Firefly 从风格上延续现有内容（常用于裁剪/重新裁剪工作流）。

宽高比配方

常见的生产用例：

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

生成式填充

第一步 —— 准备遮罩

填充需要一个遮罩来告诉 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')

第二步 —— 提交填充任务

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
使用反转遮罩的填充请求
  ↓ 提示词：“<品牌对齐的背景>”
输出：主体保留，新背景

反转步骤至关重要——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 生成式扩展与填充