Ayuda / API y agentes
API de composición de imágenes para agentes
Usa personajes originales o estilizados, o tu propia imagen con consentimiento documentado. Cualquier representación de otra persona identificable requiere su consentimiento documentado. Cumple la Política de uso aceptable en todas las imágenes de referencia, datos de entrenamiento, audios y resultados.
Una superficie JSON limpia que permite a un agente LLM (Claude, Codex, cualquiera que hable HTTP) componer por completo una imagen de Ideogram 4 (escena, texto en la imagen, regiones de objetos, estilos tipográficos, colores) sin tocar nunca el delicado esquema interno de descripciones del modelo.
Tú describes una imagen en términos sencillos: una escena general más una lista de cuadros colocados por fracción del encuadre. Phosphene lo traduce por ti a la descripción estricta de Ideogram 4, la renderiza y te devuelve las rutas de las imágenes.
Esto complementa la docs/API.md general. El mismo proceso del panel sirve a ambas.
Servidor
- URL base:
http://127.0.0.1:8199 - Proceso:
mlx_ltx_panel.py(raíz del repositorio). Lógica de la descripción:ideogram_caption.py. - Autenticación: ninguna, solo loopback.
- Dos endpoints:
GET /image/agent/schema(el contrato) yPOST /image/agent(validar / renderizar).
Agentes: lean primero el esquema.
GET /image/agent/schemadevuelve la especificación completa campo por campo, las reglas de la descripción y dos ejemplos completos. Un agente que lea solo esa respuesta puede componer una petición correcta. El resumen de abajo es para personas.
El modelo de cuadros
Las coordenadas son fracciones del encuadre con origen arriba a la izquierda, independientes de la proporción, así que el mismo cuadro cae en el mismo lugar relativo en cualquier relación de aspecto.
x,y: la esquina superior izquierda del cuadro (0 = izquierda / arriba, 1 = derecha / abajo).w,h: el ancho / alto del cuadro como fracción del encuadre.(0,0)es la esquina superior izquierda de la imagen;(1,1)es la inferior derecha.- Mantén
x + w ≤ 1yy + h ≤ 1; los cuadros que se salen por un borde se recortan (recibes una advertencia, no un error).
Internamente cada cuadro se convierte en un bbox [y_min, x_min, y_max, x_max] de enteros en orden fila primero, de 0 a 1000. Tú nunca lo escribes: lo hace el servidor.
Campos de la petición (POST /image/agent)
| Campo | Tipo | Por defecto | Notas |
|---|---|---|---|
scene | string | obligatorio | El fondo / entorno / ambiente general. Describe el mundo, no el texto. |
boxes | array | obligatorio | Lista de elementos colocados. Puede ser [] para un render de escena pura. |
render | design | photo | design | design = aspecto de gráfico/cartel/vector; photo = fotográfico. |
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 | Esfuerzo del muestreador → V4_TURBO_12 / V4_DEFAULT_20 / V4_QUALITY_48. |
n | int 1-4 | 1 | Imágenes candidatas que renderizar. |
seed | int | -1 | Semilla fija para reproducibilidad; -1 = aleatoria. Con n>1: seed, seed+1, … |
validate_only | bool | false | Si es true: no renderiza; devuelve la descripción construida y las advertencias. |
wait | bool | true | Si es true: se bloquea hasta que el render termina y devuelve las rutas de las imágenes. Si es false: encola y devuelve al instante. |
Campos de los cuadros
| Campo | Tipo | Se aplica a | Notas |
|---|---|---|---|
type | text | object | ambos | text renderiza palabras literales; object renderiza una cosa descrita. |
x, y, w, h | número 0-1 | ambos | Origen arriba a la izquierda, fracciones del encuadre (ver arriba). |
text | string | text (obligatorio) | Las palabras literales que renderizar. Los cuadros de texto vacíos se descartan. |
desc | string | object (obligatorio), text (opcional) | Qué renderizar. En los cuadros de texto, sustituye la descripción automática de estilo/alineación/color. |
style | headline | subhead | body | caps | script | serif | text | Aire tipográfico. Por defecto headline. |
align | left | center | right | text | Por defecto center. |
color | #RRGGBB | text | En mayúsculas o minúsculas; se normaliza a mayúsculas. Los valores incorrectos pasan a #FFFFFF. |
Respuestas
validate_only:true→200 { "ok": true, "caption": {…}, "issues": [warnings]}.wait:true(por defecto) →200 { "ok": true, "caption": {…}, "images": [{"path","url"}], "seconds": N, "job_id": "…"}. Abre cadaurlen este mismo host para ver el PNG.wait:false→202 { "ok": true, "queued": true, "job_id": "…", "caption": {…}, "where_results_land": "…"}.- Petición incorrecta →
400 {"ok": false, "issues": […]}(falta la escena, objeto sindesc,nfuera de rango, enumeración desconocida, un cuadro que no renderiza nada, …). - GPU ocupada / render en curso →
503(transitorio: reintenta cuando se libere). Una peticiónwait:truenormalmente espera su turno en la cola. - Tiempo agotado →
504a los 25 minutos (el trabajo aún puede terminar en la cola).
Los issues son legibles para personas. Las advertencias (recorte fuera del encuadre, solapamiento fuerte, color corregido, cuadro de texto vacío descartado) igualmente renderizan; el subconjunto fatal devuelve 400.
Ejemplos con curl
1. Validar una composición sin renderizar (gratis, instantáneo)
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. Renderizar un cartel completo 16:9 y esperar las imágenes
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. Enviar una etiqueta 9:16 y volver al instante (sin bloquear)
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":"..."}
Leer el contrato
curl -s http://127.0.0.1:8199/image/agent/schema | python3 -m json.tool
Tiempos de render esperados
Tiempo total ≈ carga inicial del modelo (una vez) + n × tiempo del muestreador por imagen. El primer render de Ideogram tras iniciar el panel es más lento porque los pesos se cargan una sola vez.
quality | Muestreador | Velocidad |
|---|---|---|
turbo | V4_TURBO_12 (~12 pasos) | la más rápida |
default | V4_DEFAULT_20 (~20 pasos) | moderada |
quality | V4_QUALITY_48 (~48 pasos) | la más lenta, máxima fidelidad |
Los renders se serializan con el resto del trabajo de GPU del panel (video, entrenamiento, otros trabajos de imagen). Una petición wait:true espera detrás de cualquier trabajo en curso; si prefieres no mantener la conexión, usa wait:false y consulta GET /state con tu job_id. El tiempo de espera de wait es de 25 minutos.
Nota (acceso a los pesos de Ideogram): Ideogram 4 descarga pesos restringidos de Hugging Face en el primer uso. Si recibes un 5xx sobre acceso denegado, quien opera el panel necesita un token de lectura de HF configurado en Configuración y la misma cuenta debe haber aceptado la licencia en
huggingface.co/ideogram-ai/ideogram-4-fp8. Se hace una sola vez, del lado del operador.
Fragmento de prompt de sistema para quien crea agentes
Pega esto en el prompt de sistema de tu agente para que maneje bien el 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. Fuente: docs/AGENT_API.md en el repositorio público. Revisado para este sitio web antes de publicarse. Traducido del original en inglés. Sugerir un cambio.