레퍼런스

서버 API

CLI는 로컬 서버 위의 얇은 셸 — 대부분의 /api/* 라우트에 CLI 래퍼가 있지만, Agent 모드는 웹 UI 전용입니다. Prompt builder는 ima2 prompt build로도 사용할 수 있습니다. 이 페이지는 엔드포인트 그룹을 정리합니다; 전체 요청/응답 형태는 API.md를 보세요.

베이스 URL

모든 엔드포인트는 로컬에서 제공됩니다. 기본 베이스는 http://localhost:3333이고, 실제 바인딩 포트는 ~/.ima2/server.json에 광고됩니다(backend.url 권장).

생성

엔드포인트	용도
`POST /api/generate`	텍스트-이미지 및 레퍼런스 기반 루트 생성.
`POST /api/edit`	이미지 편집 / image-to-image 생성.
`POST /api/generate/multimode` (SSE)	Multimode 배치.
`POST /api/node/generate` (SSE)	Node 모드 생성 및 자식 편집.
`GET /api/node/:nodeId`	저장된 노드 메타데이터와 에셋 URL 조회.
`POST /api/video/generate` (SSE)	Grok을 통한 비디오 생성 (T2V/I2V/Ref2V).

POST /api/generate — 요청 바디

{
  "prompt": "a shiba in space",
  "quality": "medium",
  "size": "1024x1024",
  "format": "png",
  "moderation": "low",
  "provider": "oauth",
  "model": "gpt-5.4",
  "references": [],
  "requestId": "optional-client-id"
}

품질: low, medium, high. Moderation: auto, low. Provider: auto, oauth, api, grok. 권장 OpenAI 모델은 gpt-5.4; 앱 기본값은 gpt-5.4-mini입니다. Grok 모델은 grok-imagine-image와 grok-imagine-image-quality입니다. SSE 라우트는 클라이언트가 Accept: text/event-stream을 보내면 phase, partial, done, error 이벤트를 보냅니다.

비디오 생성. POST /api/video/generate (SSE)는 Grok을 통해 비디오를 생성합니다. 모델: grok-imagine-video, grok-imagine-video-1.5-preview. 모드: text-to-video, image-to-video, reference-to-video (2–7개 ref). CLI: ima2 video.

히스토리

엔드포인트	비고
`GET /api/history`	생성 에셋 목록; `?groupBy=session`은 세션 제목별 그룹.
`DELETE /api/history/:filename`	생성 에셋 톰스톤(소프트 삭제).
`POST /api/history/:filename/restore`	최근 삭제된 에셋 복원.

세션 & 그래프

엔드포인트	비고
`GET /api/sessions` · `POST /api/sessions`	그래프 세션 목록 또는 생성.
`GET /api/sessions/:id`	세션과 그래프 로드.
`PATCH /api/sessions/:id` · `DELETE /api/sessions/:id`	세션 이름 변경 또는 삭제.
`PUT /api/sessions/:id/graph`	그래프 스냅샷 저장.

낙관적 동시성. 그래프 저장은 현재 버전이 담긴 If-Match 헤더가 필요합니다. 버전이 stale하면 GRAPH_VERSION_CONFLICT와 현재 버전을 반환합니다 — 다른 탭이 그래프를 바꿨다는 증거가 아니라, stale 스냅샷에 대해 저장했다는 뜻입니다.

Agent 모드 & 디스커버리

Agent 모드는 대화형 이미지 워크스페이스입니다(세션, 턴, durable 세션 큐). 이 라우트들은 항상 등록되지만 CLI 래퍼가 없습니다 — Agent 모드는 웹 UI에서 사용하세요.

엔드포인트	용도
`GET /api/capabilities`	에이전트 디스커버리: 지원 모델, 유효 값, 한도, 버전 (`ima2 capabilities`).
`GET · POST /api/agent/sessions`	에이전트 세션 목록 또는 생성.
`GET · PATCH · DELETE /api/agent/sessions/:id`	세션 로드·수정·삭제.
`POST /api/agent/sessions/:id/turns`	에이전트 턴 실행; 슬래시 명령과 `/question` 지원.
`GET · POST /api/agent/sessions/:id/queue`	durable 큐 조회·적재 (`/api/agent/queue/:itemId/cancel` · `retry`로 항목 관리).
`POST /api/prompt-builder/chat`	Prompt-builder 어시스턴트 (`ima2 prompt build`).

헬스 · 스토리지 · 작업

엔드포인트	비고
`GET /api/health`	헬스 체크 (`ima2 ping`).
`GET /api/providers`	프로바이더 가용성과 런타임 포트 (`ima2 providers`).
`GET /api/oauth/status`	OAuth 프록시 상태 (`ima2 oauth status`).
`GET /api/grok/status`	번들 progrok 상태와 xAI 모델 probe (`ima2 grok status`).
`GET /api/storage/status`	스토리지 점검.
`POST /api/storage/open-generated-dir`	OS 파일 매니저에서 생성 디렉터리 열기.
`GET /api/inflight` · `DELETE /api/inflight/:id`	진행 중 작업 목록 또는 강제 제거.

공통 에러 코드

코드	의미
`API_KEY_REQUIRED`	설정된 key 없이 API 경로 요청.
`INVALID_IMAGE_MODEL`	모델 이름이 알 수 없거나 미지원.
`IMAGE_MODEL_UNSUPPORTED`	모델은 있으나 이미지 생성 불가.
`SAFETY_REFUSAL` · `MODERATION_REFUSED`	업스트림 안전/모더레이션 거부.
`AUTH_CHATGPT_EXPIRED`	Codex/ChatGPT OAuth 세션 만료.
`AUTH_API_KEY_INVALID`	API key가 무효·취소·할당량 초과.
`NETWORK_FAILED`	네트워크·프록시·VPN·방화벽 실패.
`OAUTH_UNAVAILABLE`	로컬 OAuth 프록시 사용 불가.
`GRAPH_VERSION_CONFLICT`	stale 그래프 버전에 대한 저장.
`NODE_NOT_FOUND`	노드 메타데이터를 찾을 수 없음.
`GROK_REF_TOO_MANY`	Grok 요청에 총 세 장을 넘는 입력 이미지가 포함됨.
`GROK_MASK_UNSUPPORTED`	Grok edit이 mask와 함께 요청됨.
`INVALID_GROK_IMAGE_MODEL`	Grok 요청이 지원하지 않는 이미지 모델을 사용함.
`GROK_RATE_LIMITED` · `GROK_AUTH_FAILED`	progrok을 통한 xAI rate-limit 또는 auth 실패.
`GROK_SEARCH_TIMEOUT` · `GROK_PLANNER_TIMEOUT` · `GROK_IMAGE_TIMEOUT`	Grok 단계 중 하나가 timeout budget을 초과함.

전체 엔드포인트 → CLI 매핑, 레퍼런스 이미지 에러 코드, 스타일 시트 라우트는 API.md에 있습니다.

설정