Firefly Expand & Fill

Firefly Generative Expand & Fill

Zwei verwandte, aber unterschiedliche APIs zum Bearbeiten vorhandener Bilder. Expand vergrößert die Leinwand und generiert neuen Inhalt in den neuen Bereich. Fill modifiziert oder ersetzt Bereiche innerhalb der vorhandenen Leinwand, gesteuert durch eine Maske. Die richtige Wahl zu treffen, ist die halbe Miete; der Rest ist die Qualität der Maske.

Wann dieses Skill verwenden

Dieses Skill verwenden, wenn:

• Der Nutzer die Leinwand eines Bildes in eine beliebige Richtung erweitern möchte
• Der Nutzer einen Bereich eines Bildes (Hintergrund, Objekt, Textfläche) ersetzen oder modifizieren möchte
• Eine Kampagne mehrere Seitenverhältnisse aus einem einzigen Quell-Asset benötigt
• Ein Kreativteam ein unerwünschtes Objekt aus einem Bild entfernen möchte
• Der Nutzer Inpainting, Outpainting, Expand oder Fill erwähnt

Dieses Skill NICHT verwenden, wenn:

• Der Nutzer ein völlig neues Bild möchte – stattdessen firefly-generate-image-v3-async verwenden
• Der Nutzer stilistische Variationen eines vorhandenen Bildes möchte – stattdessen firefly-generate-similar verwenden
• Die Transformation eine rein rasterbasierte Bearbeitung ist (schärfen, farbkorrigieren) – Lightroom API verwenden

Expand vs. Fill – Entscheidungstabelle

Anforderung	Endpunkt
Leinwand vergrößern, Inhalt im neuen Bereich generieren	Expand
Seitenverhältnis eines Bildes ändern (1:1 → 16:9)	Expand
Objekt entfernen und Bereich ersetzen	Fill
Hintergrund ersetzen, Motiv beibehalten	Fill mit Maske, die den Hintergrund abdeckt
Bestimmten Bereich ersetzen (Himmel, Boden, Kleidungsstück)	Fill
Beschädigten oder unerwünschten Bereich ausbessern (Inpainting)	Fill
Outpainting (das klassische KI-Kunst „über den Rahmen hinaus generieren“)	Expand

Kurz gesagt: Leinwand wächst = Expand. Leinwand bleibt = Fill.

Generative Expand

Schritt 1 – Expand-Job einreichen

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
  }'

Gibt das asynchrone Job-Muster zurück (jobId, statusUrl, cancelUrl) – Abfrage auf die gleiche Weise wie bei firefly-generate-image-v3-async.

Das placement-Feld

placement steuert, wo das Originalbild innerhalb der neuen (größeren) Leinwand positioniert wird:

"placement": {
  "alignment": {"horizontal": "center", "vertical": "center"},
  "inset": {"left": 0, "top": 0, "right": 0, "bottom": 0}
}

Ausrichtung	Effekt
center, center	Original in der Mitte, gleichmäßig auf allen Seiten erweitert
left, center	Original links, nach rechts erweitert
right, top	Original oben rechts, nach unten und links erweitert

inset für feine Pixelkontrolle verwenden. Typisches Muster: Original zentrieren, gleichmäßig erweitern. Für Social-Media-Varianten (Querformat → Hochformat) das Original außermittig platzieren, damit das Motiv im sicheren Bereich landet.

Das prompt-Feld für Expand

Prompts beschreiben, was der neue (erweiterte) Bereich enthalten soll. Das Originalbild bleibt unverändert. Beispiele:

Original	Prompt	Ergebnis
Porträt einer Person	"the rest of their body in a business suit"	Originalkopf + neuer Körper
Produkt auf Weiß	"a kitchen counter with morning light"	Produkt in Szene
Landschaftsnahaufnahme	"a vast sky with scattered clouds above"	Szene setzt sich nach oben fort

prompt leer lassen, damit Firefly den vorhandenen Inhalt stilistisch fortsetzt (üblich für Zuschneide-/Neuzuschneide-Workflows).

Seitenverhältnis-Rezepte

Häufige Produktionsanwendungsfälle:

Von	Nach	size	placement.alignment
1024×1024 (1:1)	1408×768 (16:9 Querformat)	width 1408, height 768	center, center
1024×1024 (1:1)	768×1408 (9:16 Hochformat)	width 768, height 1408	center, top (unteres Gesicht)
1408×768 (Key Art)	2304×1280 (filmisch)	width 2304, height 1280	center, center
1024×1024 (quadratisch)	1024×1792 (Story-Hochformat)	width 1024, height 1792	center, top

Generative Fill

Schritt 1 – Maske vorbereiten

Fill erfordert eine Maske, die Firefly mitteilt, welcher Bereich modifiziert werden soll. Weiße Pixel = diesen Bereich füllen. Schwarze Pixel = erhalten. Graustufen = weiche Überblendung.

Die Maske muss die gleichen Abmessungen wie das Quellbild haben. Die Maske clientseitig generieren (Bildeditor, Photoshop API oder programmatisch mit sharp / pillow) und als Storage-Referenz hochladen.

# Maske hochladen
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')

Schritt 2 – Fill-Job einreichen

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
  }'

Gibt das asynchrone Job-Muster zurück – auf Abschluss abfragen.

Das prompt-Feld für Fill

Prompts beschreiben, was im maskierten Bereich erscheinen soll. Der nicht maskierte Bereich bleibt unverändert.

Maske abdeckt	Prompt	Ergebnis
Hintergrund eines Produktfotos	"marble kitchen counter"	Produkt unverändert, neuer Hintergrund
Eine unerwünschte Person	"empty park bench"	Person entfernt, Bank füllt den Bereich
Ein Etikettenbereich	"minimal white space"	Etikett weg, Bereich bereinigt
Farbbereich eines Fahrzeugs	"matte red paint"	Fahrzeug jetzt rot

Strategien zur Maskenerstellung

Strategie	Werkzeug	Wann
Manuelle Maske	Photoshop, Bildeditor	Einmalige kreative Arbeit
Programmatische Maske	sharp, pillow	Geometrische Bereiche (obere Hälfte, linkes Drittel)
Motivdetektion	Photoshop API select_subject oder benutzerdefinierte Segmentierung	Hintergrund ersetzen, Motiv isolieren
Farbkey-Maske	sharp Schwellwert	Bestimmten farbigen Bereich ersetzen
KI-Segmentierung	SAM (Segment Anything), Mediapipe	Produktionssegmentierungs-Pipelines

Für Workflows mit hohem Volumen (Hintergrunderweiterung bei Hunderten von Key-Art-Assets täglich) werden Masken programmatisch aus der Motivdetektion generiert – niemals von Hand.

Kombinieren von Expand + Fill in einer Pipeline

Eine gängige Produktionspipeline:

Quell-Key-Art (1408×768)
  ↓ Expand (auf 2304×1280, Prompt erweitert die Szene)
Erweitertes Bild
  ↓ Fill (Maske deckt Textbereich ab, Prompt: "clean background")
Bereinigte filmische Version
  ↓ Anwenden von Photoshop-API-Aktionen (Texteinblendung, Ebenenkomposition)
Endgültiges Asset

Dies ist das kanonische Muster zur Key-Art-Generierung, komprimiert dargestellt. Jede Stufe ist ein asynchroner Job; die Pipeline wird front-gesteuert (siehe firefly-services-rate-limits).

Produktionsmuster

Muster: Multi-Seitenverhältnis-Generierung aus einer Quelle

Aus einem quadratischen Key-Art Landschafts-, Hoch- und Story-Formate generieren:

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,
  })),
);

Drei Einreichungen, ~6 Ausgaben parallel. Jede mit dem Seitenverhältnis-Tag für das nachgelagerte Kreativteam speichern.

Muster: Hintergrundtausch in großem Maßstab

Für Markenkampagnen-Creator-Hintergrundtausche:

Quellbild
  ↓ Photoshop API: select_subject → Maske (Motiv weiß, Hintergrund schwarz)
  ↓ Maske invertieren (Motiv schwarz, Hintergrund weiß) – Sharp/Pillow
Fill-Anfrage mit invertierter Maske
  ↓ prompt: "<markenkonformer Hintergrund>"
Ausgabe: Motiv erhalten, neuer Hintergrund

Der Invertierungsschritt ist entscheidend – select_subject von Photoshop liefert die Motivmaske; für den Hintergrundtausch wird die Inverse benötigt.

Validierung

Expand-/Fill-Pipelines sind produktionsreif, wenn:

1. Die Entscheidung zwischen Expand und Fill pro Anwendungsfall dokumentiert ist
2. Die Maskenerstellung automatisiert ist, nicht manuell (für jedes Volumen >50)
3. Masken vor der Einreichung auf korrekte Abmessungen und korrekte Polarität validiert werden
4. Die Ausgabe vor der Markierung als erfolgreich visuell mit der Quelle verglichen wird
5. Multi-Seitenverhältnis-Pipelines parallel und nicht sequenziell eingereicht werden
6. Die placement-Entscheidungen mit den Markenrichtlinien für den sicheren Bereich übereinstimmen

Fehlerbehebung & Grenzfälle

• Expand-Ausgabe zeigt sichtbare Naht zwischen Original und neuem Inhalt: Das Original hat möglicherweise ungewöhnliche Farbe oder Körnung. Erneute Generierung mit geändertem Seed versuchen oder den Prompt um eine Beschreibung der Eigenschaften der Quelle erweitern.
• Fill-Prompt wird ignoriert: Die Maske ist wahrscheinlich invertiert (weiß = erhalten, schwarz = füllen anstatt umgekehrt). Polarität der Maske erneut prüfen.
• Fill-Ausgabe läuft außerhalb der Maske aus: Die Maskenkanten sind zu weich (starker Gaußscher Weichzeichner). Maskenkanten schärfen oder eine binäre Maske verwenden.
• Expand ändert die Motivplatzierung unerwartet: placement.alignment explizit setzen – die Standardwerte können das Motiv verschieben.
• Maske zu groß (>8 MB): Maske komprimieren. Graustufen-PNG mit begrenzter Palette lässt sich in der Regel gut komprimieren.
• Expand auf extremes Seitenverhältnis wirkt unnatürlich: Expand in zwei Schritten: Original → mittel → endgültig. Jeder Schritt ist ein kleinerer Sprung.
• Fill entfernt das gesamte Motiv: Die Maske überlappt das Motiv. Maske auf den Hintergrund beschränken.

Verkettung mit anderen Skills

• firefly-services-storage-refs – Masken- + Quell-Upload
• firefly-generate-image-v3-async – Gleiches asynchrones Muster
• photoshop-api-actions – Für automatisierte Maskenerstellung (select_subject)
• firefly-services-rate-limits – Für Batch-Pipelines

Referenzen

• Generative Expand Tutorial
• Generative Fill Tutorial
• Masking Concept
• Placement Concept