Pro
日本語
サインインアカウント Mac版をダウンロード
Mac版をダウンロード

ヘルプ / 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)

フィールド型デフォルト備考
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_onlyboolfalsetrue の場合、レンダリングはせず、組み立てたキャプションと警告を返します。
waitbooltruetrue の場合、レンダリングが終わるまで待機し、画像のパスを返します。false の場合は、キューに入れてすぐに返します。

ボックスのフィールド

フィールド型適用先備考
typetext | object両方text は文字をそのまま描画し、object は説明したものを描画します。
x、y、w、hnumber 0-1両方左上が原点。フレームに対する割合です(上を参照)。
textstringtext(必須)描画する文字そのもの。空の text ボックスは破棄されます。
descstringobject(必須)、text(任意)描画する内容。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 がない、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サンプラー速度
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の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(公開リポジトリ)。公開前にこのウェブサイト向けに確認済みです。英語の原文から翻訳しています。編集を提案する。