Seedream v4.5 Edit API: Programmgesteuerte Bildbearbeitung

Die Verwendung von Seedream v4.5 Edit über die Arteza-Benutzeroberfläche funktioniert für einzelne Bearbeitungen und kleine Serien. Für High-Volume-Workflows, Kataloge mit Tausenden von SKUs, dynamische benutzerspezifische Bildgenerierung, CMS-gesteuerte Asset-Pipelines, benötigen Sie API-Zugang. Dieser Leitfaden führt Sie durch die Endpunkt-Struktur, Request-Parameter, Response-Handling und Production-Muster zum Aufbau automatisierter Bildbearbeitungssysteme auf Seedream v4.5.

Warum die API nutzen

Die API ermöglicht Automatisierungsmuster, die die Benutzeroberfläche nicht bietet:

• High-Volume-Batching. Verarbeiten Sie 1.000+ Bearbeitungen in einem einzelnen Pipeline-Durchlauf.
• Dynamische Generierung. Erstellen Sie Bilder on-demand aus Benutzerdaten oder Datenbankeinträgen.
• Geplante Workflows. Nächtliche Katalogaktualisierungen, ereignisgesteuerte Regeneration.
• Integration mit bestehenden Stacks. Node.js, Python, Go, Ruby, jeder HTTP-Client.
• Reproduzierbare Production. Versionskontrollierte Skripte statt manueller Klicks.

Wenn Ihr Use-Case mehr als 20, 50 ähnliche Bearbeitungen umfasst, lohnt sich die API-Einrichtung.

Endpunkt-Struktur

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

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

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

Authentifizierung

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

API-Schlüssel abrufen

1. Melden Sie sich unter arteza.ai an
2. Navigieren Sie zu Ihren Kontoeinstellungen
3. Suchen Sie den API-Bereich
4. Generieren Sie einen neuen API-Schlüssel
5. Speichern Sie ihn sicher, behandeln Sie ihn wie ein Passwort

Speichern Sie Ihren API-Schlüssel niemals in der Versionskontrolle. Verwenden Sie Umgebungsvariablen:

export SEEDANCE_API_KEY="your_api_key_here"

Authentifizierungs-Header

Authorization: Bearer your_api_key_here

Request-Struktur

Eine grundlegende Seedream v4.5 Edit-Anfrage sieht folgendermaßen 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"
}

Parameter-Referenz

Bis zu 10 Bild-URLs können übergeben werden. Das Modell behandelt das erste Bild als primär und nachfolgende Bilder als Referenzen.

Beispiel-Request: 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);

Beispiel-Request: 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 Response 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
}

Laden Sie das Bild von der zurückgegebenen URL herunter, Ausgabe-URLs sind 24 Stunden gültig.

Asynchrones Generierungsmuster

Seedream v4.5 Edit benötigt 30, 60 Sekunden pro Request. Für Production möchten Sie wahrscheinlich asynchrone Generierung mit Webhooks oder Polling statt blockierender Requests.

Webhook-basiert asynchron

Übergeben Sie eine webhook_url in Ihrer Anfrage, und Arteza POST die Ergebnisse dorthin, wenn die Generierung abgeschlossen ist:

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

Ihr Webhook-Handler empfängt:

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

Webhook-Handling ist das empfohlene Production-Muster.

Beginnen Sie mit der Entwicklung. Probiere das Tool zunächst aus.

Polling-basiert asynchron

Wenn Ihre Infrastruktur keine Webhooks empfangen kann, fragen Sie den Status ab:

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();

// Poll for completion
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;
}

Fragen Sie alle 5, 10 Sekunden ab. Die Gesamtwartezeit beträgt normalerweise 30, 60 Sekunden.

Production-Muster

Muster 1: Katalog-Batch-Generierung

Führen Sie die API über Ihren Produktkatalog aus, um konsistente Hintergrund-Swaps 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"])

Kombinieren Sie mit einem Webhook-Handler, der Ausgaben auf Ihrem CDN speichert und den Produktdatensatz aktualisiert.

Muster 2: On-Demand-Benutzer-Edits

Ermöglichen Sie Benutzern, Bilder hochzuladen und KI-bearbeitete Ergebnisse on-demand zu erhalten:

1. Benutzer lädt Bild in Ihren Bucket hoch
2. Ihr Backend ruft Seedream v4.5 Edit mit einem benutzerwählbaren Prompt auf
3. Polling oder Webhook erwarten
4. Ergebnis-URL an den Client des Benutzers zurückgeben

Planen Sie ~60 Sekunden Wartezeit pro Bearbeitung in Ihrer UX ein.

Muster 3: CMS-gesteuerte Asset-Pipeline

Wenn Inhalte in Ihrem CMS veröffentlicht werden, generieren Sie automatisch zugehörige Bilder:

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

Dieses Muster eliminiert manuelle Bilderstellung für High-Volume-Veröffentlichung.

Fehlerbehandlung

Häufige Fehler-Responses:

Umgeben Sie API-Aufrufe immer mit try/except und Retry-Logik für 429 und 500 Responses.

Rate Limits

Arteza wendet angemessene Rate Limits auf die API an. Für die meisten Production-Workflows werden Sie diese nicht erreichen, aber für Bulk-Serien von 1.000+ Anfragen implementieren Sie:

• Exponentielles Backoff bei 429 Responses
• Gleichzeitige Request-Limits (beginnen Sie bei 5 parallelen, erhöhen Sie)
• Request-Queueing für vorhersehbaren Durchsatz

Kontaktieren Sie den Support für höhere Rate Limits bei großen Production-Workloads.

Kosten bei API-Volumen

API-Aufrufe kosten gleich wie UI-Aufrufe: 8 Credits ($0.08) pro Bild. Zu Planungszwecken:

• 100 API-Aufrufe = 800 Credits (Starter-Tier, $10)
• 1.000 API-Aufrufe = 8.000 Credits (Pro-Tier, $50)
• 10.000 API-Aufrufe = 80.000 Credits (mehrere Studio-Tiers, ~$650)

Für Volumen über 10.000/Monat kontaktieren Sie das Team für benutzerdefinierte Preise.

Best Practices

1. Verwenden Sie Webhooks in Production. Polling funktioniert, verschwendet aber Ressourcen.
2. Speichern Sie Prompts in der Versionskontrolle. Behandeln Sie Prompts wie Code.
3. Protokollieren Sie alles. Request-IDs, Prompts, Ausgaben, Fehler.
4. Validieren Sie Eingaben vor dem Aufrufen. Ungültige Bild-URLs verschwenden Credits.
5. Überwachen Sie den Credit-Saldo. Alarmieren Sie, wenn Sie unter einen Schwellwert fallen.
6. Testen Sie Prompt-Änderungen in Staging. Validieren Sie auf 3, 5 Bildern, bevor Sie einen vollständigen Batch ausführen.
7. Cachen Sie Ergebnisse. Wenn Eingaben identisch sind, nutzen Sie vorherige Ausgaben erneut.

Weitere Informationen

• Vollständiger Seedream v4.5 Bearbeitungsleitfaden
• Anleitung zur Batch-Bearbeitung
• Preisaufschlüsselung

Erste Schritte

Generieren Sie Ihren API-Schlüssel im Arteza-Dashboard, schnappen Sie sich 50 kostenlose Credits und führen Sie das obige Node.js-Beispiel mit einem Produktfoto aus. Die API erschließt das volle Production-Potenzial von Seedream v4.5 Edit, sobald Sie es eingerichtet haben, ist alles andere Prompt-Engineering. Für praktisches Testen zuerst, öffne das Web-Tool und validieren Sie Ihre Prompts, bevor Sie automatisieren.