ヘルプ / APIとエージェント
エージェント用の画像レイアウトAPI
使えるのは、オリジナルまたはスタイライズされたキャラクター、または本人の同意が記録されている自分自身の姿です。他の特定可能な人物を描く場合は、その人の同意が記録されている必要があります。参照画像、学習データ、音声、出力のすべてについて、利用規定に従ってください。
LLMエージェント(Claude、Codex、HTTPを話せるものなら何でも)が、Ideogram 4の画像を完全に構成するためのシンプルなJSONインターフェースです。シーン、画像内の文字、オブジェクトの領域、文字のスタイル、色まで、モデルの扱いにくい内部キャプションのスキーマに一切触れずに指定できます。
絵は、平易な言葉で説明します。全体のシーンと、フレームの割合で配置したボックスのリストです。Phospheneがそれを厳密なIdeogram 4のキャプションに変換してレンダリングし、画像のパスを返します。
これは、全般的なdocs/API.mdを補うものです。どちらも同じパネルのプロセスが提供します。
サーバー
- ベースURL:
http://127.0.0.1:8199 - プロセス:
mlx_ltx_panel.py(リポジトリのルート)。キャプションのロジックはideogram_caption.py。 - 認証:なし。ループバックのみです。
- 2つのエンドポイント:
GET /image/agent/schema(仕様)とPOST /image/agent(検証 / レンダリング)。
エージェントの方へ:先にスキーマを読んでください。
GET /image/agent/schemaは、フィールドごとの完全な仕様、キャプションのルール、完成した例を2つ返します。このレスポンスだけを読めば、エージェントは正しいリクエストを組み立てられます。以下の概要は、人間向けです。
ボックスのモデル
座標は、左上を原点とするフレームに対する割合です。アスペクト比に依存しないので、同じボックスは、どのアスペクト比でも相対的に同じ位置に置かれます。
x、y:ボックスの左上の角(0 = 左端 / 上端、1 = 右端 / 下端)。w、h:ボックスの幅 / 高さで、フレームに対する割合。(0,0)は画像の左上、(1,1)は右下です。x + w ≤ 1とy + h ≤ 1を守ってください。端からはみ出したボックスは切り詰められます(エラーではなく警告が返ります)。
内部では、各ボックスが、0〜1000の行優先の整数によるバウンディングボックス [y_min, x_min, y_max, x_max] に変換されます。これを自分で書く必要はなく、サーバーが処理します。
リクエストのフィールド(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(必須) | 描画する文字そのもの。空の text ボックスは破棄されます。 |
desc | string | object(必須)、text(任意) | 描画する内容。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 がない、descのない object、nが範囲外、不明な列挙値、何も描画しないボックスなど)。 - GPUが使用中 / レンダリング進行中 →
503(一時的なものです。空いたら再試行してください)。それ以外の場合、wait:trueのリクエストは、キューの順番を待つだけです。 - タイムアウト → 25分後に
504(ジョブはキュー上で完了する場合があります)。
issues は人間が読めるメッセージです。警告(フレーム外の切り詰め、大きな重なり、不正な色の代替、空のtextボックスの破棄)はレンダリングされます。致命的なものだけが 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 × 1枚あたりのサンプラー時間が目安です。パネルの起動後、最初の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(公開リポジトリ)。公開前にこのウェブサイト向けに確認済みです。英語の原文から翻訳しています。編集を提案する。