Pro
中文
登录账户 下载 Mac 版
下载 Mac 版

帮助文档 / 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)

字段类型默认值说明
scenestring无(必填)整体的背景 / 场景 / 氛围。描述的是世界,不是文字。
boxesarray无(必填)摆放的元素列表。纯场景渲染时可以是 []。
renderdesign | photodesigndesign 是平面 / 海报 / 矢量风格;photo 是照片风格。
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 | qualityturbo采样器投入的力度,对应 V4_TURBO_12 / V4_DEFAULT_20 / V4_QUALITY_48。
nint 1-41要渲染的候选图数量。
seedint-1固定种子以便复现;-1 表示随机。当 n>1 时依次为 seed、seed+1……。
validate_onlyboolfalse为 true 时:不渲染,只返回生成的标注和警告。
waitbooltrue为 true 时:阻塞直到渲染完成并返回图片路径。为 false 时:入队后立即返回。

方框字段

字段类型适用于说明
typetext | object两者text 渲染原样的文字;object 渲染描述中的物体。
x、y、w、hnumber 0-1两者原点在左上角,取画面的比例值(见上文)。
textstringtext(必填)要渲染的原样文字。空的文字方框会被丢弃。
descstringobject(必填),text(可选)要渲染的内容。对文字方框来说,它会覆盖自动生成的样式 / 对齐 / 颜色描述。
styleheadline | subhead | body | caps | script | seriftext字体风格。默认 headline。
alignleft | center | righttext默认 center。
color#RRGGBBtext大小写均可,会统一转为大写。无效的值会回退为 #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采样器速度
turboV4_TURBO_12(约 12 步)最快
defaultV4_DEFAULT_20(约 20 步)适中
qualityV4_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,位于公开仓库。发布前已针对本网站审阅。译自英文原文。建议修改。