So nutzt du die Seedream 5.0 Pro Bild-API

Du kannst Seedream 5.0 Pro mit einer POST-Anfrage, einem API-Schlüssel und einem Folgeschritt zum Laufen bringen: übermittle den Job, erhalte eine task_id und prüfe dann den Status, bis das Bild fertig ist. Wenn du diesen zweiten Schritt auslässt, bekommst du die finale Datei nicht.

Hier die Kurzfassung:

• Ich sende Anfragen an https://api.apimart.ai/v1/images/generations
• Ich füge Authorization: Bearer YOUR_API_KEY hinzu
• Ich setze model auf doubao-seedream-5-0-pro
• Ich füge prompt, size und n ein
• Ich verwende Text-zu-Bild für neue Bildideen
• Ich verwende Bild-zu-Bild, wenn ich möchte, dass die Ausgabe näher an einem oder mehreren Referenzbildern bleibt
• Ich speichere Bild-URLs schnell, denn sie laufen nach 24 Stunden ab
• Ich verwende asynchrone Jobs für langsame Ausgaben wie 3K-Bilder, die etwa 35 bis 50 Sekunden dauern können
• Ich achte auf die Kosten, da die Preise bei etwa 0,0320 $ pro Bild liegen

Das Wichtigste, das ich mir merken würde: Halte den Schlüssel auf dem Server, übergib n als Zahl und verwende Polling oder einen Webhook für längere Jobs.

Ein paar Details zählen mehr, als sie scheinen. Zum Beispiel bedeutet 401 oft, dass der Schlüssel fehlt oder das Bearer-Format falsch ist. 403 bedeutet oft, dass der Schlüssel funktioniert, aber das Konto das Modell nicht nutzen kann oder ein niedriges Guthaben hat. Und wenn ich Base64-Ausgabe verwende, muss ich den data:image/...;base64,-Präfix selbst hinzufügen, bevor ich es in einem Browser anzeige.

Kurzvergleich

Kurz gesagt: Diese Anleitung zeigt, wie ich die Authentifizierung einrichten, den Anfragekörper aufbauen, zwischen T2I und I2I wählen, asynchrone Jobs abwickeln und das Ergebnis speichern würde, ohne Dateien zu verlieren oder Ausgaben zu verschwenden.

2. API-Zugang und Authentifizierung einrichten

2.1 Erstelle dein APIMart-Konto und generiere einen API-Schlüssel

Gehe auf die APIMart-Website und melde dich für ein neues Konto an ^[8]. Öffne dann die API-Schlüssel-Verwaltungsseite in deinem Dashboard und generiere einen API-Schlüssel ^[1][5].

Kopiere diesen Schlüssel sofort und speichere ihn serverseitig. Ein Secret-Manager oder eine Umgebungsvariable ist der sicherste Ort dafür.

Setze deinen API-Schlüssel niemals in Frontend-Code oder ein öffentliches Repository. Wenn jemand diesen Schlüssel bekommt, kann er dein Konto nutzen. In Node.js speicherst du ihn mit process.env.API_KEY. In einer Shell-Umgebung verwende export API_KEY="your-key-here" ^[1][6].

Bevor du den vollständigen Anfrageablauf baust, sende eine kleine POST-Anfrage, um sicherzustellen, dass der Zugang funktioniert ^[1][2]. Wenn du eine 200 OK-Antwort erhältst, sind dein Schlüssel und deine Berechtigungen korrekt eingerichtet.

Danach kannst du zu den Anfragefeldern übergehen, einschließlich Modell und Prompt.

2.2 Basis-URL und Bearer-Authentifizierungs-Header setzen

Sobald du den T2I- oder I2I-Modus gewählt hast und deinen Schlüssel bereit hältst, musst du die Authentifizierung einrichten, bevor irgendeine Bildanfrage funktioniert. Sende diese Header mit jeder Anfrage:

Der Bearer-Präfix zählt. Lasse ihn weg, und die Anfrage schlägt fehl ^[2][5]. Verwende außerdem genau ein Leerzeichen nach Bearer.

HTTP-Statuscodes helfen dir, Auth-Probleme schnell zu erkennen ^[1][10]. Ein 401 Unauthorized-Fehler bedeutet in der Regel, dass der Schlüssel fehlt, ungültig ist oder der Bearer-Präfix nicht enthalten war ^[1][10]. Ein 403 Forbidden-Fehler bedeutet in der Regel, dass der Schlüssel selbst gültig ist, aber das Konto keinen Modellzugriff oder nicht genügend Guthaben hat ^[1][10].

Ein guter Weg, das zu prüfen, ist, zuerst mit cURL zu testen. Wenn cURL funktioniert, deine App aber nicht, liegt der Fehler wahrscheinlich im Anfragecode deiner App ^[2][6].

Mit gesetzter Authentifizierung ist der nächste Schritt, den Bildanfragekörper aufzubauen.

3. Eine Seedream 5.0 Pro-Bildanfrage aufbauen

3.1 Erforderliche Felder: Modell, Prompt, Größe und Bildanzahl

Mit eingerichteter Authentifizierung ist der nächste Schritt, den JSON-Körper aufzubauen.

Ein gültiger Anfragekörper braucht vier Felder: model, prompt, size und n.

Für Seedream 5.0 Pro setze model auf doubao-seedream-5-0-pro ^[1]. Das Feld prompt akzeptiert eine natürlichsprachliche Beschreibung und unterstützt bis zu 5.000 Zeichen ^[2]. Das Feld size steuert die Ausgabeabmessungen oder das Seitenverhältnis. Gängige Werte sind 1024x1024, 2K und Seitenverhältnisse wie 1:1 oder 16:9 ^[1][2]. Das Feld n legt fest, wie viele Bilder generiert werden, in der Regel von 1 bis 15 ^[1][6].

Ein kleines Detail kann Leute stolpern lassen: n muss eine Ganzzahl sein, kein String. Wenn du "1" statt 1 übergibst, gibt die API einen Validierungsfehler zurück ^[1][5].

3.2 Optionale Felder: Referenzbilder, Websuche und asynchrone Jobs

image_urls ist das wichtigste Feld für den Bild-zu-Bild-Modus. Verwende es, um bis zu 14 Referenzbilder als URLs oder Base64-Daten-URIs zu senden. Jedes Bild muss unter 10 MB liegen und ein Seitenverhältnis zwischen 1:3 und 3:1 verwenden ^[1]. Wenn du Base64 verwendest, füge den vollständigen Data-URI-Präfix ein – data:image/jpeg;base64, – oder die Anfrage schlägt fehl ^[1][5].

web_search kann bei faktischen oder Echtzeit-Prompts helfen, etwa bei aktuellen Ereignissen oder Markenlogos ^[4][7]. Für die meisten Standard-Bildgenerierungen brauchst du es nicht.

Für asynchrone oder Batch-Jobs akzeptiert callback_url einen öffentlichen HTTPS-Endpunkt, an den APIMart die Payload zum Aufgabenabschluss per POST sendet ^[2].

3.3 Beispiel-API-Aufrufe in cURL und JavaScript

Hier ist eine minimale funktionierende cURL-Anfrage für ein einzelnes 1024×1024-Bild:

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "doubao-seedream-5-0-pro",
    "prompt": "A sunlit mountain trail in autumn, photorealistic, wide angle",
    "size": "1024x1024",
    "n": 1
  }'

Und hier ist dieselbe Anfrage in Node.js mit fetch:

const response = await fetch("https://api.apimart.ai/v1/images/generations", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "doubao-seedream-5-0-pro",
    prompt: "A sunlit mountain trail in autumn, photorealistic, wide angle",
    size: "1024x1024",
    n: 1
  })
});

const data = await response.json();
console.log(data);

Halte diese Anfrage serverseitig. Gib deinen API-Schlüssel niemals in clientseitigem Code preis.

Sobald du die Anfrage übermittelst, ist der nächste Schritt, die Antwort-Payload zu parsen.

4. Antworten verarbeiten und gängige Bild-Workflows ausführen

4.1 Bild-URLs, Base64-Ausgabe und Fehlerobjekte parsen

Sobald die Anfrage fertig ist, bleibt die Antwortform gleich, egal ob du ein Bild oder mehrere gesendet hast.

Eine erfolgreiche Antwort gibt ein JSON-Objekt mit vier obersten Feldern zurück: model, created (ein Unix-Zeitstempel), data (ein Array von Bildobjekten) und usage ^[6]. Jedes generierte Bild erscheint innerhalb von data entweder als url- oder als b64_json-String, je nach angefordertem Format. Wenn n größer als 1 ist, enthält data ein Bildobjekt pro Ausgabe.

Wenn du das URL-Format verwendet hast, speichert jedes Element in data den Bildlink in .url. Du kannst diesen Wert als Bild-src im Browser setzen. Ein Haken: Das sind temporäre signierte Links, und sie laufen nach 24 Stunden ab ^[6]. Für Produktions-Apps lade die Datei sofort herunter und speichere sie in einem dauerhaften Speicher, statt die URL aufzubewahren.

Wenn du das Base64-Format verwendet hast, speichert jedes Element in data den Rohstring in .b64_json. Er enthält nicht den data:image/...;base64,-Präfix ^[6]. Um es in einem Browser anzuzeigen, füge diesen Präfix selbst hinzu:

img.src = "data:image/png;base64", + data.b64_json;

Um es als Datei in Python zu speichern, dekodiere es zuerst:

import base64

image_data = base64.b64decode(response["data"][0]["b64_json"])
with open("output.png", "wb") as f:
    f.write(image_data)

Wenn die Anfrage fehlschlägt, enthält die Antwort ein code- und ein message-Feld ^[6]. Ein 400 bedeutet in der Regel eine nicht unterstützte Größe oder einen ungültigen Parameter. Ein 401 bedeutet, dass die Anfrage nicht autorisiert ist. Protokolliere jedes Mal beide Felder. In den meisten Fällen zeigt die message direkt auf das Problem.

Verwende diese Felder, um zu entscheiden, ob du die Ausgabe speichern, dekodieren oder anzeigen solltest.

---

4.2 Drei gängige Bildtypen, die du mit Seedream 5.0 Pro generieren kannst

Diese drei Muster stimmen mit den zuvor behandelten Modi überein: nur Text, Einzelreferenz und Mehrfachreferenz.

• Nur-Text-Marketingvisuals. Für Kampagnen-Assets, die mehr Detail brauchen, verwende 3K-Auflösung (size: "3K") und schreibe einen strukturierten prompt, der mit dem Motiv und dem Szenenlayout beginnt und dann Beleuchtung, Stil und Farbdetails hinzufügt. Die 3K-Generierung dauert 35–50 Sekunden, sodass asynchron in der Regel besser passt.

• Produktvariationen mit Einzelreferenz. Verwende den Bild-zu-Bild-Modus mit einem Referenzbild in image_urls und einem fokussierten prompt, der nur das ändert, was du willst, wie Hintergrund, Beleuchtung oder Oberflächentextur. Das hält die Form und die Details des Produkts näher am Ausgangsbild, als von Grund auf zu generieren. Verwende für 3K-Variationen callback_url, da jede Aufgabe rund 40 Sekunden dauern kann ^[2].

• Mehrfachreferenz-Konsistenz für Marken- und Charakterkonsistenz. Wenn ein Charakter oder gebrandetes Element über mehrere Bilder hinweg konsistent bleiben soll, übergib bis zu 14 Referenzbilder über image_urls ^[2][3]. Setze sequential_image_generation auf auto, wenn du mehrere Ausgaben aus Referenzeingaben erstellst, damit du Vielfalt behältst, ohne die visuelle Konsistenz zu verlieren ^[5][4]. Das funktioniert gut für Social-Content-Serien, Produktkataloge und Charakterbögen.

Diese Muster funktionieren tendenziell am besten, wenn das Antwortformat zum Workflow passt.

---

4.3 Synchrone vs. asynchrone Anfragen und URL vs. Base64-Antworten

Verwende diesen Vergleich, um das Antwortformat zu wählen, bevor du die Integration auslieferst.

Warte bei asynchronen Jobs etwa 20 Sekunden vor der ersten Abfrage und prüfe dann alle 3 Sekunden ^[2]. In der Produktion ist callback_url die bessere Option, weil sie Polling-Schleifen vermeidet und den Server-Overhead reduziert ^[2][9].

Verwende standardmäßig URL-Antworten. Wechsle nur dann zu Base64, wenn du die Bilddaten in derselben Antwort brauchst.

5. Abschließende Checkliste für eine zuverlässige Seedream 5.0 Pro-Integration

Nach deinem ersten erfolgreichen Testaufruf gehe diese Checkliste durch, bevor du auf die Produktion skalierst. Es ist ein einfacher Weg, die Probleme abzufangen, die Launches gerne komplett stoppen.

Authentifizierung und Schlüsselsicherheit. Bewahre deinen API-Schlüssel in einer Umgebungsvariable oder einem Secret-Manager auf. Sende Anfragen von deinem Backend mit Authorization: Bearer <your_key>.

Validiere deine Anfrageparameter, bevor du sie sendest. Prüfe den Modell-String, übergib n als Ganzzahl, halte image_urls innerhalb des erlaubten Limits und stelle sicher, dass die angeforderte size unterstützt wird.

Passe bei Jobs, die länger als eine schnelle Vorschau dauern, deinen Lieferweg entsprechend an. Setze Timeouts basierend auf der Ausgabegröße und verwende callback_url für langlaufende Jobs statt Polling.

Sobald das Bild fertig ist, behandle die Lieferung als Speicherproblem, nicht nur als Antwortproblem. Wenn du URL-Ausgabe verwendest, lade die Datei sofort herunter und verschiebe sie in einen dauerhaften Speicher. Signierte URLs laufen nach 24 Stunden ab ^[6].

Teste Prompts an einem kleinen Batch, bevor du hochskalierst. Seedream 5.0 wird mit etwa 0,0320 $ pro generiertem Bild abgerechnet ^[2]. Protokolliere createTime, completeTime und costTime, damit du Latenz und Ausgaben beobachten kannst ^[2].

FAQs

Wie prüfe ich einen asynchronen Bildjob, nachdem ich eine task_id erhalten habe?

Verwende die zurückgegebene task_id, um den Status deines asynchronen Bildjobs zu prüfen.

Sende eine GET-Anfrage an den Status-Endpunkt, den die API dir gibt. In vielen APIs sieht das so aus:

• /v1/tasks/{task_id}
• oder ein abfragebasierter Endpunkt mit der task_id

Warte für den Produktionseinsatz nach dem Erstellen der Aufgabe etwa 20 Sekunden vor deiner ersten Statusprüfung. Danach frage alle 3 Sekunden ab, bis der Jobstatus completed anzeigt.

Sobald der Job fertig ist, lies die Antwort-Payload und ziehe die Bild-URLs daraus.

Wann sollte ich URL-Ausgabe statt Base64 verwenden?

Verwende in den meisten Fällen URL-Ausgabe. Sie gibt dir einen direkten Link zum generierten Bild, was es einfacher macht, es in Web- oder Mobile-Apps einzubinden.

Verwende Base64 nur, wenn dein Setup die Bilddaten inline im Antwortkörper braucht, etwa bei speicherbasierter Verarbeitung oder wenn du eine zweite Anfrage überspringen willst. Für hochauflösende 4K-Assets ist URL-Ausgabe in der Regel effizienter.

Was ist der beste Weg, um generierte Bilder nicht zu verlieren?

Speichere generierte Bilder zügig, denn API-Bildlinks sind nur 72 Stunden gültig.

Die Seedream 5.0 Pro API läuft asynchron. Das bedeutet, du bekommst die Bild-URL nicht sofort. Zuerst erhältst du eine Aufgaben-ID. Dann verwendest du diese Aufgaben-ID, um die Bild-URL abzurufen.

Um die Ausgabe nicht zu verlieren, hast du zwei Hauptoptionen:

• Frage mit der Aufgaben-ID ab, bis das Bild fertig ist
• Verwende eine Callback-URL, damit dein System das Bild empfangen, erfassen und speichern kann, bevor der Link abläuft

Wenn du zu lange wartest, läuft die URL ab und das Bild geht möglicherweise verloren.