문서 / API와 에이전트
에이전트용 이미지 레이아웃 API
오리지널 캐릭터나 스타일화된 캐릭터, 또는 문서로 동의를 남긴 본인의 모습을 사용하세요. 다른 식별 가능한 사람을 묘사하려면 그 사람의 문서화된 동의가 필요해요. 모든 참조 이미지, 학습 데이터, 오디오, 결과물은 이용 정책을 따라야 해요.
LLM 에이전트(Claude, Codex 등 HTTP를 쓸 수 있는 모든 에이전트)가 모델의 까다로운 내부 캡션 스키마를 건드리지 않고 Ideogram 4 이미지를 완전히 구성할 수 있게 해 주는 깔끔한 JSON 인터페이스예요. 장면, 이미지 속 글자, 오브젝트 영역, 타이포그래피 스타일, 색상을 모두 다룰 수 있어요.
그림을 쉬운 말로 설명하면 돼요. 전체 장면(scene) 하나와, 프레임 비율로 위치를 정한 박스(boxes) 목록이에요. 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(검증 / 렌더링)예요.
에이전트는 스키마를 먼저 읽으세요.
GET /image/agent/schema는 필드별 전체 명세, 캡션 규칙, 완성된 예제 두 개를 돌려줘요. 에이전트가 이 응답만 읽어도 올바른 요청을 만들 수 있어요. 아래 요약은 사람을 위한 거예요.
박스 모델
좌표는 프레임에 대한 비율이고 왼쪽 위가 원점이에요. 화면 비율과 상관없이 같은 박스가 같은 상대 위치에 놓여요.
x,y: 박스의 왼쪽 위 모서리예요(0은 왼쪽 / 위, 1은 오른쪽 / 아래).w,h: 박스의 너비 / 높이를 프레임 비율로 나타내요.(0,0)은 이미지의 왼쪽 위,(1,1)은 오른쪽 아래예요.x + w ≤ 1,y + h ≤ 1을 지키세요. 가장자리를 넘어가는 박스는 잘라 내고, 오류가 아니라 경고가 돌아와요.
내부적으로 각 박스는 0..1000 범위의 정수, 행 우선 bbox [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, 알 수 없는 enum, 아무것도 렌더링하지 않는 박스 등). - 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 × 이미지당 샘플러 시간이에요. 패널을 시작한 뒤 처음 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 (공개 저장소). 공개 전에 이 웹사이트용으로 검토했어요. 영어 원문에서 번역했어요. 수정 제안하기.