Anleitung zur Integration der SeeDream Images Generation API

Dieser Artikel stellt eine Anleitung zur Integration der SeeDream Images Generation API vor, mit der durch die Eingabe benutzerdefinierter Parameter offizielle Bilder von SeeDream generiert werden können.

Antragsprozess

Um die SeeDream Images Generation API zu verwenden, rufen Sie zunächst die Ace Data Cloud-Konsole auf, um Ihren API-Token zu erhalten und ihn als Reserve aufzubewahren.

Falls Sie noch nicht angemeldet oder registriert sind, werden Sie automatisch zur Anmeldeseite weitergeleitet, um sich zu registrieren und anzumelden. Nach Abschluss kehren Sie automatisch zur aktuellen Seite zurück. Ein API-Token kann alle Dienste der Plattform aufrufen, ohne dass für jeden Dienst ein separater Antrag erforderlich ist. Beim ersten Antrag erhalten Sie ein kostenloses Kontingent, das Sie kostenlos testen können; bei unzureichendem Kontingent können Sie in der Konsole ein allgemeines Guthaben aufladen.

📘 Vollständige Dokumentation: SeeDream Images Generation API →

Grundlegende Verwendung

Lernen wir zunächst die grundlegende Verwendung kennen: Geben Sie einfach den Prompt prompt, die Generierungsaktion action und die Bildgröße size ein, um das verarbeitete Ergebnis zu erhalten. Zuerst müssen Sie einfach ein Feld action übergeben, dessen Wert generate ist, und dann müssen wir auch den Prompt eingeben. Der konkrete Inhalt lautet wie folgt:

Hier sehen wir, dass wir die Request Headers festgelegt haben, einschließlich:

accept: Welches Format das empfangene Antwortergebnis haben soll; hier wird application/json eingetragen, also das JSON-Format.
authorization: Der Schlüssel zum Aufrufen der API, der nach dem Antrag direkt über ein Dropdown-Menü ausgewählt werden kann.

Außerdem wurde der Request Body festgelegt, einschließlich:

prompt: Prompt.
model: Generierungsmodell, standardmäßig doubao-seedream-5-0-lite-260128 (SeeDream 5.0 Lite, neueste Version). Unterstützt werden doubao-seedream-5-0-pro-260628, doubao-seedream-5-0-lite-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828. Dabei ist doubao-seedream-5-0-pro-260628 (SeeDream 5.0 Pro) das Flaggschiffmodell für Einzelbilder und generiert nur Einzelbilder, unterstützt keine Bildgruppen (sequential_image_generation), Streaming (stream) und Websuche (tools). Für model muss die vollständige Modellzeichenfolge übergeben werden (z. B. doubao-seedream-5-0-lite-260128); Kurzformen wie doubao-seedream-5.0-lite führen zu einem 400-Fehler.
image: Informationen zum Eingabebild, unterstützt URL oder Base64-Kodierung. doubao-seedream-5-0-pro-260628 unterstützt die Eingabe eines oder mehrerer Bilder (maximal 10), doubao-seedream-5-0-lite-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828 unterstützen die Eingabe eines oder mehrerer Bilder.
size: Legt die Größeninformationen des generierten Bildes fest und unterstützt die folgenden zwei Methoden, die nicht gemischt werden dürfen. Methode 1 | Legt die Auflösung des generierten Bildes fest und beschreibt das Seitenverhältnis des Bildes in natürlicher Sprache im Prompt. Die von den einzelnen Modellen unterstützten Voreinstellungen unterscheiden sich: doubao-seedream-5-0-pro-260628 unterstützt 1K/1.5K/2K; doubao-seedream-5-0-lite-260128 unterstützt 2K/3K/4K; doubao-seedream-4-5-251128 unterstützt nur 2K/4K; doubao-seedream-4-0-250828 unterstützt 1K/2K/4K. Methode 2 | Legt die Pixelwerte für Breite und Höhe des generierten Bildes fest: Standard ist 2048x2048, der Gesamtpixelwert und der Wertebereich des Seitenverhältnisses unterscheiden sich je nach Modell (zum Beispiel beträgt der Gesamtpixelbereich von 5.0 Pro [921600, 4624220], die untere Grenze der Gesamtpixel von 5.0 Lite / 4.5 liegt bei 3.686.400, die von 4.0 bei 921.600).
sequential_image_generation: Bildgruppe: Eine Gruppe inhaltlich zusammenhängender Bilder, die basierend auf den von Ihnen eingegebenen Inhalten generiert wird. doubao-seedream-5-0-lite-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828 unterstützen diesen Parameter, standardmäßig disabled.
stream: Steuert, ob der Streaming-Ausgabemodus aktiviert wird. doubao-seedream-5-0-lite-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828 unterstützen diesen Parameter, standardmäßig ist er false.
response_format: Legt das Rückgabeformat des generierten Bildes fest. Standardmäßig ist es url, b64_json wird ebenfalls unterstützt.
watermark: Ob dem generierten Bild ein Wasserzeichen hinzugefügt wird. Standardmäßig ist dies true.
output_format: Legt das Dateiformat des generierten Bildes fest, unterstützt jpeg (Standard) und png. Wird nur von doubao-seedream-5-0-pro-260628 und doubao-seedream-5-0-lite-260128 unterstützt.
tools: Konfiguriert die vom Modell aufzurufenden Tools, derzeit wird web_search (Websuche) unterstützt. Wird nur von Seedream 5.0 Lite unterstützt.
optimize_prompt_options: Konfiguration der Prompt-Optimierung. 5.0 Pro unterstützt standard/fast; 5.0 Lite und 4.5 unterstützen nur standard; 4.0 unterstützt standard/fast.
background: Wird nur von der Einzelbildbearbeitung von 5.0 Pro unterstützt. transparent erfordert die Eingabe einer PNG-Datei mit Transparenzkanal, und output_format muss png sein; opaque steht für einen gewöhnlichen undurchsichtigen Hintergrund.
layer_decomposition: Wird nur von 5.0 Pro unterstützt. Bei Einstellung auf true muss ein PNG/JPEG eingegeben werden; es kann ohne prompt automatisch zerlegt werden, oder Elemente können mit natürlicher Sprache/<bbox> angegeben werden; size unterstützt auto/1K/1.5K/2K. Dieser Modus kann nicht zusammen mit Bildgruppen, Streaming, Websuche oder background verwendet werden.
callback_url: Die URL, an die das Ergebnis zurückgemeldet werden soll.
async: Ob im asynchronen Modus verarbeitet wird. Bei Einstellung auf true gibt die Schnittstelle sofort task_id zurück, ohne dass callback_url bereitgestellt werden muss; anschließend wird das Ergebnis über /seedream/tasks per Polling abgerufen.

Nach der Auswahl können Sie feststellen, dass auf der rechten Seite auch entsprechender Code generiert wurde, wie in der Abbildung gezeigt:

Klicken Sie auf die Schaltfläche „Try“, um einen Test durchzuführen. Wie in der obigen Abbildung gezeigt, erhalten wir hier das folgende Ergebnis:

{
  "success": true,
  "task_id": "80ceeed1-17d4-4eb7-82e0-18b34290f36e",
  "trace_id": "96b7fdc8-0fc8-4e2e-82a9-83c0a82f0a08",
  "data": [
    {
      "prompt": "A single matte blue cube centered on a clean white studio background, neutral lighting",
      "size": "2048x2048",
      "image_url": "https://cdn.acedata.cloud/assets/examples/seedream/db93b46e-c302-4676-8a11-63f0ba638a27-1c6f66f6b7e8.jpg"
    }
  ]
}

Das zurückgegebene Ergebnis enthält mehrere Felder, die wie folgt beschrieben werden:

success, der Status der Videogenerierungsaufgabe zu diesem Zeitpunkt.
task_id, die ID der Videogenerierungsaufgabe zu diesem Zeitpunkt.
trace_id, die Tracking-ID der Videogenerierung zu diesem Zeitpunkt.
data, die Ergebnisliste der Bildgenerierungsaufgabe zu diesem Zeitpunkt.
- image_url, der Link der Bildgenerierungsaufgabe zu diesem Zeitpunkt.
- prompt, der Prompt.
- size: die Pixel des generierten Bildes

Es ist ersichtlich, dass wir zufriedenstellende Bildinformationen erhalten haben. Wir müssen nur die SeeDream-Bilder über die Bildlink-Adresse in data im Ergebnis abrufen. Wenn Sie außerdem den entsprechenden Integrationscode generieren möchten, können Sie ihn direkt kopieren und generieren, beispielsweise lautet der CURL-Code wie folgt:

curl -X POST 'https://api.acedata.cloud/seedream/images' \
-H 'accept: application/json' \
-H 'authorization: Bearer ${token}' \
-H 'content-type: application/json' \
-d '{
  "action": "generate",
  "model": "doubao-seedream-5-0-lite-260128",
  "prompt": "A single matte blue cube centered on a clean white studio background, neutral lighting"
}'

Bildbearbeitungsaufgabe

Wenn Sie ein bestimmtes Bild bearbeiten möchten, muss zunächst für den Parameter image der Link des zu bearbeitenden Bildes übergeben werden.

model: Das für diese Bildbearbeitungsaufgabe verwendete Modell; doubao-seedream-5-0-pro-260628, doubao-seedream-5-0-lite-260128, doubao-seedream-4-5-251128 und doubao-seedream-4-0-250828 unterstützen alle Bildeingaben.
image: Das hochzuladende zu bearbeitende Bild, ein oder mehrere Bilder

Ein Ausfüllbeispiel lautet wie folgt:

Der entsprechende Code:

import requests

url = "https://api.acedata.cloud/seedream/images"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "doubao-seedream-4-0-250828",
  "prompt": "Keep the model pose and the liquid garment flowing shape unchanged. Change the clothing material from silver metal to completely transparent water (or glass). Through the liquid flow, the details of the model skin are visible. The light and shadow effect shifts from reflection to refraction.",
  "image": ["https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_5_imageToimage.png"],
  "size": "2K",
  "watermark": False
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Klicken Sie auf „Ausführen“, und Sie werden feststellen, dass Sie sofort ein Ergebnis erhalten, wie folgt:

{
  "success": true,
  "task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde",
  "trace_id": "131a40c3-2eaf-44c9-af28-c9b408577286",
  "data": [
    {
      "prompt": "Keep the model pose and the liquid garment flowing shape unchanged. Change the clothing material from silver metal to completely transparent water (or glass). Through the liquid flow, the details of the model skin are visible. The light and shadow effect shifts from reflection to refraction.",
      "size": "2048x2048",
      "image_url": "https://platform.cdn.acedata.cloud/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
    }
  ]
}

Es ist ersichtlich, dass der generierte Effekt die Bearbeitung des Originalbildes darstellt und das Ergebnis dem oben beschriebenen ähnelt.

Ebenenaufteilung (Seedream 5.0 Pro)

Die Ebenenaufteilung zerlegt ein Eingabebild in 1 Hintergrundbild und bis zu 16 unabhängig bearbeitbare transparente PNG-Ebenen. Die folgende Anfrage lässt das Modell die Hauptelemente automatisch erkennen; falls Elemente angegeben werden sollen, kann prompt ergänzt werden, und im Prompt können auch normalisierte <bbox>-Koordinaten verwendet werden.

curl -X POST 'https://api.acedata.cloud/seedream/images' \
-H 'accept: application/json' \
-H 'authorization: Bearer ${token}' \
-H 'content-type: application/json' \
-d '{
  "model": "doubao-seedream-5-0-pro-260628",
  "image": "https://example.com/poster.png",
  "layer_decomposition": true,
  "size": "2K",
  "watermark": false
}'

Das zurückgegebene data ist nach z_index von unten nach oben angeordnet. Der z_index des Hintergrundbildes ist 0; Ebenen enthalten außerdem name, description und bounding_box.absolute/normalized. Bei der Neuzusammensetzung mit absoluten Koordinaten skalieren Sie die Ebenen auf [right-left, bottom-top], platzieren Sie sie bei [left, top] und stapeln Sie sie dann in aufsteigender Reihenfolge von z_index. Falls die Generierung einer beliebigen Ebene fehlschlägt, schlägt die gesamte Aufteilung fehl.

Streaming-Ausgabe

Wenn Lite/4.x auf stream: true gesetzt ist, verwenden Sie für den Anfrage-Header accept: application/x-ndjson. Die Schnittstelle gibt zeilenweise image_generation.partial_succeeded oder image_generation.partial_failed zurück und liefert abschließend das einzige Ereignis image_generation.completed sowie das endgültige usage; nur das Abschlussereignis löst einmalig eine Abrechnung aus. Der Streaming-Modus kann nicht zusammen mit async oder callback_url verwendet werden.

Asynchroner Rückruf

Da die von der SeeDream Images Generation API benötigte Generierungszeit relativ lang ist und ungefähr 1–2 Minuten beträgt, bleibt die HTTP-Anfrage bei einer länger ausbleibenden API-Antwort stets verbunden, was zu zusätzlichem Verbrauch von Systemressourcen führt. Daher bietet diese API auch Unterstützung für asynchrone Rückrufe. Der gesamte Ablauf ist: Wenn der Client eine Anfrage initiiert, gibt er zusätzlich ein Feld callback_url an. Nachdem der Client eine API-Anfrage initiiert hat, gibt die API sofort ein Ergebnis zurück, das Feldinformationen zu einer task_id enthält, welche die ID der aktuellen Aufgabe darstellt. Nachdem die Aufgabe abgeschlossen ist, wird das Ergebnis der Bildgenerierung in Form von POST JSON an die vom Client angegebene callback_url gesendet, die ebenfalls das Feld task_id enthält, sodass das Aufgabenergebnis über die ID zugeordnet werden kann. Wenn Sie keine öffentliche Adresse für Rückrufe haben, können Sie auch keine callback_url angeben und stattdessen das Feld async in der Anfrage auf true setzen. In diesem Fall gibt die Schnittstelle ebenfalls sofort die task_id zurück, überträgt jedoch kein Ergebnis. Sie müssen diese task_id mitführen und die Schnittstelle /seedream/tasks aufrufen, um den Aufgabenstatus per Polling abzufragen und das endgültige Ergebnis zu erhalten. Im Folgenden erfahren wir anhand eines Beispiels, wie der konkrete Vorgang durchgeführt wird. Klicken Sie auf „Ausführen“, und Sie werden feststellen, dass Sie sofort ein Ergebnis erhalten, wie folgt:

{
  "task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde"
}

Der Inhalt lautet wie folgt:

{
    "success": true,
    "task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde",
    "trace_id": "131a40c3-2eaf-44c9-af28-c9b408577286",
    "data": [
        {
            "prompt": "Keep the model pose and the liquid garment flowing shape unchanged. Change the clothing material from silver metal to completely transparent water (or glass). Through the liquid flow, the details of the model skin are visible. The light and shadow effect shifts from reflection to refraction.",
            "size": "2048x2048",
            "image_url": "https://platform.cdn.acedata.cloud/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
        }
    ]
}

Man kann sehen, dass es im Ergebnis ein Feld task_id gibt. Die anderen Felder sind ähnlich wie oben. Über dieses Feld kann die Zuordnung der Aufgabe realisiert werden.

Fehlerbehandlung

Wenn beim Aufrufen der API ein Fehler auftritt, gibt die API den entsprechenden Fehlercode und die entsprechenden Informationen zurück. Zum Beispiel:

400 token_mismatched: Ungültige Anfrage, möglicherweise aufgrund fehlender oder ungültiger Parameter.
400 api_not_implemented: Ungültige Anfrage, möglicherweise aufgrund fehlender oder ungültiger Parameter.
401 invalid_token: Nicht autorisiert, ungültiges oder fehlendes Autorisierungstoken.
429 too_many_requests: Zu viele Anfragen, Sie haben das Ratenlimit überschritten.
500 api_error: Interner Serverfehler, auf dem Server ist etwas schiefgelaufen.

Beispiel für eine Fehlerantwort

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Fazit

Durch dieses Dokument haben Sie bereits verstanden, wie Sie die SeeDream Images Generation API verwenden können, um durch die Eingabe von Prompt-Wörtern Bilder zu generieren. Wir hoffen, dass dieses Dokument Ihnen dabei helfen kann, diese API besser anzubinden und zu verwenden. Wenn Sie Fragen haben, kontaktieren Sie jederzeit unser technisches Supportteam.

Erste Schritte

KI Chat

KI Bild

KI Video

KI Audio

Web & Daten

CAPTCHA

Identität

Coding

Weitere Anleitungen

Anleitung zur Integration der SeeDream Images Generation API

Antragsprozess

Grundlegende Verwendung

Bildbearbeitungsaufgabe

Ebenenaufteilung (Seedream 5.0 Pro)

Streaming-Ausgabe

Asynchroner Rückruf

Fehlerbehandlung

Beispiel für eine Fehlerantwort

Fazit

​Antragsprozess

​Grundlegende Verwendung

​Bildbearbeitungsaufgabe

​Ebenenaufteilung (Seedream 5.0 Pro)

​Streaming-Ausgabe

​Asynchroner Rückruf

​Fehlerbehandlung

​Beispiel für eine Fehlerantwort

​Fazit

Antragsprozess

Grundlegende Verwendung

Bildbearbeitungsaufgabe

Ebenenaufteilung (Seedream 5.0 Pro)

Streaming-Ausgabe

Asynchroner Rückruf

Fehlerbehandlung

Beispiel für eine Fehlerantwort

Fazit