
Dieser Ideogram 4.6 API Leitfaden führt Sie vom API-Key bis zum fertigen Bild in cURL und Python und behandelt dann jeden Eingabemodus, den das PoYo-Schema akzeptiert: Text-to-Image in Preset- oder benutzerdefinierten Größen, transparente Hintergründe, reguläre Bearbeitungen, maskierte Bearbeitungen, Referenzbilder und hochpräzise Bearbeitungen. Text-to-Image verwendet die Modell-ID ideogram-v4.6, die Bearbeitung ideogram-v4.6-edit; beide sind auf der Ideogram 4.6 Modellseite gelistet.
Die Feldregeln stammen aus der PoYo API-Referenz. Was das Modell ist und wie es im Vergleich abschneidet, erfahren Sie zuerst in der Übersicht zur Ideogram 4.6 API.
Schritt 1: einen Ideogram 4.6 API Request mit cURL senden
Erstellen Sie einen Key im PoYo-Dashboard und exportieren Sie ihn als POYO_API_KEY. Bewahren Sie ihn auf Ihrem Server auf, nicht im Browser-Code.
curl https://api.poyo.ai/api/generate/submit \
-H "Authorization: Bearer $POYO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "ideogram-v4.6",
"input": {
"prompt": "A colorful storefront with a neon sign reading \"HELLO\""
}
}'
Das nutzt die Standardwerte: size: auto (etwa 2K), quality: medium, ein Bild, also kostet es 12 Credits ($0.06). Eine erfolgreiche Übermittlung liefert code: 200 und ein data-Objekt mit task_id, status: "not_started" und created_time. Das ist ein Task in der Warteschlange, kein Bild. Prüfen Sie jedes Mal code im Body: Manche Validierungsfehler kommen mit HTTP 200 und code: 400 zurück.
Schritt 2: den Task-Status pollen
curl https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
Der Status durchläuft not_started, running und dann finished oder failed. Ein abgeschlossener Task listet in data.files einen Eintrag pro Bild, jeweils mit file_url und file_type: "image", und meldet die Belastung in credits_amount. Ein fehlgeschlagener Task erklärt sich in error_message.
Schritt 3: eine begrenzte Python-Polling-Schleife
Diese Schleife prüft sowohl den HTTP-Status als auch den code im Body, stoppt bei failed, gibt alle Bilder zurück, wenn n größer als 1 ist, und gibt nach 10 Minuten auf, ohne erneut zu senden.
import os
import time
import requests
BASE = "https://api.poyo.ai"
session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ["POYO_API_KEY"]
def checked(response):
body = response.json()
if response.status_code >= 400 or body.get("code") != 200:
error = body.get("error") or {}
raise RuntimeError(f"PoYo error {body.get('code')}: {error.get('message', body)}")
return body["data"]
def run(model, input_body, max_wait=600):
task = checked(session.post(BASE + "/api/generate/submit",
json={"model": model, "input": input_body},
timeout=60))
task_id = task["task_id"]
deadline = time.monotonic() + max_wait
while time.monotonic() < deadline:
time.sleep(5)
task = checked(session.get(BASE + "/api/generate/status/" + task_id, timeout=60))
if task["status"] == "failed":
raise RuntimeError(task.get("error_message") or "generation failed")
if task["status"] == "finished":
images = [f["file_url"] for f in task.get("files", []) if f.get("file_type") == "image"]
return images, task.get("credits_amount")
raise TimeoutError("Still running, check this task later: " + task_id)
images, credits = run("ideogram-v4.6", {
"prompt": "A minimalist poster titled \"SUMMER JAZZ NIGHTS\", bold typography",
"size": "1728x2304",
"quality": "high",
"n": 2,
})
print(images, credits)
1728x2304 ist eine 3:4-Größe mit 3,981,312 Pixeln, also unter der Grenze von 4,194,304 Pixeln, daher werden die zwei Bilder zum 2K-High-Tarif abgerechnet: 2 × 20 = 40 Credits ($0.20). Ein Timeout bedeutet „dieselbe Task-ID später erneut prüfen“. Ein erneutes Senden würde einen zweiten kostenpflichtigen Task starten. Dasselbe run() funktioniert für Bearbeitungen: Übergeben Sie "ideogram-v4.6-edit" als Modell.
Alle Eingabemodi der Ideogram 4.6 API
Alle Felder gehören in input. Die Modell-ID und eine optionale callback_url stehen auf oberster Ebene.
Text-to-Image in 4K
{
"model": "ideogram-v4.6",
"input": {
"prompt": "A minimalist poster titled \"SUMMER JAZZ NIGHTS\", bold typography",
"size": "2048x3072",
"quality": "high",
"n": 2
}
}
2048x3072 sind 6,291,456 Pixel, also über 4,194,304; das ist die 4K-Stufe, und very_low ist bei dieser Größe nicht erlaubt.
Transparenter Hintergrund und fester Seed
{
"model": "ideogram-v4.6",
"input": {
"prompt": "A flat sticker of a smiling coffee cup",
"size": "1:1 HD",
"quality": "low",
"background": "transparent",
"seed": 42
}
}
transparent liefert ein Bild mit Alphakanal; opaque erzwingt einen deckenden Hintergrund. Senden Sie denselben Body mit demselben seed, um ein Ergebnis zu wiederholen.
Reguläre Bearbeitung
{
"model": "ideogram-v4.6-edit",
"input": {
"prompt": "Replace the background with a blue photo studio",
"image_urls": [
"https://example.com/source.png"
]
}
}
Eine reguläre Bearbeitung generiert das Bild aus dem Prompt neu. image_urls muss ein Array mit genau einem Bild sein, als öffentliche HTTP(S)-URL oder Base64-Data-URI. Um lokale Dateien zu senden, laden Sie sie zuerst über den Datei-Upload-Endpunkt von PoYo hoch.
Umgestaltung mit einem Referenzbild
{
"model": "ideogram-v4.6-edit",
"input": {
"prompt": "Restyle the product shot to match the reference",
"image_urls": [
"https://example.com/product.png"
],
"reference_image_urls": [
"https://example.com/style.png"
],
"size": "2048x2048",
"quality": "low",
"n": 2
}
}
Bis zu 4 Referenzen sind erlaubt, mit Maske 3. Eine benutzerdefinierte size ist hier erlaubt, weil es sich um eine reguläre Bearbeitung ohne Maske handelt.
Hochpräzise Bearbeitung des ganzen Bildes
{
"model": "ideogram-v4.6-edit",
"input": {
"prompt": "Change only the date line to \"JULY 3-5 · RIVERSIDE PARK\". Keep everything else exactly the same.",
"image_urls": [
"https://example.com/poster.png"
],
"edit_precision": "high",
"context_window": "none",
"size": "auto",
"quality": "high"
}
}
Das ist der Body unserer Bearbeitung vom Launch-Tag (Task 672JRU198S22NS8D, 20. November 2026), mit ersetzter Quell-URL. Die Quelle war ein 2304×3072-Poster; die Ausgabe behielt diese Größe und änderte nur die Datumszeile, und der Task wurde mit 120 Credits ($0.60) belastet, dem 4K-High-Bearbeitungstarif.
Lokale maskierte Bearbeitung
{
"model": "ideogram-v4.6-edit",
"input": {
"prompt": "Change the sign text to \"OPEN LATE\"",
"image_urls": [
"https://example.com/storefront.png"
],
"mask_url": "https://example.com/sign-mask.png",
"edit_precision": "high",
"context_window": "auto",
"quality": "high"
}
}
Die Maske muss die Abmessungen der Quelle haben und sowohl schwarze (bearbeiten) als auch weiße (behalten) Bereiche enthalten. Mit context_window: auto wird nur der Bereich um die Maske in der Auflösung der Quelle bearbeitet. Eine zu große Maske fällt auf die Bearbeitung des ganzen Bildes zurück.
Validierungsregeln für die Felder
Validieren Sie vor dem Senden auf Ihrer Seite, damit fehlerhafte Requests schnell scheitern:
| Feld | Regel |
|---|---|
model | ideogram-v4.6 oder ideogram-v4.6-edit |
prompt | Pflichtfeld, 1 bis 10,000 Zeichen, nicht nur Leerzeichen |
size | auto, 1:1, 1:1 HD, 4:3, 3:4, 16:9, 9:16 oder WIDTHxHEIGHT mit kleinem x |
| Benutzerdefinierte Größe | Jede Seite 256 bis 4096 und ein Vielfaches von 32; Seitenverhältnis zwischen 1:6 und 6:1 |
quality | very_low nur, wenn die Ausgabe höchstens 4,194,304 Pixel hat |
n | Ganzzahl 1 bis 8; Strings und Booleans werden abgelehnt |
image_urls | Nur Bearbeitung; Array mit genau einem Bild |
mask_url, edit_precision: high | Erfordern size: auto (oder kein size) |
background | Abgelehnt, wenn edit_precision gleich high ist |
context_window: auto | Erfordert mask_url und edit_precision: high |
| Unbekannte Felder | Abgelehnt mit einem unsupported fields-Fehler |
Beispiele: 2304x3072 besteht (beide Seiten Vielfache von 32); 1296x3168 scheitert, weil 1296 kein Vielfaches von 32 ist, obwohl Ideogram 4.5 es akzeptiert hat; 4096x512 scheitert (Verhältnis 8:1); very_low bei 2048x3072 scheitert.
Fehler, die Sie behandeln sollten
code | Bedeutung | Was zu tun ist |
|---|---|---|
| 400 | Ungültige Parameter | Body korrigieren; nicht unverändert wiederholen |
| 401 | Fehlender oder ungültiger API-Key | Den Authorization: Bearer-Header prüfen |
| 402 | Nicht genügend Credits | Aufladen, dann erneut senden |
| 429 | Rate-Limit überschritten | Zurückhalten und später erneut versuchen |
| 500, 502, 503 | Server-, Upstream- oder Verfügbarkeitsfehler | Mit Backoff wiederholen; vorher prüfen, ob bereits eine Task-ID zurückgegeben wurde |
Ein Task, der failed erreicht, enthält den Grund in error_message. Die vollständige Liste finden Sie unter Error Codes.
Callback statt Polling verwenden
Fügen Sie "callback_url": "https://your-app.example.com/poyo-webhook" auf oberster Ebene des Bodys ein, nicht in input. Wenn der Task abgeschlossen ist oder fehlschlägt, sendet PoYo die Task-Daten per POST an diese URL, signiert mit HMAC-SHA256 im Header X-Webhook-Signature; die Webhook-Doku beschreibt die Signaturregel. Behalten Sie ein langsames Polling als Fallback für Callbacks, die nie ankommen.
So wird Ihre erste Rechnung berechnet
Die Ideogram 4.6 API rechnet pro Ausgabebild ab: Preis der Qualitäts- und Größenstufe × n. 1 Credit = $0.005.
| Request | Stufe | Belastung |
|---|---|---|
Standardwerte (auto, medium, n: 1) | Text-to-Image medium 2K | 12 Credits ($0.06) |
very_low, 3:4, n: 1 | Text-to-Image very_low 2K | 1.6 Credits ($0.008) |
high, 1728x2304, n: 2 | Text-to-Image high 2K | 40 Credits ($0.20) |
high, 2304x3072, n: 1 | Text-to-Image high 4K | 40 Credits ($0.20) |
Hochpräzise Bearbeitung einer 2304×3072-Quelle, high | Bearbeitung high 4K | 120 Credits ($0.60) |
Die Zeilen very_low und 2304x3072 entsprechen dem, was unseren Tasks am Launch-Tag berechnet wurde. Bei Bearbeitungen mit size: auto wird der Preis anhand der Größe des Quellbilds angeboten und auf Basis des gelieferten Bildes abgerechnet, nie über dem Angebot. Der Beitrag zu den Preisen enthält weitere Rechenbeispiele.
Häufig gestellte Fragen
Ist die Ideogram 4.6 API mit dem OpenAI SDK kompatibel?
Nein. Es ist eine asynchrone Task-API: Senden Sie an /api/generate/submit und pollen Sie dann /api/generate/status/{task_id} oder empfangen Sie einen Callback. Einfaches requests, fetch oder cURL funktionieren.
Wie bearbeite ich ein Bild mit der Ideogram 4.6 API?
Rufen Sie ideogram-v4.6-edit mit einer URL in image_urls und der Änderung im prompt auf. Fügen Sie edit_precision: high hinzu, um die Pixel zu behalten, deren Änderung Sie nicht angefordert haben.
Kann ich Referenzbilder an ideogram-v4.6 senden?
Nein. Bei PoYo gehören Referenzen in reference_image_urls bei ideogram-v4.6-edit, bis zu 4, mit Maske 3.
Wie viele Bilder liefert ein Ideogram 4.6 API Request?
1 bis 8, festgelegt mit n. Jedes Bild wird zum Preis seiner Stufe abgerechnet.
Warum wurde mein Ideogram 4.6 API Request wegen der Größe abgelehnt?
Benutzerdefinierte Seiten müssen Vielfache von 32 zwischen 256 und 4096 sein, und Masken oder hochpräzise Bearbeitungen erfordern size: auto.