Pro
ES
Iniciar sesiónCuenta Descargar para Mac
Descargar para Mac

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) y POST /image/agent (validar / renderizar).

Agentes: lean primero el esquema. GET /image/agent/schema devuelve 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 ≤ 1 y y + 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)

CampoTipoPor defectoNotas
scenestringobligatorioEl fondo / entorno / ambiente general. Describe el mundo, no el texto.
boxesarrayobligatorioLista de elementos colocados. Puede ser [] para un render de escena pura.
renderdesign | photodesigndesign = aspecto de gráfico/cartel/vector; photo = fotográfico.
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 | qualityturboEsfuerzo del muestreador → V4_TURBO_12 / V4_DEFAULT_20 / V4_QUALITY_48.
nint 1-41Imágenes candidatas que renderizar.
seedint-1Semilla fija para reproducibilidad; -1 = aleatoria. Con n>1: seed, seed+1, …
validate_onlyboolfalseSi es true: no renderiza; devuelve la descripción construida y las advertencias.
waitbooltrueSi 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

CampoTipoSe aplica aNotas
typetext | objectambostext renderiza palabras literales; object renderiza una cosa descrita.
x, y, w, hnúmero 0-1ambosOrigen arriba a la izquierda, fracciones del encuadre (ver arriba).
textstringtext (obligatorio)Las palabras literales que renderizar. Los cuadros de texto vacíos se descartan.
descstringobject (obligatorio), text (opcional)Qué renderizar. En los cuadros de texto, sustituye la descripción automática de estilo/alineación/color.
styleheadline | subhead | body | caps | script | seriftextAire tipográfico. Por defecto headline.
alignleft | center | righttextPor defecto center.
color#RRGGBBtextEn 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 cada url en 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 sin desc, n fuera de rango, enumeración desconocida, un cuadro que no renderiza nada, …).
  • GPU ocupada / render en curso → 503 (transitorio: reintenta cuando se libere). Una petición wait:true normalmente espera su turno en la cola.
  • Tiempo agotado → 504 a 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.

qualityMuestreadorVelocidad
turboV4_TURBO_12 (~12 pasos)la más rápida
defaultV4_DEFAULT_20 (~20 pasos)moderada
qualityV4_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.