帮助文档 / API 与智能体
面向智能体的图像布局 API
请使用原创或风格化的角色,或经有据可查的同意后使用你本人的形象。任何涉及其他可识别真人的描绘,都需要对方有据可查的同意。所有参考图、训练数据、音频和作品,都请遵守可接受使用政策。
这是一个简洁的 JSON 接口,让 LLM 智能体(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。 - 认证: 无,只允许本机回环访问。
- 两个端点:
GET /image/agent/schema(接口约定)和POST /image/agent(校验 / 渲染)。
智能体请先读 schema。
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": […]}(缺少 scene、object 没有desc、n超出范围、未知的枚举值、某个方框什么也渲染不出来,等等)。 - GPU 繁忙 / 正有渲染进行 →
503(暂时性的,待其空闲后重试一次即可)。除此之外,wait:true的请求会在队列里排队等候。 - 超时 → 25 分钟后返回
504(任务仍可能在队列里完成)。
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 读取令牌,并且同一个账号必须已在
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,位于公开仓库。发布前已针对本网站审阅。译自英文原文。建议修改。