Pro
한국어
로그인계정 Mac용 다운로드
Mac용 다운로드

문서 / 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)

필드타입기본값메모
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, 알 수 없는 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샘플러속도
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 (공개 저장소). 공개 전에 이 웹사이트용으로 검토했어요. 영어 원문에서 번역했어요. 수정 제안하기.