레퍼런스

서버 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`	Multimode 배치. 비동기 POST (202) + SSE 멀티플렉싱 지원.
`POST /api/node/generate`	Node 모드 생성 및 자식 편집. 비동기 POST (202) + SSE 멀티플렉싱 지원.
`GET /api/node/:nodeId`	저장된 노드 메타데이터와 에셋 URL 조회.
`GET /api/events`	비동기 생성 진행 이벤트를 위한 SSE 멀티플렉스 채널.
`POST /api/video/generate`	Grok 비디오 생성 (T2V/I2V/Ref2V). 비동기 POST (202) + SSE 멀티플렉싱 지원.
`POST /api/video/edit`	Grok 비디오-투-비디오 편집. 결과 MP4를 generated artifact로 저장.
`POST /api/video/extend`	기존 MP4의 마지막 프레임에서 이어붙이기.
`GET /api/video/frame`	generated MP4에서 PNG 프레임 추출.
`POST /api/video/analyze`	generated MP4의 첫/마지막 프레임을 Grok 4.3 vision으로 분석.

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, grok-api, agy, gemini-api. 권장 OpenAI 모델은 gpt-5.4; 앱 기본값은 gpt-5.4-mini입니다. Grok 모델은 grok-imagine-image와 grok-imagine-image-quality입니다. Gemini 모델은 nano-banana-2(Flash)와 nano-banana-pro(Pro)입니다. 웹 UI는 GET /api/events (SSE 멀티플렉싱)로 모든 생성 진행 이벤트를 받습니다: POST 라우트에 { async: true, requestId }를 보내면 202 응답 후 이벤트 버스를 통해 phase, partial, done, error 이벤트가 멀티플렉싱됩니다. CLI에서 Accept: text/event-stream을 보내면 기존 per-request SSE를 그대로 사용합니다.

비디오 생성. POST /api/video/generate (SSE)는 Grok을 통해 비디오를 생성합니다. 모델: grok-imagine-video, 정식 grok-imagine-video-1.5; grok-imagine-video-1.5-preview는 호환 alias로만 받습니다. 모드: text-to-video, image-to-video, reference-to-video (2–7개 ref). 1080p는 1.5 단일 이미지/프레임 I2V에서만 사용할 수 있고 Ref2V, V2V edit, extension은 기본 모델 경로로 유지됩니다. CLI: ima2 video. 확장 표면은 ima2 video edit, ima2 video extend, ima2 video frame, ima2 video analyze입니다. 요청 본문은 plannerModel(기본 grok-4.3)와 순차 클립 연속성용 storyboard를 받습니다. frame/analyze는 generated MP4 파일을 대상으로 하며 analyze는 임의 원격 URL을 거부합니다.

히스토리

엔드포인트	비고
`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을 초과함.
`AGY_GENERATION_FAILED`	Gemini(agy) 이미지 생성 실패.
`AGY_TIMEOUT`	agy CLI 프로세스가 360초 timeout 초과.
`AGY_QUOTA_EXHAUSTED`	Gemini API 할당량 소진(rate limit).
`AGY_VIDEO_UNSUPPORTED`	Gemini(agy) 프로바이더는 비디오 생성 미지원.
`AGY_REF_TOO_MANY`	agy 레퍼런스 이미지 초과(최대 3장).
`GEMINI_API_KEY_MISSING`	Gemini API key 또는 Vertex AI 자격증명 미설정.
`GEMINI_API_RATE_LIMITED`	Gemini API rate limit(429).
`GEMINI_API_SAFETY_BLOCKED`	Gemini API safety 필터로 생성 차단.
`GEMINI_API_NO_IMAGE`	Gemini API 응답에 이미지 없음.
`VIDEO_PROVIDER_UNSUPPORTED`	비디오 생성은 `"grok"` 또는 `"grok-api"` 프로바이더가 필요함.

키 관리

설정 UI 또는 HTTP API로 런타임에 프로바이더 자격증명을 설정합니다.

엔드포인트	메서드	설명
`/api/keys/status`	GET	모든 프로바이더(openai, xai, gemini, vertex) 키 설정·유효성·마스킹 상태 반환.
`/api/keys/:provider`	PUT	API key 저장. 바디: `{"apiKey": "..."}`. 프로바이더: `openai`·`xai`·`gemini`.
`/api/keys/:provider`	DELETE	설정 파일 기반 API key 제거. env var 기반 키는 제거 불가(`ENV_KEY_IMMUTABLE`).
`/api/keys/vertex`	PUT	Vertex AI 서비스 계정 JSON 저장. 바디: `{"serviceAccountJson": "..."}`.
`/api/keys/vertex`	DELETE	설정 파일 기반 Vertex 서비스 계정 제거.

PUT으로 저장된 키는 config.json에 기록되고 런타임에 즉시 반영됩니다(서버 재시작 불필요). 환경 변수(GEMINI_API_KEY, VERTEX_SERVICE_ACCOUNT_JSON 등)는 설정 파일보다 우선하며 API로 변경할 수 없습니다.

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

설정