Seedream v4.5 Edit API: Programmatische Bildbearbeitung

Das Ausführen von Seedream v4.5 Edit über die Arteza-Oberfläche eignet sich für einzelne Bearbeitungen und kleine Mengen. Für Workflows mit hohem Volumen, also Kataloge mit Tausenden von SKUs, dynamische Bildgenerierung pro Nutzer oder CMS-gesteuerte Asset-Pipelines, empfiehlt sich der API-Zugriff. Diese Anleitung erklärt die Endpunktstruktur, Request-Parameter, Response-Verarbeitung und Produktionsmuster für den Aufbau automatisierter Bildbearbeitungssysteme mit Seedream v4.5.

Zusammenfassung

• Seedream v4.5 Edit ist über den Endpunkt fal-ai/bytedance/seedream/v4.5/edit verfügbar
• Gleiche 1 Credits ($0,10) pro Bild wie in der Oberfläche
• Akzeptiert bis zu 10 Eingabebild-URLs plus einen Textprompt
• 4MP (2048×2048) Ausgabe wird als Bild-URL zurückgegeben
• Typische Generierungszeit von 30-60 Sekunden, für die Produktion asynchrone Muster verwenden

Warum die API nutzen

Die API ermöglicht Automatisierungsmuster, die die Oberfläche nicht bieten kann:

• Batch-Verarbeitung in großem Umfang. Über 1.000 Bearbeitungen in einem einzigen Pipeline-Durchlauf verarbeiten.
• Dynamische Generierung. Bilder auf Abruf aus Nutzerdaten oder Datenbankeinträgen erstellen.
• Geplante Workflows. Nächtliche Katalog-Updates, ereignisgesteuerte Neugenerierung.
• Integration in bestehende Stacks. Node.js, Python, Go, Ruby, jeder HTTP-Client.
• Reproduzierbare Produktion. Versionskontrollierte Skripte statt manueller Klicks.

Wenn der Anwendungsfall mehr als 20-50 ähnliche Bearbeitungen umfasst, lohnt sich die Einrichtung der API.

Endpunktstruktur

Das Seedream v4.5 Edit-Modell ist verfügbar unter:

fal-ai/bytedance/seedream/v4.5/edit

Dies ist ein Standard-fal.ai-Modellendpunkt, der direkt oder über das Arteza-Kreditsystem aufgerufen werden kann.

Authentifizierung

Arteza-API-Anfragen authentifizieren sich über einen API-Schlüssel, der im Header Authorization als Bearer-Token übergeben wird.

API-Schlüssel abrufen

1. Bei arteza.ai anmelden
2. Zu den Kontoeinstellungen navigieren
3. Den Bereich API aufrufen
4. Einen neuen API-Schlüssel generieren
5. Sicher aufbewahren, wie ein Passwort behandeln

Den API-Schlüssel niemals in die Versionskontrolle einchecken. Umgebungsvariablen verwenden:

export SEEDANCE_API_KEY="your_api_key_here"

Authentifizierungs-Header

Authorization: Bearer your_api_key_here

Request-Struktur

Eine einfache Seedream v4.5 Edit-Anfrage sieht so aus:

{
  "prompt": "Replace the background with a polished marble surface. Preserve the product position, color, and lighting exactly. Add a subtle contact shadow.",
  "image_urls": [
    "https://your-bucket.com/product-shot.jpg"
  ],
  "num_images": 1,
  "output_format": "png"
}

Parameterreferenz

Es können bis zu 10 Bild-URLs übergeben werden. Das Modell behandelt das erste Bild als Hauptbild und die folgenden als Referenzen.

Beispielanfrage: Node.js

const response = await fetch("https://api.arteza.ai/v1/seedream/v4.5/edit", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SEEDANCE_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    prompt: "Replace the background with a polished marble surface. Preserve the product position, color, and lighting exactly.",
    image_urls: [
      "https://your-bucket.com/product-shot.jpg"
    ],
    num_images: 1,
    output_format: "png"
  })
});

const result = await response.json();
console.log(result.images[0].url);

Beispielanfrage: Python

import os
import requests

response = requests.post(
    "https://api.arteza.ai/v1/seedream/v4.5/edit",
    headers={
        "Authorization": f"Bearer {os.environ['SEEDANCE_API_KEY']}",
        "Content-Type": "application/json"
    },
    json={
        "prompt": "Replace the background with a polished marble surface. Preserve the product position, color, and lighting exactly.",
        "image_urls": [
            "https://your-bucket.com/product-shot.jpg"
        ],
        "num_images": 1,
        "output_format": "png"
    }
)

result = response.json()
print(result["images"][0]["url"])

Response-Struktur

Eine erfolgreiche Antwort enthält die generierten Bild-URLs:

{
  "images": [
    {
      "url": "https://storage.arteza.ai/output/abc123.png",
      "width": 2048,
      "height": 2048,
      "content_type": "image/png"
    }
  ],
  "seed": 123456789,
  "credits_used": 8
}

Das Bild von der zurückgegebenen URL herunterladen: Ausgabe-URLs sind 24 Stunden lang gültig.

Asynchrones Generierungsmuster

Seedream v4.5 Edit benötigt 30-60 Sekunden pro Anfrage. Für die Produktion empfiehlt sich die asynchrone Generierung mit Webhooks oder Polling anstelle von blockierenden Anfragen.

Webhook-basiertes Async

Eine webhook_url in der Anfrage übergeben, und Arteza sendet das Ergebnis per POST dorthin, sobald die Generierung abgeschlossen ist:

{
  "prompt": "...",
  "image_urls": ["..."],
  "webhook_url": "https://your-app.com/webhooks/seedream"
}

Der Webhook-Handler empfängt:

{
  "request_id": "req_abc123",
  "status": "completed",
  "images": [
    {
      "url": "https://storage.arteza.ai/output/xyz.png"
    }
  ]
}

Webhook-Verarbeitung ist das empfohlene Produktionsmuster.

Jetzt loslegen. Zuerst das Tool ausprobieren.

Polling-basiertes Async

Wenn die Infrastruktur keine Webhooks empfangen kann, den Status per Polling abfragen:

const initResponse = await fetch("https://api.arteza.ai/v1/seedream/v4.5/edit", {
  method: "POST",
  headers: { "Authorization": `Bearer ${key}`, "Content-Type": "application/json" },
  body: JSON.stringify({ prompt, image_urls, async: true })
});

const { request_id } = await initResponse.json();

// Status abfragen
let result;
while (!result) {
  await new Promise(r => setTimeout(r, 5000));
  const statusResponse = await fetch(
    `https://api.arteza.ai/v1/requests/${request_id}`,
    { headers: { "Authorization": `Bearer ${key}` } }
  );
  const status = await statusResponse.json();
  if (status.status === "completed") result = status;
}

Alle 5-10 Sekunden abfragen. Die Gesamtwartezeit beträgt in der Regel 30-60 Sekunden.

Produktionsmuster

Muster 1: Katalog-Batch-Generierung

Die API über den Produktkatalog laufen lassen, um konsistente Hintergrundwechsel für jede SKU zu generieren:

for product in catalog:
    response = requests.post(
        API_URL,
        headers=HEADERS,
        json={
            "prompt": PROMPT_TEMPLATE.format(product_name=product.name),
            "image_urls": [product.source_image_url],
            "webhook_url": WEBHOOK_URL
        }
    )
    log_request(product.id, response.json()["request_id"])

Mit einem Webhook-Handler kombinieren, der Ausgaben im CDN speichert und den Produktdatensatz aktualisiert.

Muster 2: On-Demand-Bearbeitungen durch Nutzer

Nutzern ermöglichen, Bilder hochzuladen und KI-bearbeitete Ergebnisse auf Abruf zu erhalten:

1. Nutzer lädt Bild in den eigenen Bucket hoch
2. Das Backend ruft Seedream v4.5 Edit mit einem nutzerseitig gewählten Prompt auf
3. Per Polling oder Webhook auf das Ergebnis warten
4. Ergebnis-URL an den Client des Nutzers zurückgeben

In der Nutzererfahrung etwa 60 Sekunden Wartezeit pro Bearbeitung einplanen.

Muster 3: CMS-gesteuerte Asset-Pipeline

Wenn Inhalte im CMS veröffentlicht werden, zugehörige Bilder automatisch generieren:

1. CMS sendet ein Publish-Ereignis
2. Serverless-Funktion wird ausgelöst
3. Ruft Seedream v4.5 Edit mit einem Template-Prompt auf
4. Speichert das Ergebnis im CDN
5. Aktualisiert den CMS-Datensatz mit der Bild-URL

Dieses Muster eliminiert die manuelle Bilderstellung bei hohem Veröffentlichungsvolumen.

Fehlerbehandlung

Häufige Fehlerantworten:

API-Aufrufe immer in try/except mit Retry-Logik für 429- und 500-Antworten einwickeln.

Rate-Limits

Arteza wendet angemessene Rate-Limits auf die API an. Bei den meisten Produktions-Workflows werden diese nicht erreicht, aber für Bulk-Batches mit mehr als 1.000 Anfragen Folgendes implementieren:

• Exponentielles Backoff bei 429-Antworten
• Begrenzung paralleler Anfragen (mit 5 parallelen Anfragen beginnen und hochskalieren)
• Request-Queueing für vorhersehbaren Durchsatz

Den Support für höhere Rate-Limits bei umfangreichen Produktions-Workloads kontaktieren.

Kosten bei API-Volumen

API-Aufrufe kosten dasselbe wie Aufrufe über die Oberfläche: 1 Credits ($0,10) pro Bild. Zur Planung:

• 100 API-Aufrufe = 100 Credits (gut innerhalb des 5-Dollar-Starter-Tarifs)
• 1.000 API-Aufrufe = 1.000 Credits (der 120-Dollar-Studio-Tarif, 1.800 pro Monat)
• 10.000 API-Aufrufe = 10.000 Credits (der 120-Dollar-Studio-Tarif plus etwa 8.200 Credits in Top-ups)

Bei Volumen über 10.000 pro Monat das Team für individuelle Preisgestaltung kontaktieren.

Best Practices

1. Webhooks in der Produktion verwenden. Polling funktioniert, verschwendet aber Ressourcen.
2. Prompts in der Versionskontrolle speichern. Prompts wie Code behandeln.
3. Alles protokollieren. Request-IDs, Prompts, Ausgaben, Fehler.
4. Eingaben vor dem Aufruf validieren. Ungültige Bild-URLs verschwenden Credits.
5. Credit-Guthaben überwachen. Warnung ausgeben, wenn ein Schwellenwert unterschritten wird.
6. Prompt-Änderungen in der Staging-Umgebung testen. Vor einem vollständigen Batch an 3-5 Bildern validieren.
7. Ergebnisse cachen. Bei identischen Eingaben vorherige Ausgaben wiederverwenden.

Weiterführende Informationen

• Vollständiger Leitfaden zur Bearbeitung mit Seedream v4.5
• Tutorial zur Stapelbearbeitung
• Preisübersicht

Einstieg

API-Schlüssel im Arteza-Dashboard generieren, 10 kostenlose Credits holen und das Node.js-Beispiel oben mit einem Produktfoto ausführen. Die API erschließt das volle Produktionspotenzial von Seedream v4.5 Edit: Sobald sie eingebunden ist, dreht sich alles um Prompt-Engineering. Für praktische Tests zuerst das Web-Tool öffnen aufrufen und Prompts validieren, bevor die Automatisierung gestartet wird.