Docs / API e agenti
API di layout per immagini per agenti
Usa personaggi originali o stilizzati, oppure la tua immagine con un consenso documentato. Qualsiasi raffigurazione di un’altra persona identificabile richiede il suo consenso documentato. Per tutte le immagini di riferimento, i dati di addestramento, l’audio e i risultati segui la Politica di utilizzo accettabile.
Un’interfaccia JSON pulita che permette a un agente LLM (Claude, Codex, qualsiasi cosa parli HTTP) di comporre per intero un’immagine Ideogram 4, con scena, testo sull’immagine, regioni di oggetti, stili tipografici e colori, senza mai toccare il delicato schema interno delle didascalie del modello.
Descrivi un’immagine in termini semplici: una scena complessiva, più un elenco di riquadri posizionati per frazione del fotogramma. Phosphene lo traduce per te nella rigorosa didascalia di Ideogram 4, ne fa il render e ti restituisce i percorsi delle immagini.
Completa la docs/API.md generale. Lo stesso processo del pannello serve entrambe.
Server
- URL di base:
http://127.0.0.1:8199 - Processo:
mlx_ltx_panel.py(radice del repository). Logica delle didascalie:ideogram_caption.py. - Autenticazione: nessuna, solo loopback.
- Due endpoint:
GET /image/agent/schema(il contratto) ePOST /image/agent(convalida / render).
Agenti: leggete prima lo schema.
GET /image/agent/schemarestituisce la specifica completa campo per campo, le regole delle didascalie e due esempi completi. Un agente che legge solo quella risposta può comporre una richiesta corretta. Il riepilogo qui sotto è per gli esseri umani.
Il modello dei riquadri
Le coordinate sono frazioni del fotogramma con origine in alto a sinistra, indipendenti dalle proporzioni, quindi lo stesso riquadro cade nello stesso punto relativo con qualsiasi formato.
x,y: l’angolo in alto a sinistra del riquadro (0 = sinistra / alto, 1 = destra / basso).w,h: larghezza / altezza del riquadro come frazione del fotogramma.(0,0)è l’angolo in alto a sinistra dell’immagine;(1,1)è quello in basso a destra.- Mantieni
x + w ≤ 1ey + h ≤ 1; i riquadri che escono da un bordo vengono limitati (ricevi un avviso, non un errore).
Internamente ogni riquadro diventa un bbox [y_min, x_min, y_max, x_max] di interi in ordine riga-prima da 0 a 1000. Non lo scrivi mai tu: lo fa il server.
Campi della richiesta (POST /image/agent)
| Campo | Tipo | Predefinito | Note |
|---|---|---|---|
scene | stringa | (obbligatorio) | Lo sfondo / ambientazione / atmosfera complessivi. Descrivi il mondo, non il testo. |
boxes | array | (obbligatorio) | Elenco degli elementi posizionati. Può essere [] per un render di sola scena. |
render | design | photo | design | design = aspetto grafico/poster/vettoriale; photo = fotografico. |
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 | Impegno del campionatore → V4_TURBO_12 / V4_DEFAULT_20 / V4_QUALITY_48. |
n | intero 1-4 | 1 | Immagini candidate di cui fare il render. |
seed | intero | -1 | Seed fisso per la riproducibilità; -1 = casuale. Per n>1: seed, seed+1, … |
validate_only | booleano | false | Se true: non fa il render, restituisce la didascalia costruita più gli avvisi. |
wait | booleano | true | Se true: attende la fine del render e restituisce i percorsi delle immagini. Se false: mette in coda e risponde subito. |
Campi dei riquadri
| Campo | Tipo | Si applica a | Note |
|---|---|---|---|
type | text | object | entrambi | text fa il render di parole letterali; object di una cosa descritta. |
x, y, w, h | numero 0-1 | entrambi | Origine in alto a sinistra, frazioni del fotogramma (vedi sopra). |
text | stringa | text (obbligatorio) | Le parole letterali di cui fare il render. I riquadri di testo vuoti vengono scartati. |
desc | stringa | object (obbligatorio), text (facoltativo) | Che cosa renderizzare. Per i riquadri di testo, sostituisce la descrizione automatica di stile/allineamento/colore. |
style | headline | subhead | body | caps | script | serif | text | Resa tipografica. Predefinito headline. |
align | left | center | right | text | Predefinito center. |
color | #RRGGBB | text | Maiuscole o minuscole indifferenti; normalizzato in maiuscolo. I valori errati ripiegano su #FFFFFF. |
Risposte
validate_only:true→200 { "ok": true, "caption": {…}, "issues": [warnings]}.wait:true(predefinito) →200 { "ok": true, "caption": {…}, "images": [{"path","url"}], "seconds": N, "job_id": "…"}. Apri ogniurlsu questo stesso host per vedere il PNG.wait:false→202 { "ok": true, "queued": true, "job_id": "…", "caption": {…}, "where_results_land": "…"}.- Richiesta errata →
400 {"ok": false, "issues": […]}(scena mancante, oggetto senzadesc,nfuori intervallo, enum sconosciuto, un riquadro che non renderizza nulla, …). - GPU occupata / render in corso →
503(temporaneo: riprova quando si libera). Altrimenti una richiestawait:trueaspetta semplicemente il suo turno in coda. - Timeout →
504dopo 25 minuti (il lavoro può comunque finire in coda).
issues sono leggibili da una persona. Gli avvisi (limitazione fuori fotogramma, sovrapposizione forte, ripiego su colore errato, riquadro di testo vuoto scartato) vengono comunque renderizzati; il sottoinsieme fatale restituisce 400.
Esempi con curl
1. Convalidare un layout senza fare il render (gratuito, istantaneo)
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. Fare il render di un poster 16:9 completo e attendere le immagini
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. Inviare un’etichetta 9:16 e rispondere subito (senza bloccare)
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":"..."}
Leggere il contratto
curl -s http://127.0.0.1:8199/image/agent/schema | python3 -m json.tool
Tempi di render previsti
Il tempo reale è circa un caricamento a freddo del modello, una sola volta + n × tempo del campionatore per immagine. Il primo render Ideogram dopo l’avvio del pannello è più lento perché i pesi si caricano una volta.
quality | Campionatore | Velocità |
|---|---|---|
turbo | V4_TURBO_12 (~12 passi) | il più veloce |
default | V4_DEFAULT_20 (~20 passi) | moderata |
quality | V4_QUALITY_48 (~48 passi) | la più lenta, la massima fedeltà |
I render sono messi in serie con l’altro lavoro GPU del pannello (video, addestramento, altri lavori di immagini). Una richiesta wait:true aspetta dietro qualsiasi lavoro in corso; se preferisci non tenere aperta la connessione, usa wait:false e interroga GET /state per il tuo job_id. Il timeout di wait è di 25 minuti.
Nota (accesso ai pesi di Ideogram): Ideogram 4 scarica da Hugging Face pesi ad accesso riservato al primo utilizzo. Se ricevi un 5xx per accesso negato, chi gestisce il pannello deve impostare in Impostazioni un token Read di HF e lo stesso account deve aver accettato la licenza su
huggingface.co/ideogram-ai/ideogram-4-fp8. Si fa una volta sola, lato operatore.
Frammento di prompt di sistema per chi scrive un agente
Incolla questo nel prompt di sistema del tuo agente perché usi correttamente l’endpoint:
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. Fonte: docs/AGENT_API.md nel repository pubblico. Rivisto per questo sito prima della pubblicazione. Tradotto dall'originale inglese. Suggerisci una modifica.