Pro
PT
EntrarConta Baixar para Mac
Baixar para Mac

Docs / API e agentes

API de layout de imagem para agentes

Use personagens originais ou estilizados, ou a sua própria imagem com consentimento documentado. Qualquer representação de outra pessoa identificável exige o consentimento documentado dela. Siga a Política de Uso Aceitável para todas as imagens de referência, dados de treino, áudios e resultados.

Uma superfície JSON limpa que permite a um agente de LLM (Claude, Codex, qualquer coisa que fale HTTP) compor por completo uma imagem do Ideogram 4, com cena, texto na imagem, regiões de objeto, estilos tipográficos e cores, sem nunca tocar no esquema interno e delicado de legenda do modelo.

Você descreve uma imagem em termos simples: uma cena geral, mais uma lista de caixas posicionadas por fração do quadro. O Phosphene traduz isso para a legenda rígida do Ideogram 4, renderiza e devolve os caminhos das imagens.

Isto complementa a docs/API.md geral. O mesmo processo do painel atende as duas.

Servidor

  • URL base: http://127.0.0.1:8199
  • Processo: mlx_ltx_panel.py (raiz do repositório). Lógica da legenda: ideogram_caption.py.
  • Autenticação: nenhuma, só loopback.
  • Dois endpoints: GET /image/agent/schema (o contrato) e POST /image/agent (validar / renderizar).

Agentes: leiam primeiro o schema. GET /image/agent/schema devolve a especificação completa campo a campo, as regras da legenda e dois exemplos completos. Um agente que ler só essa resposta consegue compor uma requisição correta. O resumo abaixo é para pessoas.


O modelo de caixa

As coordenadas são frações do quadro com origem no canto superior esquerdo, independentes da proporção, então a mesma caixa cai no mesmo ponto relativo em qualquer proporção.

  • x, y: o canto superior esquerdo da caixa (0 = esquerda / topo, 1 = direita / base).
  • w, h: a largura / altura da caixa como fração do quadro.
  • (0,0) é o canto superior esquerdo da imagem; (1,1) é o inferior direito.
  • Mantenha x + w ≤ 1 e y + h ≤ 1; caixas que passam de uma borda são cortadas no limite (você recebe um aviso, não um erro).

Internamente, cada caixa vira uma bbox [y_min, x_min, y_max, x_max] de inteiros, linha primeiro, de 0 a 1000. Você nunca escreve isso: o servidor faz.

Campos da requisição (POST /image/agent)

CampoTipoPadrãoObservações
scenestringsem padrão (obrigatório)O fundo / cenário / clima geral. Descreva o mundo, não o texto.
boxesarraysem padrão (obrigatório)Lista de elementos posicionados. Pode ser [] para uma renderização só de cena.
renderdesign | photodesigndesign = visual de gráfico/pôster/vetor; 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 | qualityturboEsforço do sampler → V4_TURBO_12 / V4_DEFAULT_20 / V4_QUALITY_48.
nint 1-41Imagens candidatas a renderizar.
seedint-1Seed fixa para reprodutibilidade; -1 = aleatória. Para n>1: seed, seed+1, …
validate_onlyboolfalseSe verdadeiro: não renderiza, devolve a legenda montada e os avisos.
waitbooltrueSe verdadeiro: bloqueia até a renderização terminar e devolve os caminhos das imagens. Se falso: enfileira e devolve na hora.

Campos da caixa

CampoTipoVale paraObservações
typetext | objectambostext renderiza palavras literais; object renderiza uma coisa descrita.
x, y, w, hnúmero 0-1ambosOrigem no canto superior esquerdo, frações do quadro (veja acima).
textstringtext (obrigatório)As palavras literais a renderizar. Caixas de texto vazias são descartadas.
descstringobject (obrigatório), text (opcional)O que renderizar. Em caixas de texto, substitui a descrição automática de estilo/alinhamento/cor.
styleheadline | subhead | body | caps | script | seriftextO jeito tipográfico. Padrão headline.
alignleft | center | righttextPadrão center.
color#RRGGBBtextMaiúsculas ou minúsculas; normalizado para maiúsculas. Valores inválidos voltam para #FFFFFF.

Respostas

  • validate_only:true → 200 { "ok": true, "caption": {…}, "issues": [warnings]}.
  • wait:true (padrão) → 200 { "ok": true, "caption": {…}, "images": [{"path","url"}], "seconds": N, "job_id": "…"}. Abra cada url neste mesmo host para ver o PNG.
  • wait:false → 202 { "ok": true, "queued": true, "job_id": "…", "caption": {…}, "where_results_land": "…"}.
  • Requisição inválida → 400 {"ok": false, "issues": […]} (cena faltando, objeto sem desc, n fora do intervalo, enum desconhecido, uma caixa que não renderiza nada, …).
  • GPU ocupada / renderização em andamento → 503 (transitório: tente de novo quando ela liberar). Uma requisição com wait:true, fora isso, simplesmente espera a sua vez na fila.
  • Tempo esgotado → 504 depois de 25 minutos (o trabalho ainda pode terminar na fila).

Os issues são legíveis por pessoas. Os avisos (corte na borda, sobreposição forte, cor inválida substituída, caixa de texto vazia descartada) ainda renderizam; o subconjunto fatal devolve 400.


Exemplos com curl

1. Validar um layout sem renderizar (grátis, 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 um pôster 16:9 completo e esperar as imagens

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 um rótulo 9:16 e voltar na hora (sem 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":"..."}

Ler o contrato

curl -s http://127.0.0.1:8199/image/agent/schema | python3 -m json.tool

O que esperar do tempo de renderização

Tempo total ≈ carga inicial do modelo, uma única vez + n × tempo do sampler por imagem. A primeira renderização do Ideogram depois que o painel inicia é mais lenta, porque os pesos são carregados uma vez.

qualitySamplerVelocidade
turboV4_TURBO_12 (~12 passos)a mais rápida
defaultV4_DEFAULT_20 (~20 passos)moderada
qualityV4_QUALITY_48 (~48 passos)a mais lenta, de maior fidelidade

As renderizações são serializadas com o outro trabalho de GPU do painel (vídeo, treino, outros trabalhos de imagem). Uma requisição com wait:true espera atrás de qualquer trabalho em andamento; se você prefere não manter a conexão, use wait:false e consulte GET /state pelo seu job_id. O tempo limite de wait é de 25 minutos.

Observação (acesso restrito aos pesos do Ideogram): o Ideogram 4 baixa pesos com acesso restrito do Hugging Face no primeiro uso. Se você receber um 5xx sobre acesso negado, o operador do painel precisa ter um token Read do HF definido nos Ajustes e a mesma conta precisa ter aceitado a licença em huggingface.co/ideogram-ai/ideogram-4-fp8. Isso é feito uma única vez, pelo operador.


Trecho de prompt de sistema para quem cria agentes

Cole isto no prompt de sistema do seu agente para que ele use o endpoint corretamente:

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 no repositório público. Revisado para este site antes da publicação. Traduzido do original em inglês. Sugerir uma edição.