> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.
# SeeDream Bilder Generierung API Integrationsanleitung
> ByteDance Seedream Image Generation API guide - Ace Data Cloud
Dieser Artikel beschreibt eine Integrationsanleitung für die SeeDream Bilder Generierung API, die es ermöglicht, offizielle SeeDream Bilder durch Eingabe benutzerdefinierter Parameter zu generieren.
## Antragsprozess
Um die SeeDream Bilder Generierung API zu nutzen, gehen Sie zuerst zur [Ace Data Cloud Konsole](https://platform.acedata.cloud/console/applications), um Ihr API-Token zu erhalten und für später aufzubewahren.
Wenn Sie noch nicht angemeldet oder registriert sind, werden Sie automatisch zur Anmeldeseite weitergeleitet, die Sie zur Registrierung und Anmeldung einlädt. Nach Abschluss werden Sie automatisch zur aktuellen Seite zurückgeleitet.
**Ein API-Token reicht aus, um alle Dienste der Plattform zu nutzen, es ist nicht erforderlich, für jeden Dienst separat zu beantragen.** Bei der ersten Beantragung erhalten Sie ein kostenloses Kontingent, um es kostenlos auszuprobieren; wenn das Kontingent nicht ausreicht, können Sie im [Konsolenbereich](https://platform.acedata.cloud/console/coin) Ihr Guthaben aufladen.
> 📘 Vollständige Dokumentation: [SeeDream Bilder Generierung API →](https://platform.acedata.cloud/documents/seedream-images)
## Grundlegende Nutzung
Zuerst sollten Sie die grundlegende Nutzung verstehen, indem Sie das Eingabewort `prompt`, die Generierungsaktion `action` und die Bildgröße `size` eingeben, um das bearbeitete Ergebnis zu erhalten. Zuerst müssen Sie ein einfaches `action`-Feld übergeben, dessen Wert `generate` ist. Dann müssen wir auch das Eingabewort eingeben, die genauen Inhalte sind wie folgt:
Hier sehen wir, dass wir die Request-Header festgelegt haben, einschließlich:
* `accept`: In welchem Format Sie die Antwort erhalten möchten, hier eingetragen als `application/json`, also im JSON-Format.
* `authorization`: Der Schlüssel zur API, den Sie nach der Beantragung direkt auswählen können.
Zusätzlich haben wir den Request-Body festgelegt, einschließlich:
* `prompt`: Eingabewort.
* `model`: Generierungsmodell, standardmäßig `doubao-seedream-5-0-260128` (SeeDream 5.0 Lite, die neueste Version). Unterstützt werden `doubao-seedream-5-0-pro-260628`, `doubao-seedream-5-0-260128`, `doubao-seedream-4-5-251128`, `doubao-seedream-4-0-250828`, `doubao-seedream-3-0-t2i-250415`, `doubao-seededit-3-0-i2i-250628`. Dabei ist `doubao-seedream-5-0-pro-260628` (SeeDream 5.0 Pro) das Flaggschiff-Modell für Einzelbilder, das nur Einzelbilder generiert, **unterstützt keine Gruppenbilder (`sequential_image_generation`), Streaming (`stream`) und Online-Suche (`tools`)**. **`model` muss die vollständige Modellbezeichnung übergeben werden (z. B. `doubao-seedream-5-0-260128`), die Übertragung von Abkürzungen wie `doubao-seedream-5.0-lite` führt zu einem 400-Fehler.**
* `image`: Informationen zum eingegebenen Bild, unterstützt URL oder Base64-Codierung. Dabei unterstützt `doubao-seedream-5-0-pro-260628` Einzel- oder Mehrfachbilderingaben (Mehrfachbilder 2-10 Stück, ab dem 2. Bild wird nach Stück abgerechnet), `doubao-seedream-5-0-260128`, `doubao-seedream-4-5-251128`, `doubao-seedream-4-0-250828` unterstützen Einzel- oder Mehrfachbilder, `doubao-seededit-3-0-i2i-250628` unterstützt nur Einzelbilder, `doubao-seedream-3-0-t2i-250415` unterstützt diesen Parameter nicht.
* `size`: Gibt die Größeninformationen des zu generierenden Bildes an, unterstützt die folgenden zwei Methoden, die nicht gemischt werden können. Methode 1 | Gibt die Auflösung des zu generierenden Bildes an und beschreibt das Seitenverhältnis in natürlicher Sprache im Prompt. **Die unterstützten Voreinstellungen variieren je nach Modell**: `doubao-seedream-5-0-pro-260628` unterstützt `1K`/`2K`; `doubao-seedream-5-0-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`; `doubao-seedream-3-0-t2i-250415` und `doubao-seededit-3-0-i2i-250628` **unterstützen keine Voreinstellungen**, akzeptieren nur Methode 2. Methode 2 | Gibt die Breiten- und Höhenpixelwerte des zu generierenden Bildes an: Standard `2048x2048`, die Gesamtpixelanzahl und das Seitenverhältnis variieren je nach Modell (z. B. Gesamtpixelbereich für 5.0 Pro \[921600, 4194304], 5.0 Lite / 4.5 untere Grenze 3.686.400, 4.0 untere Grenze 921.600, 3.0-t2i / seededit-3.0-i2i Bereich \[512x512, 2048x2048]).
* `seed`: Zufallszahlensamen, um die Zufälligkeit des vom Modell generierten Inhalts zu steuern. Der Wertebereich liegt zwischen \[-1, 2147483647]. **Nur `doubao-seedream-3-0-t2i-250415` unterstützt diesen Parameter**.
* `sequential_image_generation`: Gruppenbilder: Basierend auf Ihrem eingegebenen Inhalt wird eine Gruppe von inhaltlich verwandten Bildern generiert. `doubao-seedream-5-0-260128`, `doubao-seedream-4-5-251128`, `doubao-seedream-4-0-250828` unterstützen diesen Parameter, standardmäßig `deaktiviert`.
* `stream`: Steuert, ob der Streaming-Ausgabemodus aktiviert ist. `doubao-seedream-5-0-260128`, `doubao-seedream-4-5-251128`, `doubao-seedream-4-0-250828` unterstützen diesen Parameter, standardmäßig ist er `false`.
* `guidance_scale`: Der Grad der Übereinstimmung der Modellausgabe mit dem Prompt, je größer der Wert, desto stärker die Relevanz. Der Wertebereich liegt zwischen \[1, 10]. `doubao-seedream-3-0-t2i-250415` hat den Standardwert 2.5, `doubao-seededit-3-0-i2i-250628` hat den Standardwert 5.5, andere Modelle unterstützen dies nicht.
* `response_format`: Gibt das Rückgabeformat des generierten Bildes an. Standard ist `url`, es wird auch `b64_json` unterstützt.
* `watermark`: Ob ein Wasserzeichen im generierten Bild hinzugefügt werden soll. Standard ist `true`.
* `output_format`: Gibt das Dateiformat des generierten Bildes an, unterstützt `jpeg` (Standard) und `png`. Nur `doubao-seedream-5-0-pro-260628` und `doubao-seedream-5-0-260128` unterstützen dies.
* `tools`: Konfiguriert die Werkzeuge, die das Modell aufrufen soll, derzeit wird `web_search` (Online-Suche) unterstützt. Nur `doubao-seedream-5-0-260128` unterstützt dies.
* `callback_url`: Die URL, an die die Ergebnisse zurückgerufen werden sollen.
* `async`: Ob die Verarbeitung im asynchronen Modus erfolgen soll. Wenn auf `true` gesetzt, gibt die Schnittstelle sofort `task_id` zurück, ohne dass `callback_url` bereitgestellt werden muss, und die Ergebnisse können anschließend über `/seedream/tasks` abgefragt werden.
Nach der Auswahl können Sie feststellen, dass auf der rechten Seite auch der entsprechende Code generiert wurde, wie im Bild gezeigt:
Klicken Sie auf die Schaltfläche „Try“, um einen Test durchzuführen, wie im obigen Bild gezeigt, hier haben wir das folgende Ergebnis erhalten:
```json theme={null}
{
"success": true,
"task_id": "81246f86-05ff-4d7d-9553-1013e0c1cd32",
"trace_id": "ab50a78d-ab1f-457f-a46b-c2259cd5d35b",
"data": [
{
"prompt": "Ein fotorealistisches Studio-Produktfoto einer parfümflasche aus frosted Glas auf nassem schwarzem Schiefer, einzelnes Softbox-Hauptlicht, Wassertropfen, dunkler stimmungsreicher Hintergrund, 85mm Makro.",
"size": "2048x2048",
"image_url": "https://platform2.cdn.acedata.cloud/seedream/901c6af6-e83a-4849-b233-295f6c20bacb.jpg"
}
]
}
```
Die Rückgabe enthält mehrere Felder, die wie folgt beschrieben werden:
* `success`, der Status des Videoerzeugungsauftrags zu diesem Zeitpunkt.
* `task_id`, die ID des Videoerzeugungsauftrags zu diesem Zeitpunkt.
* `trace_id`, die Verfolgungs-ID des Videoerzeugungsauftrags zu diesem Zeitpunkt.
* `data`, die Ergebnisliste des Bildgenerierungsauftrags zu diesem Zeitpunkt.
* `image_url`, der Link zum Bildgenerierungsauftrag zu diesem Zeitpunkt.
* `prompt`, der Hinweistext.
* `size`: Die Pixelgröße des generierten Bildes.
Wir können sehen, dass wir zufriedenstellende Bildinformationen erhalten haben, und wir müssen nur den Link zur `data`-Bildadresse abrufen, um das generierte SeeDream-Bild zu erhalten.
Wenn Sie den entsprechenden Code zur Integration generieren möchten, können Sie ihn direkt kopieren, zum Beispiel der CURL-Code wie folgt:
```shell theme={null}
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-260128",
"prompt": "Ein fotorealistisches Studio-Produktfoto einer parfümflasche aus frosted Glas auf nassem schwarzem Schiefer, einzelnes Softbox-Hauptlicht, Wassertropfen, dunkler stimmungsreicher Hintergrund, 85mm Makro."
}'
```
## Bildbearbeitungsauftrag
Wenn Sie ein Bild bearbeiten möchten, muss zunächst der Parameter `image` die zu bearbeitende Bildadresse übergeben werden.
* model: Das Modell, das für diesen Bildbearbeitungsauftrag verwendet wird, `doubao-seedream-5-0-260128`, `doubao-seedream-4-5-251128`, `doubao-seedream-4-0-250828` unterstützen die Eingabe von einem oder mehreren Bildern, `doubao-seededit-3-0-i2i-250628` unterstützt nur die Eingabe eines einzelnen Bildes.
* image: Hochladen des zu bearbeitenden Bildes, eines oder mehrerer.
Ein Beispiel für die Eingabe sieht wie folgt aus:
Der entsprechende Code:
```python theme={null}
import requests
url = "https://api.acedata.cloud/flux/images"
headers = {
"accept": "application/json",
"authorization": "Bearer {token}",
"content-type": "application/json"
}
payload = {
"model": "doubao-seedream-4-0-250828",
"prompt": "Behalten Sie die Pose des Modells und die fließende Form des flüssigen Kleidungsstücks unverändert. Ändern Sie das Kleidungsmaterial von silbernem Metall zu vollständig transparentem Wasser (oder Glas). Durch den Flüssigkeitsfluss sind die Details der Haut des Modells sichtbar. Der Licht- und Schatteneffekt wechselt von Reflexion zu Brechung.",
"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)
```
Wenn Sie auf Ausführen klicken, können Sie sofort ein Ergebnis erhalten, wie folgt:
```json theme={null}
{
"success": true,
"task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde",
"trace_id": "131a40c3-2eaf-44c9-af28-c9b408577286",
"data": [
{
"prompt": "Behalten Sie die Pose des Modells und die fließende Form des flüssigen Kleidungsstücks unverändert. Ändern Sie das Kleidungsmaterial von silbernem Metall zu vollständig transparentem Wasser (oder Glas). Durch den Flüssigkeitsfluss sind die Details der Haut des Modells sichtbar. Der Licht- und Schatteneffekt wechselt von Reflexion zu Brechung.",
"size": "2048x2048",
"image_url": "https://platform.cdn.acedata.cloud/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
}
]
}
```
Wir können sehen, dass der generierte Effekt eine Bearbeitung des Originalbildes ist, das Ergebnis ist ähnlich wie oben.
## Asynchrone Rückrufe
Da die SeeDream Images Generation API eine relativ lange Generierungszeit benötigt, etwa 1-2 Minuten, wird die HTTP-Anfrage bei langer Nichtreaktion der API die Verbindung aufrechterhalten, was zu einem zusätzlichen Systemressourcenverbrauch führt. Daher bietet diese API auch Unterstützung für asynchrone Rückrufe.
Der gesamte Prozess ist: Wenn der Client die Anfrage stellt, gibt er zusätzlich ein `callback_url`-Feld an. Nachdem der Client die API-Anfrage gestellt hat, gibt die API sofort ein Ergebnis zurück, das ein `task_id`-Feld enthält, das die aktuelle Aufgaben-ID darstellt. Wenn die Aufgabe abgeschlossen ist, werden die Ergebnisse des generierten Bildes in Form von POST JSON an die vom Client angegebene `callback_url` gesendet, wobei auch das `task_id`-Feld enthalten ist, sodass die Aufgabenergebnisse über die ID verknüpft werden können.
Wenn Sie keine öffentliche Adresse für Rückrufe haben, können Sie auch `callback_url` nicht angeben, sondern das `async`-Feld in der Anfrage auf `true` setzen. In diesem Fall gibt die Schnittstelle ebenfalls sofort `task_id` zurück, aber es werden keine Ergebnisse gepusht. Sie müssen die `task_id` verwenden, um die `/seedream/tasks`-Schnittstelle abzufragen, um den endgültigen Status zu erhalten.
Lassen Sie uns durch ein Beispiel verstehen, wie dies konkret funktioniert.
Wenn Sie auf Ausführen klicken, können Sie sofort ein Ergebnis erhalten, wie folgt:
```
{
"task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde"
}
```
Der Inhalt lautet:
```json theme={null}
{
"success": true,
"task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde",
"trace_id": "131a40c3-2eaf-44c9-af28-c9b408577286",
"data": [
{
"prompt": "Behalten Sie die Pose des Modells und die fließende Form des flüssigen Kleidungsstücks unverändert. Ändern Sie das Kleidungsmaterial von silbernem Metall zu vollständig transparentem Wasser (oder Glas). Durch den Flüssigkeitsfluss sind die Details der Haut des Modells sichtbar. Der Licht- und Schatteneffekt wechselt von Reflexion zu Brechung.",
"size": "2048x2048",
"image_url": "https://platform.cdn.acedata.cloud/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
}
]
}
```
Wir können sehen, dass im Ergebnis ein `task_id`-Feld vorhanden ist, und die anderen Felder sind ähnlich wie oben, sodass die Aufgabe über dieses Feld verknüpft werden kann.
## Fehlerbehandlung
Wenn beim Aufruf der API ein Fehler auftritt, gibt die API den entsprechenden Fehlercode und die 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`: Unbefugt, ungültiger oder fehlender Autorisierungstoken.
* `429 too_many_requests`: Zu viele Anfragen, Sie haben das Kontingent überschritten.
* `500 api_error`: Interner Serverfehler, etwas ist auf dem Server schiefgelaufen.
### Beispiel für eine Fehlerantwort
```json theme={null}
{
"success": false,
"error": {
"code": "api_error",
"message": "Abruf fehlgeschlagen"
},
"trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```
## Fazit
Durch dieses Dokument haben Sie erfahren, wie Sie die SeeDream Images Generation API nutzen können, um Bilder durch Eingabe von Stichwörtern zu generieren. Wir hoffen, dass Ihnen dieses Dokument hilft, die API besser zu integrieren und zu nutzen. Bei Fragen wenden Sie sich bitte jederzeit an unser technisches Support-Team.