Pro
FR
Se connecterCompte Télécharger pour Mac
Télécharger pour Mac

Docs / API et agents

API de mise en page d'images pour agents

Utilisez des personnages originaux ou stylisés, ou votre propre image avec un consentement documenté. Toute représentation d’une autre personne identifiable exige son consentement documenté. Respectez la Politique d’utilisation acceptable pour toutes les images de référence, les données d’entraînement, les audios et les créations.

Une interface JSON simple qui permet à un agent LLM (Claude, Codex, tout ce qui parle HTTP) de composer entièrement une image Ideogram 4 (scène, texte dans l’image, zones d’objets, styles typographiques, couleurs) sans jamais toucher au schéma de légende interne du modèle, qui est capricieux.

Vous décrivez une image en termes simples : une scène d’ensemble, plus une liste de zones placées en fractions du cadre. Phosphene la traduit pour vous dans la légende stricte d’Ideogram 4, effectue le rendu et renvoie les chemins des images.

Elle complète l’docs/API.md général. Le même processus du panneau sert les deux.

Serveur

  • URL de base : http://127.0.0.1:8199
  • Processus : mlx_ltx_panel.py (racine du dépôt). Logique des légendes : ideogram_caption.py.
  • Authentification : aucune, boucle locale uniquement.
  • Deux points d’accès : GET /image/agent/schema (le contrat) et POST /image/agent (valider / rendre).

Agents : lisez d’abord le schéma. GET /image/agent/schema renvoie la spécification complète champ par champ, les règles de légende et deux exemples complets. Un agent qui ne lit que cette réponse peut composer une requête correcte. Le résumé ci-dessous s’adresse aux humains.


Le modèle de zones

Les coordonnées sont des fractions du cadre avec une origine en haut à gauche : elles ne dépendent pas du format, donc une même zone tombe au même endroit relatif quel que soit le rapport d’aspect.

  • x, y : le coin supérieur gauche de la zone (0 = gauche / haut, 1 = droite / bas).
  • w, h : la largeur / hauteur de la zone, en fraction du cadre.
  • (0,0) est le coin supérieur gauche de l’image ; (1,1) est le coin inférieur droit.
  • Gardez x + w ≤ 1 et y + h ≤ 1 ; les zones qui dépassent d’un bord sont rognées (vous obtenez un avertissement, pas une erreur).

En interne, chaque zone devient un bbox [y_min, x_min, y_max, x_max] d’entiers, ligne d’abord, de 0 à 1000. Vous n’avez jamais à l’écrire : le serveur s’en charge.

Champs de la requête (POST /image/agent)

ChampTypePar défautNotes
scenestringaucun (obligatoire)L’arrière-plan / le décor / l’ambiance d’ensemble. Décrivez le monde, pas le texte.
boxesarrayaucun (obligatoire)Liste des éléments placés. Peut être [] pour un rendu de scène seule.
renderdesign | photodesigndesign = look graphique / affiche / vectoriel ; photo = photographique.
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 | qualityturboEffort de l’échantillonneur → V4_TURBO_12 / V4_DEFAULT_20 / V4_QUALITY_48.
nint 1-41Nombre d’images candidates à rendre.
seedint-1Seed fixe pour la reproductibilité ; -1 = aléatoire. Pour n>1 : seed, seed+1, …
validate_onlyboolfalseSi true : ne rend pas, renvoie la légende construite et les avertissements.
waitbooltrueSi true : bloque jusqu’à la fin du rendu et renvoie les chemins des images. Si false : met en file d’attente et rend la main tout de suite.

Champs d’une zone

ChampTypeS’applique àNotes
typetext | objectles deuxtext rend des mots exacts ; object rend une chose décrite.
x, y, w, hnombre 0-1les deuxOrigine en haut à gauche, fractions du cadre (voir ci-dessus).
textstringtext (obligatoire)Les mots exacts à rendre. Les zones de texte vides sont ignorées.
descstringobject (obligatoire), text (facultatif)Ce qu’il faut rendre. Pour les zones de texte, remplace la description automatique du style / de l’alignement / de la couleur.
styleheadline | subhead | body | caps | script | seriftextAllure typographique. headline par défaut.
alignleft | center | righttextcenter par défaut.
color#RRGGBBtextCasse libre ; normalisée en majuscules. Les valeurs invalides retombent sur #FFFFFF.

Réponses

  • validate_only:true → 200 { "ok": true, "caption": {…}, "issues": [warnings]}.
  • wait:true (par défaut) → 200 { "ok": true, "caption": {…}, "images": [{"path","url"}], "seconds": N, "job_id": "…"}. Ouvrez chaque url sur ce même hôte pour voir le PNG.
  • wait:false → 202 { "ok": true, "queued": true, "job_id": "…", "caption": {…}, "where_results_land": "…"}.
  • Requête invalide → 400 {"ok": false, "issues": […]} (scène manquante, objet sans desc, n hors limites, énumération inconnue, une zone qui ne rend rien, …).
  • GPU occupé / rendu en cours → 503 (transitoire : réessayez dès qu’il se libère). Une requête wait:true attend sinon simplement son tour dans la file.
  • Délai dépassé → 504 après 25 minutes (le travail peut encore se terminer dans la file).

Les issues sont lisibles par un humain. Les avertissements (rognage hors cadre, fort chevauchement, repli sur une couleur par défaut, zone de texte vide ignorée) donnent quand même un rendu ; le sous-ensemble fatal renvoie 400.


Exemples curl

1. Valider une mise en page sans rendre (gratuit, instantané)

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. Rendre une affiche 16:9 complète et attendre les images

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. Envoyer une étiquette 9:16 et rendre la main tout de suite (sans bloquer)

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":"..."}

Lire le contrat

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

Temps de rendu à prévoir

Temps total ≈ chargement à froid du modèle (une fois) + n × temps de l’échantillonneur par image. Le premier rendu Ideogram après le démarrage du panneau est plus lent, parce que les poids se chargent une fois.

qualityÉchantillonneurVitesse
turboV4_TURBO_12 (~12 étapes)le plus rapide
defaultV4_DEFAULT_20 (~20 étapes)modérée
qualityV4_QUALITY_48 (~48 étapes)la plus lente, la plus fidèle

Les rendus sont sérialisés avec les autres travaux GPU du panneau (vidéo, entraînement, autres travaux d’images). Une requête wait:true attend derrière tout travail en cours ; si vous préférez ne pas garder la connexion ouverte, utilisez wait:false et interrogez GET /state avec votre job_id. Le délai d’attente de wait est de 25 minutes.

Note (accès aux poids d’Ideogram) : Ideogram 4 télécharge des poids à accès restreint depuis Hugging Face à la première utilisation. Si vous obtenez une erreur 5xx sur un accès refusé, l’opérateur du panneau doit saisir un jeton Read HF dans Réglages et le même compte doit avoir accepté la licence sur huggingface.co/ideogram-ai/ideogram-4-fp8. C’est à faire une seule fois, côté opérateur.


Extrait de prompt système pour l’auteur d’un agent

Collez ceci dans le prompt système de votre agent pour qu’il pilote correctement le point d’accès :

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.

Source : docs/AGENT_API.md dans le dépôt public. Relu pour ce site avant publication. Traduit de l'original anglais. Suggérer une modification.