Doku / API und Agenten
Bildlayout-API für Agenten
Verwende eigene oder stilisierte Charaktere oder deine eigene Darstellung mit dokumentierter Einwilligung. Jede Darstellung einer anderen erkennbaren Person erfordert deren dokumentierte Einwilligung. Beachte die Richtlinie zur zulässigen Nutzung für alle Referenzbilder, Trainingsdaten, Audiodateien und Ergebnisse.
Eine saubere JSON-Schnittstelle, mit der ein LLM-Agent (Claude, Codex, alles, was HTTP spricht) ein Ideogram-4-Bild vollständig komponieren kann: Szene, Text im Bild, Objektbereiche, typografische Stile, Farben, ohne je das heikle interne Caption-Schema des Modells anzufassen.
Du beschreibst ein Bild in einfachen Worten: eine übergeordnete Szene plus eine Liste von Boxen, die nach Bruchteilen des Bildes platziert werden. Phosphene übersetzt das für dich in die strenge Ideogram-4-Caption, rendert sie und gibt dir die Bildpfade zurück.
Das ergänzt die allgemeine docs/API.md. Derselbe Panel-Prozess bedient beide.
Server
- Basis-URL:
http://127.0.0.1:8199 - Prozess:
mlx_ltx_panel.py(Stammordner des Repos). Caption-Logik:ideogram_caption.py. - Authentifizierung: keine, nur Loopback.
- Zwei Endpunkte:
GET /image/agent/schema(der Vertrag) undPOST /image/agent(validieren / rendern).
Agenten: Lest zuerst das Schema.
GET /image/agent/schemaliefert die vollständige Feld-für-Feld-Spezifikation, die Caption-Regeln und zwei komplette Beispiele. Ein Agent, der nur diese Antwort liest, kann eine korrekte Anfrage zusammenstellen. Die Zusammenfassung unten ist für Menschen.
Das Box-Modell
Koordinaten sind Bruchteile des Bildes mit Ursprung oben links, unabhängig vom Seitenverhältnis, sodass dieselbe Box bei jedem Seitenverhältnis an derselben relativen Stelle landet.
x,y: die linke obere Ecke der Box (0 = links / oben, 1 = rechts / unten).w,h: Breite / Höhe der Box als Bruchteil des Bildes.(0,0)ist oben links im Bild;(1,1)ist unten rechts.- Halte
x + w ≤ 1undy + h ≤ 1ein; Boxen, die über einen Rand hinausragen, werden begrenzt (du bekommst eine Warnung, keinen Fehler).
Intern wird jede Box zu einer Bbox [y_min, x_min, y_max, x_max] aus zeilenweisen Ganzzahlen von 0 bis 1000. Das schreibst du nie selbst; das macht der Server.
Anfragefelder (POST /image/agent)
| Feld | Typ | Standard | Hinweise |
|---|---|---|---|
scene | string | keiner (erforderlich) | Der übergeordnete Hintergrund / die Umgebung / Stimmung. Beschreibe die Welt, nicht den Text. |
boxes | array | keiner (erforderlich) | Liste der platzierten Elemente. Für ein reines Szenen-Rendering darf sie [] sein. |
render | design | photo | design | design = Grafik- / Poster- / Vektor-Look; photo = fotografisch. |
aspect | 16:9 | 1:1 | 9:16 | 4:3 | 3:4 | 21:9 | 16:9 | 16:9=1280×720, 1:1=1024×1024, 9:16=720×1280, 4:3=1024×768, 3:4=768×1024, 21:9=1280×544. |
quality | turbo | default | quality | turbo | Sampler-Aufwand → V4_TURBO_12 / V4_DEFAULT_20 / V4_QUALITY_48. |
n | int 1-4 | 1 | Anzahl der zu rendernden Kandidatenbilder. |
seed | int | -1 | Fester Seed für Reproduzierbarkeit; -1 = zufällig. Bei n>1: seed, seed+1, … |
validate_only | bool | false | Wenn true: nicht rendern, sondern die erzeugte Caption samt Warnungen zurückgeben. |
wait | bool | true | Wenn true: blockieren, bis das Rendering fertig ist, und Bildpfade zurückgeben. Wenn false: einreihen und sofort zurückkehren. |
Box-Felder
| Feld | Typ | Gilt für | Hinweise |
|---|---|---|---|
type | text | object | beide | text rendert wörtliche Wörter; object rendert eine beschriebene Sache. |
x, y, w, h | number 0-1 | beide | Ursprung oben links, Bruchteile des Bildes (siehe oben). |
text | string | text (erforderlich) | Die wörtlich zu rendernden Wörter. Leere Textboxen werden verworfen. |
desc | string | object (erforderlich), text (optional) | Was gerendert werden soll. Bei Textboxen überschreibt es die automatische Beschreibung aus Stil / Ausrichtung / Farbe. |
style | headline | subhead | body | caps | script | serif | text | Typografische Anmutung. Standard headline. |
align | left | center | right | text | Standard center. |
color | #RRGGBB | text | Beliebige Schreibweise; wird in Großbuchstaben normalisiert. Ungültige Werte fallen auf #FFFFFF zurück. |
Antworten
validate_only:true→200 { "ok": true, "caption": {…}, "issues": [warnings]}.wait:true(Standard) →200 { "ok": true, "caption": {…}, "images": [{"path","url"}], "seconds": N, "job_id": "…"}. Öffne jedeurlauf demselben Host, um das PNG zu sehen.wait:false→202 { "ok": true, "queued": true, "job_id": "…", "caption": {…}, "where_results_land": "…"}.- Fehlerhafte Anfrage →
400 {"ok": false, "issues": […]}(fehlende Szene, Objekt ohnedesc,naußerhalb des Bereichs, unbekannter Enum-Wert, eine Box, die nichts rendert, …). - GPU belegt / Rendering läuft →
503(vorübergehend, versuche es erneut, sobald sie frei wird). Eine Anfrage mitwait:truewartet sonst einfach in der Warteschlange, bis sie dran ist. - Timeout →
504nach 25 Minuten (der Auftrag kann in der Warteschlange trotzdem noch fertig werden).
issues sind für Menschen lesbar. Warnungen (Begrenzung außerhalb des Bildes, starke Überlappung, Rückfall bei ungültiger Farbe, verworfene leere Textbox) rendern trotzdem; die fatale Teilmenge liefert 400.
Curl-Beispiele
1. Ein Layout validieren, ohne zu rendern (kostenlos, sofort)
curl -s http://127.0.0.1:8199/image/agent \
-H 'Content-Type: application/json' \
-d '{
"validate_only": true,
"scene": "A moody vintage travel poster of a mountain lake at golden hour, warm muted palette",
"render": "design",
"aspect": "16:9",
"boxes": [
{"type":"text","x":0.08,"y":0.08,"w":0.84,"h":0.18,"text":"LAKE DISTRICT","style":"headline","align":"center","color":"#F5C518"},
{"type":"text","x":0.30,"y":0.80,"w":0.40,"h":0.10,"text":"Est. 1951","style":"serif","align":"center","color":"#FFFFFF"},
{"type":"object","x":0.55,"y":0.32,"w":0.35,"h":0.42,"desc":"A small wooden canoe drifting on the still lake"}
]
}'
2. Ein vollständiges 16:9-Poster rendern und auf die Bilder warten
curl -s http://127.0.0.1:8199/image/agent \
-H 'Content-Type: application/json' \
-d '{
"scene": "A moody vintage travel poster of a mountain lake at golden hour, warm muted palette",
"render": "design",
"aspect": "16:9",
"quality": "turbo",
"n": 1,
"wait": true,
"boxes": [
{"type":"text","x":0.08,"y":0.08,"w":0.84,"h":0.18,"text":"LAKE DISTRICT","style":"headline","align":"center","color":"#F5C518"},
{"type":"text","x":0.30,"y":0.80,"w":0.40,"h":0.10,"text":"Est. 1951","style":"serif","align":"center","color":"#FFFFFF"},
{"type":"object","x":0.55,"y":0.32,"w":0.35,"h":0.42,"desc":"A small wooden canoe drifting on the still lake"}
]
}'
# -> {"ok":true,"job_id":"...","caption":{...},"images":[{"path":".../cand_..._mflux.png","url":"/file?path=..."}],"seconds":...}
3. Ein 9:16-Etikett einreichen und sofort zurückkehren (nicht blockieren)
curl -s http://127.0.0.1:8199/image/agent \
-H 'Content-Type: application/json' \
-d '{
"scene": "A minimalist product label, soft off-white paper texture, centered composition",
"render": "design",
"aspect": "9:16",
"quality": "default",
"wait": false,
"boxes": [
{"type":"text","x":0.10,"y":0.42,"w":0.80,"h":0.16,"text":"COLD BREW","style":"caps","align":"center","color":"#0A0A0A"}
]
}'
# -> 202 {"ok":true,"queued":true,"job_id":"...","caption":{...},"where_results_land":"..."}
Den Vertrag lesen
curl -s http://127.0.0.1:8199/image/agent/schema | python3 -m json.tool
Erwartungen an die Renderzeit
Gesamtzeit ≈ einmaliges Kaltladen des Modells + n × Sampler-Zeit pro Bild. Das erste Ideogram-Rendering nach dem Start des Panels ist langsamer, weil die Gewichte einmal geladen werden.
quality | Sampler | Tempo |
|---|---|---|
turbo | V4_TURBO_12 (~12 Schritte) | am schnellsten |
default | V4_DEFAULT_20 (~20 Schritte) | mittel |
quality | V4_QUALITY_48 (~48 Schritte) | am langsamsten, höchste Detailtreue |
Renderings werden mit der übrigen GPU-Arbeit des Panels (Video, Training, andere Bildaufträge) serialisiert. Eine Anfrage mit wait:true wartet hinter jedem laufenden Auftrag; willst du die Verbindung nicht offen halten, nutze wait:false und frage GET /state nach deiner job_id ab. Das Timeout für wait beträgt 25 Minuten.
Hinweis (Ideogram-Gewichte mit Zugangsschranke): Ideogram 4 lädt beim ersten Gebrauch geschützte Gewichte von Hugging Face. Bekommst du einen 5xx wegen verweigerten Zugriffs, muss der Betreiber des Panels in den Einstellungen ein HF-Read-Token setzen und dasselbe Konto muss die Lizenz unter
huggingface.co/ideogram-ai/ideogram-4-fp8akzeptiert haben. Das ist einmalig und liegt beim Betreiber.
System-Prompt-Schnipsel für Agent-Autoren
Füge das in den System-Prompt deines Agenten ein, damit er den Endpunkt richtig bedient:
You can generate composed images (posters, labels, text-on-image graphics) with Phosphene's Ideogram 4 agent API at http://127.0.0.1:8199.
ALWAYS start by calling GET /image/agent/schema once — it returns the exact field schema, the rules, and two worked examples. Compose against that.
To make an image, POST JSON to /image/agent with:
- scene: a plain-language description of the overall background/mood (required).
- boxes: a list of placed elements (required; [] for a pure-scene image). Each box positions itself by FRACTIONS of the frame with a TOP-LEFT origin: x,y is the top-left corner and w,h the size, each in [0,1]. (0,0)=top-left, (1,1)=bottom-right. Keep x+w<=1 and y+h<=1.
* text box: {"type":"text","x","y","w","h","text": "<the literal words>", "style":"headline|subhead|body|caps|script|serif","align":"left|center|right","color":"#RRGGBB"}
* object box: {"type":"object","x","y","w","h","desc":"<what to render there>"} (desc is required for objects)
- render: "design" (graphic/poster) or "photo". aspect: "16:9"|"1:1"|"9:16"|"4:3"|"3:4"|"21:9". quality: "turbo"|"default"|"quality". n: 1-4.
Iterate cheaply with "validate_only": true — it returns the built caption plus warnings without rendering. When the layout looks right, POST again with "wait": true to render and receive image urls. Do NOT hand-write Ideogram's internal caption JSON — the server builds it from your scene+boxes. Max 6 text boxes. Quelle: docs/AGENT_API.md im öffentlichen Repo. Für diese Website vor der Veröffentlichung geprüft. Aus dem englischen Original übersetzt. Änderung vorschlagen.