Tutorial
So verwenden Sie seedream-4.5/text-to-image über die HiAPI API: curl- und Python-Beispiele
Eine praktische Anleitung für Entwickler zur minimal lauffähigen Integration
Auf dieser Seite
Was seedream-4.5/text-to-image für Sie bereitstellt
seedream-4.5/text-to-image ist der Text-zu-Bild-Endpunkt, der über die HiAPI API bereitgestellt wird. Sie senden einen Text-Prompt und einige optionale Parameter, und das Modell gibt ein generiertes Bild zurück. Sie können ihn verwenden, um Szenenillustrationen, Produkt-Mockups, Konzeptkunst oder jegliche visuelle Inhalte zu erstellen, bei denen lesbarer Text im Bild gerendert werden muss – Schilder, Etiketten, kurze Überschriften. Der Endpunkt ist zustandslos: Jede Anfrage ist eine eigenständige Generierung, sodass die Kontrolle über Wiederholungen und Variationen in Ihrem Anwendungscode liegt.
Da er hinter derselben einheitlichen Schnittstelle wie andere HiAPI-Modelle läuft, authentifizieren Sie sich nur einmal, verwenden dieselbe Basis-URL und dieselben Fehlerkonventionen und müssen beim Modellwechsel kein neues Integrationsmuster lernen. Die Modelldetailseite von seedream-4.5/text-to-image listet die aktuellen Parameternamen und zulässigen Werte auf – betrachten Sie diese Seite als maßgebliche Quelle für die Felder, nicht diesen Artikel.
Anfragestruktur: Was gesendet und empfangen wird
Jeder Text-zu-Bild-Aufruf hat dieselbe Struktur: eine POST-Anfrage mit einem JSON-Anfragekörper an den HiAPI-Endpunkt des Modells. Der Anfragekörper enthält die vom Modell benötigten Felder; die Antwort enthält das generierte Bild und Metadaten zur Anfrage.
Was gesendet wird
prompt(String, erforderlich): Die Beschreibung des Bildes. Dies ist die wichtigste Steuerungsebene; siehe den Prompt-Abschnitt unten.aspect_ratiooder ein größenbezogenes Feld (optional): Steuert die Form der Ausgabe-Canvas. Verwenden Sie den genauen Feldnamen von der Modelldetailseite – gehen Sie nicht davon aus, dass er mit dem Parameternamen anderer Modelle übereinstimmt.- Alle modellspezifischen Optionen, die auf der Modellseite dokumentiert sind (z. B. Stil- oder Qualitätshinweise). Lassen Sie Felder weg, die Sie nicht benötigen; die API wendet Standardwerte an.
Was empfangen wird
Eine erfolgreiche Antwort ist ein JSON-Objekt. Die Felder, die Ihr Code tatsächlich liest, sind normalerweise:
- Die Bildnutzlast: je nach Antwortschema entweder eine URL zum generierten Bild oder ein base64-kodierter Bild-String. Ihr Code sollte das Format verarbeiten, das der Endpunkt tatsächlich zurückgibt; die Modellseite gibt an, welches es ist.
- Anfragemetadaten wie Kennungen oder Status, nützlich für Protokollierung und Support.
Nicht jedes Feld ist in allen Versionen garantiert, daher sollten Sie die Antwortstruktur validieren, statt ein festes Schema anzunehmen. Wenn Sie einen Parser erstellen, der nur nach den benötigten Feldern sucht und andere als optional behandelt, übersteht Ihre Integration geringfügige Antwortänderungen.
Ihre erste ausführbare curl-Anfrage
Der minimale gültige Aufruf sendet nur einen Prompt und sonst nichts. Ersetzen Sie den Platzhalter-Schlüssel und den Prompt durch Ihre eigenen und führen Sie ihn aus.
curl -X POST "https://api.hiapi.ai/v1/models/seedream-4.5/text-to-image" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Ein ruhiges Straßencafé in der Abenddämmerung, warmes Fensterlicht, ein Kreideschild mit der Aufschrift OPEN",
"aspect_ratio": "1:1"
}'
Zeile für Zeile erklärt:
- Die URL verweist auf den HiAPI-Endpunkt des Modells. Halten Sie die Modellkennung exakt mit der Dokumentation identisch.
- Der
Authorization-Header trägt Ihren API-Schlüssel. Die Verwendung von Umgebungsvariablen verhindert, dass der Schlüssel in Ihrer Shell-Historie und in Quelldateien auftaucht. Content-Type: application/jsonteilt dem Server mit, dass der Anfragekörper als JSON zu parsen ist.- Der JSON-Anfragekörper enthält den Prompt und ein optionales Seitenverhältnis. Beginnen Sie mit einem Bild und einem Prompt; iterieren Sie die Formulierung, bevor Sie Optionen hinzufügen.
Bei erfolgreichem Aufruf enthält die Antwort die im vorigen Abschnitt beschriebenen Bilddaten. Speichern Sie die Ausgabe in einer Datei (oder öffnen Sie die zurückgegebene URL) und prüfen Sie sie, bevor Sie weiter bauen. Bei einem Authentifizierungsfehler stellen Sie sicher, dass der Schlüssel vorhanden und der Header korrekt geschrieben ist; bei einem Parameterfehler prüfen Sie die Feldnamen erneut anhand der Modellseite.
Dieselbe Anfrage in Python
Die Python-Version verwendet die Standardbibliothek requests – kein SDK erforderlich.
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
URL = "https://api.hiapi.ai/v1/models/seedream-4.5/text-to-image"
payload = {
"prompt": "Ein ruhiges Straßencafé in der Abenddämmerung, warmes Fensterlicht, ein Kreideschild mit der Aufschrift OPEN",
"aspect_ratio": "1:1",
}
response = requests.post(
URL,
headers={"Authorization": f"Bearer {API_KEY}"},
json=payload,
timeout=60,
)
response.raise_for_status()
result = response.json()
print(result)
Zwei Details sind hier wichtig. Erstens: Übergeben Sie json=payload statt eines manuell erstellten Strings – requests setzt den Inhaltstyp und serialisiert korrekt. Zweitens: Legen Sie ein explizites timeout fest. Die Bildgenerierung kann länger dauern als typische API-Aufrufe, daher ist ein großzügiges Timeout mit klar definiertem Fehlerverhalten besser als eine hängende Anfrage.
Das ausgegebene Ergebnis ist die Rohantwort. In echtem Code extrahieren Sie das Bildfeld, das Ihr Endpunkt zurückgibt (URL oder base64), und laden dann entweder die URL mit einer zweiten Anfrage herunter oder dekodieren die base64-Daten zu Bytes und schreiben sie auf die Festplatte. Legen Sie diese Extraktionslogik in eine kleine Hilfsfunktion, damit Test- und Produktionscode dieselbe Parsing-Logik teilen.
Prompts für Realismus und lesbaren Text schreiben
Die Prompt-Qualität bestimmt die Ausgabequalität stärker als jeder andere Parameter. Die zwei häufigsten Ziele sind: fotorealistische Szenen und klar lesbarer Text im Bild.
Realismus
Beschreiben Sie die Szene so, wie ein Fotograf sie ins Bild setzt: Motiv, Licht, Tageszeit, Objektivwirkung und Umgebung. Konkrete Substantive schlagen abstrakte Adjektive. Schreiben Sie nicht „ein schönes Café“, sondern „ein schmales Café-Interieur, Mittagslicht durch große Fenster, Holztheke, geringe Schärfentiefe“. Fügen Sie einen kurzen Stilhinweis hinzu, z. B. „photograph“ oder „documentary photo“, um das Modell vom Illustrationsstil wegzuführen. Halten Sie einen Hauptmotiv pro Prompt; konkurrierende Motive führen oft zu unübersichtlichen Kompositionen.
Lesbarer Text
Wenn das Bild Text enthalten muss, setzen Sie den genauen Text in Anführungszeichen und halten Sie ihn kurz. Ein Schild mit der Aufschrift OPEN oder ein Etikett mit FRESH BREAD ist weit zuverlässiger als ein ganzer Textabsatz. Geben Sie an, wo der Text erscheint – „ein Kreideschild über der Theke mit der Aufschrift OPEN“ –, damit das Modell weiß, dass der Text zu einem Objekt gehört. Wenn der Text unleserlich wird, kürzen Sie ihn, vereinfachen Sie die umgebende Szene und generieren Sie neu. Kleine Formulierungsanpassungen sind normal; rechnen Sie mit einigen Iterationen.
Iteration
Ändern Sie jeweils nur eine Variable: zuerst den Prompt, dann das Seitenverhältnis, zuletzt etwaige Stiloptionen. Speichern Sie Ihre Prompts sowie die Einstellungen, die gute Ergebnisse erzielt haben. Diese Aufzeichnung wird Ihre Basis für Neugenerierungen und verhindert, dass Debugging zu Rätselraten wird.
Seitenverhältnisse und Ausgabeeinstellungen wählen
Das Seitenverhältnis bestimmt die Komposition, bevor das Modell irgendetwas zeichnet. Wählen Sie es nach dem Verwendungszweck, nicht um den Standardwert zu treffen.
- Quadrat (
1:1): Social-Media-Beiträge, Avatare, Produktkacheln. Einfach und sicher. - Querformat (z. B.
16:9): Banner, Key Visuals, Präsentationsfolien. Fördert weite Szenen – Horizonte, Ladenfronten, geräumige Innenräume. - Hochformat (z. B.
9:16): Mobile Bildschirme, Stories, Poster. Prompts mit klarem vertikalem Motiv – stehende Personen, hochaufragende Gebäude – funktionieren am besten.
Wenn Ihr Prompt eine weite Szene beschreibt, Sie aber eine Hochformat-Canvas anfordern, muss das Modell die Komposition beschneiden oder verzerren. Lassen Sie Beschreibung und Bildformat zueinander passen. Für nachgelagerte Pipelines generieren Sie in der Größe, die für Ihren größten Anwendungsfall passt, und verkleinern Sie später; das Hochskalieren kleiner Bilder sieht selten richtig aus. Wenn Sie mehrere Formate benötigen, starten Sie für jedes Verhältnis einen eigenen Aufruf, statt ein Bild in verschiedene Layouts zu beschneiden.
Ausgabeeinstellungen jenseits des Seitenverhältnisses (Qualitätshinweise, Stilsteuerung) sind modellspezifisch. Setzen Sie nur das, was auf der Modellseite dokumentiert ist, und behandeln Sie jeden zusätzlichen Parameter als zu testende Variable, nicht als zu übernehmenden Standardwert.
Fehler und Ratenlimits behandeln
Fehlschläge in Produktionsintegrationen sind vorhersehbar: falscher Schlüssel, ungültige Parameter, Timeouts und Drosselung. Behandeln Sie jede Klasse explizit.
Vor dem Parsen validieren
Prüfen Sie zuerst den HTTP-Statuscode. 2xx bedeutet Erfolg – dann parsen Sie den Antwortkörper. 4xx bedeutet in der Regel, dass Ihre Anfrage fehlerhaft ist: nicht autorisierter Schlüssel, fehlerhaftes JSON oder nicht unterstützter Parameterwert. Diese Probleme lösen sich nicht durch Wiederholen; protokollieren Sie den Antwortkörper, melden Sie ihn an den Aufrufer und korrigieren Sie die Anfrage. 5xx bedeutet ein serverseitiges Problem, meist vorübergehend.
Wiederholen mit Backoff
Wiederholen Sie nur Fehlschläge, die später erfolgreich sein könnten: 429-Antworten, Timeouts, Verbindungsfehler und die meisten 5xx-Statuscodes. Verwenden Sie exponentielles Backoff mit Jitter – warten Sie ein kurzes Basisintervall, verdoppeln Sie es bei jedem Versuch und begrenzen Sie die Gesamtzahl der Versuche. Wiederholen Sie niemals 400 oder 401; Sie verbrauchen nur unnötig Kontingent.
import time, random
def generate(payload, max_attempts=5):
for attempt in range(max_attempts):
try:
r = requests.post(URL, headers=HEADERS, json=payload, timeout=60)
except requests.RequestException:
pass # Netzwerkfehler: unten erneut versuchen
else:
if r.status_code == 200:
return r.json()
if r.status_code not in (429, 500, 502, 503, 504):
raise RuntimeError(f"Nicht behebbar: {r.status_code} {r.text}")
time.sleep(min(2 ** attempt + random.random(), 30))
raise RuntimeError("Wiederholungsversuche erschöpft")
Limits einhalten
Halten Sie das Anfragevolumen unter dem für Ihr Konto angegebenen Ratenlimit und behandeln Sie 429 als Signal zum Verlangsamen, nicht als Signal, stärker zu wiederholen. Fügen Sie in Workern eine Obergrenze für die Parallelität hinzu und protokollieren Sie für jeden Versuch die Anfrage-ID, um Drosselung und Fehlschläge im Nachhinein diagnostizieren zu können. Da Bildaufrufe nach generierter Ausgabe abgerechnet werden, sind Wiederholungen, die Bilder erzeugen, nicht kostenlos – validieren Sie die Eingabe vor dem Senden der Anfrage.
Von der Testanfrage zur Produktions-Checkliste
Bevor Sie live gehen, bestätigen Sie die folgenden betrieblichen Punkte:
- Schlüsselverwaltung: Schlüssel liegen in Umgebungsvariablen oder einem Secret Manager, niemals in der Versionskontrolle. Rotieren Sie Schlüssel planmäßig und sofort bei jedem vermuteten Leck.
- Timeouts: Jeder ausgehende Aufruf hat ein explizites Timeout, und Ihr Aufrufer hat einen Plan für den Umgang mit abgelaufenen Timeouts.
- Protokollierung: Protokollieren Sie für jeden Aufruf Anfrage-ID, Prompt-Version, Parameter, Status und Latenz. Schwärzen Sie bei Bedarf Schlüssel und vollständige Nutzlasten.
- Prompt-Versionierung: Speichern Sie Prompts sowie die Einstellungen, die akzeptierte Ausgaben erzeugt haben, um Reproduzierbarkeit und Rollback zu ermöglichen.
- Kostenbewusstsein: Generierungen werden nach Ausgabe abgerechnet, daher begrenzen Sie die Batch-Größe, vermeiden Sie unnötige Wiederholungen und cachen Sie Ergebnisse, die Sie wiederverwenden.
- Graceful Degradation: Wenn die Generierung nach Wiederholungen weiterhin fehlschlägt, fallen Sie auf ein zwischengespeichertes Bild oder einen Platzhalter zurück, statt die Seite zu beschädigen.
Beginnen Sie mit dem einzelnen curl-Aufruf aus dieser Anleitung, verschieben Sie ihn in eine kleine Python-Hilfsfunktion und fügen Sie erst dann Parallelität und Batch-Verarbeitung hinzu. Beim Skalieren der Integration ist die Modellreferenzseite von seedream-4.5/text-to-image die Stelle, an der Sie Feldnamen bestätigen.
Ähnliche Artikel
Alle Artikel ansehen →-
Tutorial
gpt-6.2-sol Praxisleitfaden: 5 hochwertige Einsatzszenarien für Textmodelle im Geschäftsalltag
-
Tutorial
gpt-6.2-astra Praxisleitfaden: Integration und Umsetzung von 5 hochwertigen Text-Szenarien
Eine Entwickler-Checkliste von der Szenarioauswahl bis zur technischen Umsetzung
-
Tutorial
Tripo H3.1 Anwendungsszenarien in der Praxis: 5 wertvolle Einsatzmöglichkeiten und Umsetzungshinweise
Von Text-zu-3D bis Multi-View-Rekonstruktion: den richtigen Modus und die richtigen Parameter je nach Geschäftsszenario wählen