Справка / API и агенты
API раскладки изображений для агентов
Используйте оригинальных или стилизованных персонажей либо собственное изображение при наличии документально подтверждённого согласия. Для любого изображения другого узнаваемого человека необходимо его документально подтверждённое согласие. Для всех референсных изображений, обучающих данных, аудио и результатов соблюдайте Политику допустимого использования.
Простой JSON-интерфейс, с помощью которого ИИ-агент (Claude, Codex, любой, кто говорит по HTTP) может полностью скомпоновать изображение Ideogram 4: сцену, текст на картинке, области объектов, типографские стили, цвета, ни разу не касаясь капризной внутренней схемы подписи модели.
Вы описываете картинку простыми словами: общую сцену и список полей, размещённых по долям кадра. Phosphene сам переводит это в строгую подпись Ideogram 4, рендерит и возвращает пути к изображениям.
Это дополняет общую docs/API.md. Обе обслуживает один и тот же процесс панели.
Сервер
- Базовый URL:
http://127.0.0.1:8199 - Процесс:
mlx_ltx_panel.py(корень репозитория). Логика подписи:ideogram_caption.py. - Авторизация: нет, только loopback.
- Две конечные точки:
GET /image/agent/schema(контракт) иPOST /image/agent(проверка / рендер).
Агентам: сначала прочитайте схему.
GET /image/agent/schemaвозвращает полное описание по полям, правила подписи и два готовых примера. Агент, прочитавший только этот ответ, может составить правильный запрос. Краткое изложение ниже предназначено для людей.
Модель поля
Координаты это доли кадра с началом в левом верхнем углу: они не зависят от пропорций, поэтому одно и то же поле попадает в то же относительное место при любом соотношении сторон.
x,y: левый верхний угол поля (0 = слева / сверху, 1 = справа / снизу).w,h: ширина / высота поля как доля кадра.(0,0)это левый верхний угол изображения;(1,1)правый нижний.- Следите, чтобы
x + w ≤ 1иy + h ≤ 1; поля, выходящие за край, обрезаются (вы получаете предупреждение, а не ошибку).
Внутри каждое поле превращается в bbox [y_min, x_min, y_max, x_max] из целых чисел от 0 до 1000, сначала строки. Вам писать это не нужно: это делает сервер.
Поля запроса (POST /image/agent)
| Поле | Тип | По умолчанию | Примечания |
|---|---|---|---|
scene | string | нет (обязательно) | Общий фон / обстановка / настроение. Описывайте мир, а не текст. |
boxes | array | нет (обязательно) | Список размещённых элементов. Для рендера одной лишь сцены может быть []. |
render | design | photo | design | design = вид графики / постера / вектора; photo = фотографический вид. |
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 | Усилие сэмплера → V4_TURBO_12 / V4_DEFAULT_20 / V4_QUALITY_48. |
n | int 1-4 | 1 | Сколько вариантов изображения рендерить. |
seed | int | -1 | Фиксированный сид для воспроизводимости; -1 = случайный. При n>1: seed, seed+1, … |
validate_only | bool | false | Если true: не рендерить, а вернуть построенную подпись и предупреждения. |
wait | bool | true | Если true: ждать окончания рендера и вернуть пути к изображениям. Если false: поставить в очередь и сразу вернуться. |
Поля поля
| Поле | Тип | Относится к | Примечания |
|---|---|---|---|
type | text | object | оба | text рендерит дословные слова; object рендерит описанный предмет. |
x, y, w, h | number 0-1 | оба | Начало в левом верхнем углу, доли кадра (см. выше). |
text | string | text (обязательно) | Дословные слова для рендера. Пустые текстовые поля отбрасываются. |
desc | string | object (обязательно), text (необязательно) | Что рендерить. Для текстовых полей заменяет автоматическое описание стиля / выравнивания / цвета. |
style | headline | subhead | body | caps | script | serif | text | Типографский характер. По умолчанию headline. |
align | left | center | right | text | По умолчанию center. |
color | #RRGGBB | text | В любом регистре; приводится к верхнему. Неверные значения заменяются на #FFFFFF. |
Ответы
validate_only:true→200 { "ok": true, "caption": {…}, "issues": [warnings]}.wait:true(по умолчанию) →200 { "ok": true, "caption": {…}, "images": [{"path","url"}], "seconds": N, "job_id": "…"}. Откройте каждыйurlна этом же хосте, чтобы посмотреть PNG.wait:false→202 { "ok": true, "queued": true, "job_id": "…", "caption": {…}, "where_results_land": "…"}.- Неверный запрос →
400 {"ok": false, "issues": […]}(нет сцены, объект безdesc,nвне диапазона, неизвестное значение перечисления, поле, которое ничего не рендерит, …). - GPU занят / идёт рендер →
503(временно: повторите, когда освободится). Запрос сwait:trueв остальных случаях просто ждёт своей очереди. - Тайм-аут →
504через 25 минут (задание может ещё завершиться в очереди).
issues читаемы человеком. Предупреждения (обрезка за пределами кадра, сильное перекрытие, замена неверного цвета, отброшенное пустое текстовое поле) рендер не останавливают; фатальные возвращают 400.
Примеры curl
1. Проверить макет без рендера (бесплатно, мгновенно)
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. Отрендерить полный постер 16:9 и дождаться изображений
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. Отправить этикетку 9:16 и сразу вернуться (не блокировать)
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":"..."}
Прочитать контракт
curl -s http://127.0.0.1:8199/image/agent/schema | python3 -m json.tool
Ожидаемое время рендера
Время по часам ≈ однократная холодная загрузка модели + n × время сэмплера на изображение. Первый рендер Ideogram после запуска панели медленнее, потому что веса загружаются один раз.
quality | Сэмплер | Скорость |
|---|---|---|
turbo | V4_TURBO_12 (~12 шагов) | быстрее всего |
default | V4_DEFAULT_20 (~20 шагов) | умеренная |
quality | V4_QUALITY_48 (~48 шагов) | медленнее всего, наивысшая точность |
Рендеры выстраиваются в последовательность с остальной работой GPU панели (видео, обучение, другие задания с изображениями). Запрос с wait:true ждёт за любым выполняющимся заданием; если не хотите держать соединение, используйте wait:false и опрашивайте GET /state по вашему job_id. Тайм-аут wait равен 25 минутам.
Примечание (доступ к весам Ideogram): при первом использовании Ideogram 4 скачивает с Hugging Face веса с закрытым доступом. Если вы получаете 5xx про отказ в доступе, оператору панели нужно задать в Настройках токен HF Read, и этот же аккаунт должен принять лицензию на
huggingface.co/ideogram-ai/ideogram-4-fp8. Это делается один раз, на стороне оператора.
Фрагмент системного промпта для автора агента
Вставьте это в системный промпт вашего агента, чтобы он правильно работал с конечной точкой:
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. Источник: docs/AGENT_API.md в открытом репозитории. Проверено для этого сайта перед публикацией. Переведено с английского оригинала. Предложить правку.