핵심 개념

프로바이더 & 모델

이미지 생성은 네 프로바이더 경로 중 하나로 실행됩니다: 로컬 Codex/ChatGPT OAuth 로그인, 설정된 OpenAI API key, 번들 Grok/progrok xAI 경로, 또는 Google Gemini(Antigravity CLI 또는 직접 API).

프로바이더 경로

• 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.3, 설정 또는 --planner-model로 변경)를 거친 뒤 xAI Images API를 호출합니다.
• 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이 필요합니다.

OAuth, API key, Grok, Gemini 생성은 Classic, Node, Agent Mode를 지원합니다. Agent Mode는 웹 UI 전용이고, Classic과 Node는 CLI도 있습니다.

요청 단위 오버라이드

생성 명령은 --provider <auto|oauth|api|grok|grok-api|agy|gemini-api>를 받습니다:

모델

앱은 빠른 로컬 반복을 위해 gpt-5.4-mini를 기본값으로 씁니다. 가장 안전한 균형 워크플로에는 gpt-5.4로 전환하세요.

앱은 품질(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.3, IMA2_GROK_PLANNER_MODEL·설정 UI·비디오 CLI의 --planner-model로 변경)로 영어 최종 이미지 프롬프트를 만든 뒤, xAI 이미지 생성. 텍스트만 있는 요청은 /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(기본) 또는 정식 grok-imagine-video-1.5를 사용합니다. 기존 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" --duration 5 --resolution 720p.

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 경로를 명시적 옵션 없이 사용하면 다음 기본값이 적용됩니다:

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