SeeDream Bilderzeugungs-API Integrationsanleitung

Dieses Dokument beschreibt die Integration der SeeDream Images Generation API, mit der Sie Bilder von SeeDream anhand benutzerdefinierter Parameter erzeugen können.

Antragsverfahren

Um die API zu nutzen, müssen Sie zunächst die entsprechende Seite der SeeDream Images Generation API besuchen und dort eine Dienstanfrage stellen. Nach dem Aufrufen der Seite klicken Sie auf die Schaltfläche „Acquire“, wie in der Abbildung gezeigt:

Wenn Sie noch nicht eingeloggt oder registriert sind, werden Sie automatisch zur Login-Seite weitergeleitet und zur Registrierung bzw. Anmeldung aufgefordert. Nach dem Login werden Sie automatisch auf die aktuelle Seite zurückgeleitet. Bei der ersten Anwendung wird ein kostenloses Kontingent gewährt, das die Nutzung der API kostenlos ermöglicht.

Grundlegende Nutzung

Zunächst ist es wichtig, die grundsätzliche Vorgehensweise zu verstehen: Sie übermitteln die Eingabewörter prompt, die Aktion action und die Bildgröße size, um ein bearbeitetes Ergebnis zu erhalten. Für den Einstieg setzen Sie das Feld action auf generate. Zudem müssen Sie die Prompt-Wörter angeben. Die konkrete Konfiguration ist wie folgt:

Hier sehen Sie, dass wir die Request-Header, einschließlich:

accept：Das gewünschte Format der Antwort, hier auf application/json eingestellt (JSON-Format).
authorization：Der API-Schlüssel für den Zugriff, der nach der Anwendung direkt aus der Auswahlliste entnommen werden kann.

Zusätzlich sind im Request-Body folgende Felder enthalten:

prompt: Die Eingabewörter.
model: Das zu verwendende Generierungsmodell, Standard ist doubao-seedream-5.0-lite. Es werden unterstützt: doubao-seedream-5.0-lite (neueste), doubao-seedream-4.5, doubao-seedream-4.0, doubao-seedream-3.0-t2i, doubao-seededit-3.0-i2i.
image: Eingabebilder, unterstützt URL oder Base64-kodiert. doubao-seedream-5.0-lite, doubao-seedream-4.5 und doubao-seedream-4.0 unterstützen Einzel- oder Mehrbilder. doubao-seededit-3.0-i2i unterstützt nur Einzelbilder. doubao-seedream-3.0-t2i unterstützt diesen Parameter nicht.
size: Angabe der Ausgabebildgröße, zwei Formen sind möglich – nicht kombinierbar: Methode 1: Bestimmung der Auflösung des generierten Bildes, ergänzt durch natürliche Sprachbeschreibung des Seitenverhältnisses im Prompt. Je nach Modell unterschiedliche Voreinstellungen:
- doubao-seedream-5.0-lite: Unterstützung für 2K/3K/4K
- doubao-seedream-4.5: Unterstützung für 2K/4K
- doubao-seedream-4.0: Unterstützung für 1K/2K/4K
- doubao-seedream-3.0-t2i und doubao-seededit-3.0-i2i: keine Voreinstellungen, nur Methode 2 nutzbar
Methode 2: Angabe der Pixelmaße für Breite und Höhe, Standard 2048x2048. Die Pixelzahl und das Seitenverhältnis variieren je nach Modell (z.B. bei 5.0 / 4.5 liegt die Untergrenze bei 3.686.400 Pixel, bei 4.0 bei 921.600, bei 3.0-t2i / seededit-3.0-i2i zwischen [512x512, 2048x2048]).
seed: Zufallszahl-Seed für die Kontrolle der Zufälligkeit bei der Generierung. Werte im Bereich [-1, 2147483647]. Nur doubao-seedream-3.0-t2i unterstützt diesen Parameter.
sequential_image_generation: Serie von Bildern: Eine Gruppe inhaltlich zusammenhängender Bilder, basierend auf Ihrer Eingabe. Unterstützt bei doubao-seedream-5.0-lite, 4.5, 4.0, Standard ist disabled.
stream: Steuerung, ob Stream-Ausgabe aktiviert wird (true / false). Unterstützt bei doubao-seedream-5.0-lite, 4.5, 4.0, Standard false.
guidance_scale: Grad der Übereinstimmung des Modellergebnisses mit prompt, größere Werte bedeuten stärkere Korrelation. Bereich [1,10]. Standardwerte: 2.5 bei doubao-seedream-3.0-t2i, 5.5 bei doubao-seededit-3.0-i2i, sonst keine Unterstützung.
response_format: Format der Bildausgabe, Standard url, Alternativ b64_json.
watermark: Ob Wasserzeichen im Bild hinzugefügt wird, Standard true.
output_format: Das Ausgabeformat, Unterstützung für jpeg (Standard) und png. Nur bei doubao-seedream-5.0-lite verfügbar.
tools: Die zu aktivierenden Tools, z.B. web_search für Online-Recherche. Nur doubao-seedream-5.0-lite unterstützt.
callback_url: URL für Callback bei Abschluss.

Nachdem Sie die Parameter ausgewählt haben, erscheint auf der rechten Seite der entsprechende Code, z.B.:

Mit Klick auf „Try“ können Sie die API testen. Das Ergebnis sieht wie folgt aus:

{
  "success": true,
  "task_id": "25027ba3-0430-4a1b-91c8-d2297f19ba73",
  "trace_id": "8043a9e9-692f-43b0-82f7-5890f798be38",
  "data": [
    {
      "prompt": "a white siamese cat",
      "size": "2048x2048",
      "image_url": "https://platform.cdn.xhuoapi.ai/seedream/3c060029-69b1-406f-a957-fcd55ddc9386.jpg"
    }
  ]
}

Antwortfelder:

success: Status der Bilderstellung (true / false)
task_id: Eindeutige ID der Aufgabe
trace_id: Nachverfolgungs-ID
data: Ergebnisliste der Bilderzeugung
- image_url: Link zum generierten Bild
- prompt: Eingabewörter
- size: Pixelgröße des generierten Bildes

Sie können das erzeugte Bild anhand des image_url-Links abrufen. Zur Generierung des passenden Programmcodes, z.B. curl, siehe folgendes Beispiel:

curl -X POST 'https://api.xhuoapi.ai/v1/seedream/images' \
-H 'accept: application/json' \
-H 'authorization: Bearer ${token}' \
-H 'content-type: application/json' \
-d '{
  "action": "generate",
  "model": "doubao-seedream-4-0-250828",
  "prompt": "a white siamese cat"
}'

Bildbearbeitung

Möchten Sie ein Bild bearbeiten, muss im Parameter image die URL des Originalbilds angegeben werden:

model: Zum Einsatz kommendes Modell, unterstützend: doubao-seedream-5.0-lite, doubao-seedream-4.5, doubao-seedream-4.0 (Einzel- oder Mehrbild), doubao-seededit-3.0-i2i (nur Einzelbild).
image: Das Bild, das bearbeitet werden soll, eins oder mehrere.

Beispiel:

Programmierbeispiel in Python:

import requests

url = "https://api.xhuoapi.ai/v1/flux/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)

Nach Ausführung erhalten Sie sofort ein Ergebnis, z.B.:

{
    "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.xhuoapi.ai/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
        }
    ]
}

Das Ergebnis zeigt eine bearbeitete Version des Originalbilds.

Asynchrone Callback-Funktion

Da die Bildgenerierung etwa 1-2 Minuten dauert, kann es bei längerer Wartezeit zu Verbindungs-Timeouts kommen. Daher unterstützt die API auch asynchrone Rückmeldungen. Der Ablauf ist:

Client sendet eine Anfrage mit einem callback_url.
API antwortet sofort mit einem task_id.
Nach Abschluss der Bearbeitung wird das Ergebnis im JSON-Format an die callback_url gesendet, inklusive task_id, sodass das Ergebnis anhand dieser ID zugeordnet werden kann.

Beispiel, sofortiges Ergebnis:

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

Callback-Beispiel:

{
    "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.xhuoapi.ai/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
        }
    ]
}

Hier sehen Sie, dass das Ergebnis anhand des task_id verknüpft wird.

Fehlerbehandlung

Bei Fehlern während des API-Aufrufs gibt die API entsprechende Fehlercodes und -nachrichten zurück, z.B.:

400 token_mismatched: Falsche Anfrage, z.B. fehlende oder ungültige Parameter
400 api_not_implemented: Nicht implementierte Funktion
401 invalid_token: Nicht autorisiert, ungültiger oder fehlender Zugriffs-Token
429 too_many_requests: Rate-Limit überschritten
500 api_error: Serverfehler

Beispiel für Fehlerantwort:

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

Zusammenfassung

Dieses Dokument vermittelt die Nutzung der SeeDream Images Generation API, um Bilder anhand von Prompt-Wörtern zu erzeugen. Wir hoffen, dass die Anleitung Ihnen beim erfolgreichen Anschluss und Gebrauch der API hilft. Bei Fragen wenden Sie sich bitte jederzeit an unser technisches Support-Team.

Documentation Index

​Antragsverfahren

​Grundlegende Nutzung

​Bildbearbeitung

​Asynchrone Callback-Funktion

​Fehlerbehandlung

​Beispiel für Fehlerantwort:

​Zusammenfassung