Pro
DE
AnmeldenKonto Für Mac herunterladen
Für Mac herunterladen

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) und POST /image/agent (validieren / rendern).

Agenten: Lest zuerst das Schema. GET /image/agent/schema liefert 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 ≤ 1 und y + h ≤ 1 ein; 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)

FeldTypStandardHinweise
scenestringkeiner (erforderlich)Der übergeordnete Hintergrund / die Umgebung / Stimmung. Beschreibe die Welt, nicht den Text.
boxesarraykeiner (erforderlich)Liste der platzierten Elemente. Für ein reines Szenen-Rendering darf sie [] sein.
renderdesign | photodesigndesign = Grafik- / Poster- / Vektor-Look; photo = fotografisch.
aspect16:9 | 1:1 | 9:16 | 4:3 | 3:4 | 21:916:916:9=1280×720, 1:1=1024×1024, 9:16=720×1280, 4:3=1024×768, 3:4=768×1024, 21:9=1280×544.
qualityturbo | default | qualityturboSampler-Aufwand → V4_TURBO_12 / V4_DEFAULT_20 / V4_QUALITY_48.
nint 1-41Anzahl der zu rendernden Kandidatenbilder.
seedint-1Fester Seed für Reproduzierbarkeit; -1 = zufällig. Bei n>1: seed, seed+1, …
validate_onlyboolfalseWenn true: nicht rendern, sondern die erzeugte Caption samt Warnungen zurückgeben.
waitbooltrueWenn true: blockieren, bis das Rendering fertig ist, und Bildpfade zurückgeben. Wenn false: einreihen und sofort zurückkehren.

Box-Felder

FeldTypGilt fürHinweise
typetext | objectbeidetext rendert wörtliche Wörter; object rendert eine beschriebene Sache.
x, y, w, hnumber 0-1beideUrsprung oben links, Bruchteile des Bildes (siehe oben).
textstringtext (erforderlich)Die wörtlich zu rendernden Wörter. Leere Textboxen werden verworfen.
descstringobject (erforderlich), text (optional)Was gerendert werden soll. Bei Textboxen überschreibt es die automatische Beschreibung aus Stil / Ausrichtung / Farbe.
styleheadline | subhead | body | caps | script | seriftextTypografische Anmutung. Standard headline.
alignleft | center | righttextStandard center.
color#RRGGBBtextBeliebige 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 jede url auf 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 ohne desc, n auß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 mit wait:true wartet sonst einfach in der Warteschlange, bis sie dran ist.
  • Timeout → 504 nach 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.

qualitySamplerTempo
turboV4_TURBO_12 (~12 Schritte)am schnellsten
defaultV4_DEFAULT_20 (~20 Schritte)mittel
qualityV4_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-fp8 akzeptiert 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.