핵심 개념

프로바이더 & 모델

core registry에는 OpenAI OAuth/API, Grok OAuth/API, Gemini/Antigravity CLI, Gemini 직접 API, AtlasCloud API, MiniMax API로 구성된 provider lane 8개가 있습니다. Runway와 Higgsfield는 아래에서 따로 설명하는 MCP-backed integration입니다.

프로바이더 경로

• provider: "oauth" — 로컬 Codex OAuth 프록시를 사용합니다. 기본 경로이며 API key가 필요 없습니다.
• provider: "api" — 호스티드 image_generation 도구로 OpenAI Responses API를 호출합니다. OPENAI_API_KEY가 필요합니다.
• provider: "grok" — 번들 progrok을 시작하고, 필수 xAI Web Search와 planner pass(기본 grok-4.5, 설정 또는 --planner-model로 변경)를 거친 뒤 xAI Images API를 호출합니다. Grok 4.3은 호환 선택지로 유지합니다.
• provider: "grok-api" — grok과 같은 xAI pipeline을 직접 XAI_API_KEY로 실행합니다.
• provider: "agy" — Antigravity CLI(agy -p)를 통해 Google Gemini(nano-banana-2)로 이미지를 생성합니다. 고정 1024×1024 JPEG 출력, 최대 3장 참조.
• provider: "gemini-api" — Google Generative Language API 또는 Vertex AI를 직접 호출합니다. 모델 nano-banana-2(Gemini 3.1 Flash Image)와 nano-banana-pro(Gemini 3 Pro Image) 지원. 가변 화면비와 해상도(512px–4K) 지원. GEMINI_API_KEY 또는 Vertex AI 서비스 계정 JSON이 필요합니다.
• provider: "atlascloud" — ATLASCLOUD_API_KEY로 AtlasCloud GPT Image 2 생성·편집을 호출하며 참조는 최대 10장입니다.
• provider: "minimax" — MINIMAX_API_KEY로 MiniMax image-01과 image-01-live를 호출하며 참조는 1장입니다.

core lane은 Classic, Node, Agent Mode를 지원합니다. Agent Mode는 웹 UI 전용이고, Classic과 Node는 CLI도 있습니다.

요청 단위 오버라이드

생성 명령은 아래 core lane ID 8개를 명시합니다. 일부 명령이 받는 auto는 아홉 번째 lane이 아니라 routing mode입니다.

모델

이미지 생성과 Prompt Builder는 gpt-5.6-luna를 기본값으로 씁니다. 이전 지원 모델은 호환 선택지로 남아 있습니다.

앱은 품질(low, medium, high)과 moderation(auto, low) 컨트롤도 제공합니다. reasoning effort는 none, low, medium, high, xhigh를 받습니다.

Grok 파이프라인

Grok Classic, Node, Agent 요청은 세 단계로 동작합니다: 필수 xAI Web Search, planner pass(기본 grok-4.5, IMA2_GROK_PLANNER_MODEL·설정 UI·비디오 CLI의 --planner-model로 변경)로 영어 최종 이미지 프롬프트를 만든 뒤, xAI 이미지를 생성합니다. Grok 4.3은 호환 선택지로 유지합니다. 텍스트만 있는 요청은 /v1/images/generations를 쓰고, 레퍼런스 이미지·Node 부모 이미지·Agent 현재 이미지가 있으면 image-to-image 문맥을 유지하기 위해 /v1/images/edits를 씁니다. 이 경로의 입력 이미지는 총 세 장까지입니다.

ima2는 OpenAI식 size를 xAI aspect_ratio와 resolution 컨트롤로 매핑합니다. Grok mask edit은 이번 릴리스에 연결되지 않았고 GROK_MASK_UNSUPPORTED를 반환합니다.

Grok 비디오

Grok 비디오 생성 기본값은 정식 grok-imagine-video-1.5입니다. grok-imagine-video는 Ref2V·edit·extension 호환 경로에서 계속 사용합니다. 기존 grok-imagine-video-1.5-preview 값은 호환 alias로만 받습니다. 세 가지 모드가 레퍼런스 수에서 자동 감지됩니다: text-to-video (0개), image-to-video (1개), reference-to-video (2–7개, 최대 10초). 컨트롤: 길이(1–15초), 해상도(480p, 720p, 1.5 단일 이미지/프레임 I2V의 1080p), 화면비. 1.5는 Ref2V, V2V edit, extension 지원을 추가하지 않으므로 해당 경로는 기본 모델만 사용합니다. 비디오 설정 또는 CLI --planner-model로 플래너 모델을 고를 수 있습니다. 엔드포인트 POST /api/video/generate는 SSE 이벤트를 스트리밍합니다: planning → submitted → progress → done. CLI: ima2 video "prompt" --model grok/grok-imagine-video-1.5 --duration 5 --resolution 720p (한 번만 ima2 defaults set video grok/grok-imagine-video-1.5로 기본값을 잡아두면 이후엔 생략 가능).

MCP 레인 (Runway, Higgsfield)

3.0.0부터 CLI는 원격 MCP 프로바이더 두 레인을 추가로 라우팅합니다: runway(Gen-4/4.5, Veo 3.1, Seedance 2, Kling — 이미지·비디오)와 higgsfield(유료 플랜 전까지 카탈로그 전용). ima2 models로 레인 상태와 모델별 capability를 확인한 뒤 다른 레인처럼 지정하면 됩니다: ima2 video "prompt" --model runway/veo-3.1 --duration 8. MCP 작업은 비동기라서 CLI가 POST /api/mcp/generate로 제출하고 공용 SSE 이벤트 스트림에서 완료를 기다린 뒤 갤러리에 파일이 저장됩니다.

Grok 청구 & 계정 전환

설정의 QuotaCard에서 Grok 청구 현황($used/$limit)과 월간 사용량 바를 확인할 수 있습니다. Switch Account 버튼을 누르면 server-side device-code 흐름으로 xAI OAuth 재인증이 시작됩니다 — 새 탭이 열리고, 표시된 device code를 확인한 뒤 서버가 폴링해 자동 완료합니다. Codex(GPT OAuth) 계정도 동일한 흐름으로 전환할 수 있습니다.

Gemini API (직접)

provider: "gemini-api"는 Google Generative Language API 또는 Vertex AI를 직접 호출합니다.

• 모델: nano-banana-2(Gemini 3.1 Flash Image) 또는 nano-banana-pro(Gemini 3 Pro Image). UI의 2열 모델 선택기로 전환합니다.
• 화면비: 1:1·2:3·3:2·3:4·4:3·4:5·5:4·9:16·16:9·21:9 — 10개 버튼.
• 해상도(imageSize): 512px·1K·2K·4K — 화면비와 조합해 정확한 픽셀 크기로 매핑됩니다.
• 비용 예상: Flash(nano-banana-2): 512px=$0.045, 1K=$0.067, 2K=$0.101, 4K=$0.151. Pro(nano-banana-pro): 1K/2K=$0.134, 4K=$0.240 (이미지당).
• 인증: API key(GEMINI_API_KEY 또는 웹 UI) 또는 Vertex AI 서비스 계정 JSON. 둘 다 설정된 경우 Vertex AI가 우선합니다. 인증 모드는 마지막으로 저장한 설정이 영속됩니다.
• Vertex AI 제한: Vertex 경로(aiplatform.googleapis.com)는 response_format 필드를 지원하지 않아 화면비·해상도 요청이 무시됩니다 — 출력은 기본 1K/1:1로 고정됩니다. 직접 API 경로는 화면비·해상도를 모두 반영합니다.

API 프로바이더 기본값

API 경로를 명시적 옵션 없이 사용하면 다음 기본값이 적용됩니다:

전체 환경 변수 표는 설정을 보세요.