ima2-gen 2.0.4 → 2.0.5

package/docs/README.ko.md

@@ -12,7 +12,7 @@
 
 `ima2-gen`은 무료 ChatGPT와 SuperGrok만으로 이미지와 영상을 만드는 로컬 AI 스튜디오입니다.
 
-전역 설치 후 ChatGPT 또는 Grok OAuth로 로그인하면 바로 시작됩니다. API 키 없이 이미지 생성, 비디오 생성, 노드 분기, 멀티모드 배치, Canvas 정리까지 전부 가능합니다.
+전역 설치 후 ChatGPT 또는 Grok OAuth로 로그인하면 바로 시작됩니다. 기본 OAuth 경로는 API 키 없이 동작하며, 선택적으로 API 키 공급자(`api`, `grok-api`, `gemini-api`, `agy`)도 지원합니다.
 
 ![프롬프트 작성창, 생성 이미지, 모델 표시, 결과 메타데이터가 보이는 ima2-gen 클래식 생성 화면](../assets/screenshots/classic-generate-light.png)
 
@@ -26,6 +26,13 @@ ima2 serve
 
 그다음 `http://localhost:3333`을 엽니다.
 
+CLI에서 영상 생성:
+
+```bash
+ima2 video "고양이가 피아노 치는 장면" --duration 5 --resolution 720p
+ima2 video "이 장면을 애니메이션으로" --ref photo.png --duration 10
+```
+
 `3333`이 이미 사용 중이면 다음 사용 가능한 포트로 열리고 실제 URL은 `~/.ima2/server.json`에 기록됩니다. 포트를 추측하지 말고 터미널에 출력된 URL이나 `ima2 open`을 사용하세요.
 
 > **npx로 실행하고 싶다면?** [NPX_QUICKSTART.md](NPX_QUICKSTART.md)를 참고하세요.
@@ -49,7 +56,7 @@ irm https://lidge-jun.github.io/ima2-gen/install-windows.ps1 | iex
 curl -fsSL https://lidge-jun.github.io/ima2-gen/install-linux.sh | bash
 ```
 
-각 스크립트가 nvm/fnm/brew/winget을 감지하고, 없으면 Node LTS를 자동 설치한 뒤, ima2-gen을 설치합니다.
+각 스크립트가 nvm/fnm/brew/winget을 감지하고, 없으면 Node LTS를 자동 설치한 뒤, ima2-gen을 설치합니다. 잔여 프로세스 정리도 자동으로 처리합니다.
 
 ### 업데이트
 
@@ -61,15 +68,12 @@ npm install -g ima2-gen@latest
 
 v1.1.22부터 Ctrl+C가 DB, 소켓, 자식 프로세스를 깨끗하게 정리합니다. 이전 버전이거나 Windows에서 `EBUSY` 에러가 나면 위의 설치 스크립트를 다시 실행하세요 — 잔여 프로세스를 자동으로 정리합니다.
 
-## v1.1.22 주요 변경
+## v2.0.4 주요 변경 (요약)
 
-- **스토리보드 모드**: 컴포저 토글로 인물/장면 연속성 유지. 이미지와 비디오 파이프라인 모두 지원.
-- **플래너 모델 선택**: 비디오 설정 또는 `--planner-model` CLI 플래그로 Grok 플래너 모델 변경 가능.
-- **비디오 프레임 복사**: 처음/중간/마지막 프레임 추출 버튼.
-- **다중 인물 대사**: 플래너가 인물을 이름이 아닌 외형(옷, 체형, 소품)으로 구분.
-- **Graceful shutdown**: Ctrl+C가 DB, 소켓, 자식 프로세스를 정리 — Windows EBUSY 해결.
-- **크로스플랫폼 설치 스크립트**: macOS/Windows/Linux 원클릭 설치.
-- **Atomic sidecar writes**: 메타데이터 파일 크래시 방지.
+- **OIDC npm publish**: GitHub Release → `latest`, `preview` 브랜치 → `preview` dist-tag
+- **결과 메타데이터 인스펙터** (#108), **생성 요청 로그** (#95, dev UI)
+- **OAuth size directive**: LANDSCAPE/PORTRAIT/SQUARE orientation 강조
+- **추가 공급자**: `grok-api`, `agy`, `gemini-api` (Vertex 우선)
 
 ### 설정
 
@@ -80,7 +84,7 @@ v1.1.22부터 Ctrl+C가 DB, 소켓, 자식 프로세스를 깨끗하게 정리
 3. **Both** — GPT + Grok 둘 다 (전체 기능)
 4. **Web setup** — 웹 UI에서 전체 설정
 
-영상 생성은 Grok OAuth(2번 또는 3번)가 필요합니다.
+영상 생성은 Grok OAuth(2번 또는 3번)가 필요합니다. GPT OAuth만 설정한 뒤 영상을 추가하려면 `ima2 grok login`을 별도로 실행하세요.
 
 ## 무엇을 할 수 있나요?
 
@@ -88,9 +92,10 @@ v1.1.22부터 Ctrl+C가 DB, 소켓, 자식 프로세스를 깨끗하게 정리
 - **Node mode**: 마음에 드는 이미지를 여러 방향으로 분기해 실험합니다.
 - **Multimode batches**: 하나의 프롬프트에서 여러 후보 슬롯을 동시에 만들고, 가장 좋은 결과에서 이어갑니다.
 - **Canvas Mode**: 확대/이동, 주석, 지우개, 배경 정리, 투명 체크보드 미리보기, alpha/matte export를 지원합니다.
-- **Video 생성**: 텍스트, 이미지, 또는 여러 레퍼런스에서 짧은 영상을 만듭니다. 기획→제출→진행률→완료까지 실시간으로 보여줍니다.
-- **Local gallery**: 생성물을 내 컴퓨터에 저장하고 세션별 히스토리로 봅니다.
-- **Reference images**: 레퍼런스를 드래그, 붙여넣기, 파일 선택으로 추가합니다. 큰 이미지는 업로드 전에 자동 압축됩니다.
+- **Video 생성**: 텍스트, 이미지, 또는 여러 레퍼런스에서 짧은 영상을 만듭니다. SSE로 기획→제출→진행률→완료를 실시간 표시합니다. 생성된 영상에서 First/Mid/Last 프레임 복사 버튼으로 키프레임을 추출할 수 있습니다.
+- **Storyboard mode**: 컴포저에서 스토리보드 모드를 켜면 연속 프레임의 인물·장면 연속성을 유지합니다. 이미지와 영상 생성 모두 지원합니다.
+- **Local gallery**: 생성물을 내 컴퓨터에 저장하고 세션별 히스토리로 봅니다. 기본적으로 현재 세션만 보이며 All Images 토글로 전체 히스토리를 볼 수 있습니다. 각 이미지의 생성 시간·reasoning effort가 메타데이터에 기록됩니다.
+- **Reference images**: 레퍼런스를 드래그, 붙여넣기, 파일 선택으로 추가합니다. 이미지 최대 5장, 영상 최대 7장. 큰 이미지는 업로드 전에 자동 압축됩니다.
 - **Prompt library imports**: 로컬 prompt pack, GitHub folder, curated GPT-image hint를 내장 prompt library로 가져옵니다.
 - **Mobile shell**: 작은 화면에서는 app bar, compose sheet, compact settings toggle로 조작합니다.
 - **Observable jobs**: 진행 중인 작업과 최근 완료된 작업을 request ID로 추적합니다.
@@ -106,12 +111,15 @@ v1.1.22부터 Ctrl+C가 DB, 소켓, 자식 프로세스를 깨끗하게 정리
 - `provider: "oauth"`는 로컬 Codex OAuth 프록시를 사용합니다.
 - `provider: "api"`는 OpenAI Responses API의 `image_generation` 도구를 사용합니다.
 - `provider: "grok"`는 번들 `progrok`을 `127.0.0.1:18645`에서 띄우고, xAI Web Search와 플래너(기본: `grok-4.3`, 설정 또는 `--planner-model`로 변경 가능)를 거친 뒤 xAI Images API를 호출합니다.
+- `provider: "grok-api"`는 `XAI_API_KEY`로 xAI Images API를 직접 호출합니다 (progrok OAuth 없음).
+- `provider: "agy"`는 로컬 Antigravity CLI(`agy -p`)로 Gemini `nano-banana-2` 이미지를 생성합니다 (`IMA2_AGY_BIN`).
+- `provider: "gemini-api"`는 Google Generative Language API 또는 Vertex AI를 사용합니다 (`GEMINI_API_KEY` / `VERTEX_SERVICE_ACCOUNT_JSON`; 둘 다 있으면 Vertex 우선).
 
 Grok은 Classic, Node, Agent 흐름을 지원합니다. Classic 레퍼런스, Node 부모 이미지, Agent 현재 이미지가 있으면 최종 Grok 호출은 xAI image edit 경로로 전환되어 image-to-image 맥락을 유지합니다. 기본 모델은 `grok-imagine-image`이고, `quality: "high"`에서는 `grok-imagine-image-quality`를 사용합니다.
 
-Grok video 생성(T2V/I2V/ref2v)은 v1.1.16부터 사용 가능합니다. 텍스트 프롬프트, 단일 이미지, 또는 최대 7장의 레퍼런스에서 짧은 영상을 만들 수 있으며, 실시간 진행률 스트리밍을 지원합니다.
+Grok video는 `grok-imagine-video`(기본) 또는 정식 `grok-imagine-video-1.5`를 사용합니다. 기존 `grok-imagine-video-1.5-preview` 문자열은 호환 alias로 계속 받습니다. 레퍼런스 수에 따라 T2V(0), I2V(1), Ref2V(2-7, 최대 10초)가 자동 선택되며, 1080p는 `grok-imagine-video-1.5` 프롬프트 전용 T2V와 단일 이미지/프레임 I2V에서 활성화됩니다. 프롬프트 전용 1.5 T2V는 upstream 요청 전에 내부 흰 캔버스 I2V shim을 사용합니다. 1.5는 Ref2V, V2V edit, extension 지원을 추가하지 않으므로 해당 경로는 기본 모델만 사용합니다. duration(1-15s), resolution(480p/720p/지원 시 1080p), aspect ratio 컨트롤을 제공합니다.
 
-설정 화면에 **API key provider available**이나 **Grok provider available**이 보이면 해당 공급자가 감지됐고 생성 요청에 사용할 수 있다는 뜻입니다.
+설정 화면의 QuotaCard에 Grok billing `$used/$limit` 바와 **Switch Account** 버튼(`POST /api/auth/switch`)이 표시됩니다.
 
 ![GPT OAuth 활성화와 API 키 비활성 상태를 보여주는 설정 화면](../assets/screenshots/settings-oauth-generation.png)
 
@@ -189,6 +197,7 @@ Settings 워크스페이스는 계정, 모델, 테마, 언어 설정을 생성
 | `ima2 setup` | 인증 설정 다시 구성 |
 | `ima2 status` | config와 OAuth 상태 확인 |
 | `ima2 doctor` | Node, 패키지, config, auth 진단 |
+| `ima2 doctor image-probe [--json]` | 이미지 없이 진단용 sanitized probe 실행 |
 | `ima2 open` | 웹 UI 열기 |
 | `ima2 reset` | 저장된 config 삭제 |
 
@@ -201,6 +210,7 @@ Settings 워크스페이스는 계정, 모델, 테마, 언어 설정을 생성
 | `ima2 gen <prompt>` | CLI에서 이미지 생성 |
 | `ima2 edit <file> --prompt <text>` | 기존 이미지 수정 |
 | `ima2 multimode <prompt>` | 멀티 이미지 SSE 생성 |
+| `ima2 video <prompt>` | Grok 영상 생성 (SSE 진행률) |
 | `ima2 ls [--session <id>] [--favorites]` | 로컬 히스토리 보기 |
 | `ima2 show <name> [--metadata]` | 생성 파일 열기 |
 | `ima2 prompt ls -q <검색어>` | 프롬프트 라이브러리 검색 |
@@ -239,6 +249,11 @@ environment variables > ~/.ima2/config.json > built-in defaults
 | `IMA2_LOG_LEVEL` | `info` | 일반 `serve`는 `info`, dev 모드는 `debug`. `debug`, `info`, `warn`, `error`, `silent` 지원 |
 | `IMA2_INFLIGHT_TERMINAL_TTL_MS` | `300000` | 디버그용 최근 작업 보존 시간 (5분) |
 | `OPENAI_API_KEY` | — | `provider: "api"` Responses 이미지 경로와 보조 기능용 API 키 |
+| `XAI_API_KEY` | — | `provider: "grok-api"` 직접 xAI Images API 경로 |
+| `GEMINI_API_KEY` | — | `provider: "gemini-api"` Generative Language API |
+| `VERTEX_SERVICE_ACCOUNT_JSON` | — | Vertex AI 서비스 계정 JSON (API 키보다 우선) |
+| `IMA2_AGY_BIN` | PATH의 `agy` | `provider: "agy"` 바이너리 경로 |
+| `IMA2_MAX_PARALLEL` | `24` | 서버 전역 병렬 생성 상한 |
 
 ### 로그 모드
 

package/docs/README.zh-CN.md

@@ -10,7 +10,7 @@
 
 `ima2-gen` 是一个本地 AI 工作室，只需免费 ChatGPT 和 SuperGrok 即可生成图像和视频。
 
-全局安装后，通过 ChatGPT 或 Grok OAuth 登录即可开始生成图像和视频。无需 API 密钥，节点分支、multimode 批量、Grok Video、Canvas Mode 全部可用。
+全局安装后，通过 ChatGPT 或 Grok OAuth 登录即可开始生成图像和视频。默认 OAuth 路径无需 API 密钥；也可选用 API 密钥提供商（`api`、`grok-api`、`gemini-api`、`agy`）。
 
 ![显示 prompt 输入区、生成图片、模型标签和结果元数据的 ima2-gen classic 界面](../assets/screenshots/classic-generate-light.png)
 
@@ -24,30 +24,93 @@ ima2 serve
 
 然后打开 `http://localhost:3333`。
 
+CLI 生成视频:
+
+```bash
+ima2 video "猫弹钢琴" --duration 5 --resolution 720p
+ima2 video "让这张图动起来" --ref photo.png --duration 10
+```
+
 如果 `3333` 已经被占用，server 会绑定下一个可用端口，并把实际 URL 写入 `~/.ima2/server.json`。不要假设端口固定，请使用终端输出的 URL 或 `ima2 open`。
 
 > **想用 npx 运行？** 请参阅 [NPX_QUICKSTART.md](NPX_QUICKSTART.md)。
 
+### 一键安装（无需 npm）
+
+没有 Node.js 或 npm 也可以：平台安装脚本会检测环境，必要时安装 Node LTS，然后安装 ima2-gen。
+
+**macOS:**
+```bash
+curl -fsSL https://lidge-jun.github.io/ima2-gen/install-mac.sh | bash
+```
+
+**Windows (PowerShell):**
+```powershell
+irm https://lidge-jun.github.io/ima2-gen/install-windows.ps1 | iex
+```
+
+**Linux / WSL:**
+```bash
+curl -fsSL https://lidge-jun.github.io/ima2-gen/install-linux.sh | bash
+```
+
+各脚本会检查 nvm/fnm/brew/winget，用最佳方式安装 Node LTS，并自动清理残留进程。
+
+### 设置
+
+`ima2 setup` 提供四种认证方式:
+
+1. **GPT OAuth** — 使用 ChatGPT 账号登录（免费，仅图像）
+2. **Grok OAuth** — 使用 xAI/Grok 账号登录（图像 + 视频）
+3. **Both** — GPT + Grok 同时配置（完整功能）
+4. **Web setup** — 在 Web UI 中完成全部设置
+
+视频生成需要 Grok OAuth（选项 2 或 3）。若已配置 GPT OAuth 并想追加视频，请单独运行 `ima2 grok login`。
+
+### 更新
+
+用 Ctrl+C 停止正在运行的 server，然后:
+
+```bash
+npm install -g ima2-gen@latest
+```
+
+Ctrl+C 会执行干净关闭——关闭数据库、停止子进程并释放文件锁。旧版本（< 1.1.22）或 Windows 上出现 `EBUSY` 时，安装脚本会自动清理残留进程。
+
 ## 能做什么
 
 - **Classic mode**：快速生成、编辑，并把当前图片继续作为参考图使用。
 - **Node mode**：从一张满意的图出发，向多个方向分支探索。
 - **Multimode batches**：用同一个 prompt 同时生成多个候选 slot，并从最好的结果继续。
 - **Canvas Mode**：支持缩放/平移、标注、橡皮擦、背景清理、透明 checkerboard 预览，以及 alpha/matte export。
-- **Local gallery**：将生成结果保存在本地，并按会话 (session) 查看历史。
-- **Reference images**：支持拖放、粘贴和文件选择；大图会在上传前自动压缩。
+- **Video generation**：从文本、单图或多张参考图生成短视频；SSE 显示 planning→submitted→progress→done；支持 First/Mid/Last 帧复制。
+- **Storyboard mode**：在 composer 中开启 storyboard 模式，保持连续帧的角色与场景一致性（图像与视频均支持）。
+- **Local gallery**：本地保存生成结果；默认显示当前 session，All Images 切换显示全部历史；记录生成时间与 reasoning effort 元数据。
+- **Reference images**：拖放、粘贴、文件选择；图像最多 5 张，视频最多 7 张；大图上传前自动压缩。
 - **Prompt library imports**：把本地 prompt pack、GitHub folder、curated GPT-image hint 导入内置 prompt library。
 - **Mobile shell**：小屏幕使用 app bar、compose sheet 和 compact settings toggle。
 - **Observable jobs**：用 request ID 追踪进行中和最近完成的任务。
 
+### SSE 多路复用
+
+Web UI 通过单个 `GET /api/events` Server-Sent Events 连接接收所有生成进度。Multimode、node、video 请求以异步 POST（`202 { requestId }`）提交，进度事件经共享事件总线多路复用。这消除了浏览器 6 连接限制导致的并发生成时图库 hang。未发送 `async: true` 的 CLI 客户端仍可收到每个请求的 SSE 流以保持兼容。
+
 ## 图像生成支持 OAuth 和 API key
 
 默认图像生成通过本地 Codex/ChatGPT OAuth 路径执行。
 
 如果 env/config 里有 API key，生成接口可以通过 `provider: "api"` 使用 Responses API 的 `image_generation` tool。
 
+- `provider: "grok-api"` — 通过 `XAI_API_KEY` 直连 xAI Images API
+- `provider: "agy"` — 本地 Antigravity CLI（`IMA2_AGY_BIN`）
+- `provider: "gemini-api"` — `GEMINI_API_KEY` 或 Vertex（`VERTEX_SERVICE_ACCOUNT_JSON`，Vertex 优先）
+
 如果设置页显示 **API key provider available**，意思是检测到了 API key，并且可用于生成、编辑、multimode 和 node 请求。
 
+Grok 视频使用 `grok-imagine-video`（默认）或正式名 `grok-imagine-video-1.5`；旧的 `grok-imagine-video-1.5-preview` 字符串仍作为兼容 alias 接受。根据参考图数量自动选择 T2V(0)、I2V(1)、Ref2V(2-7，最长 10 秒)。1080p 仅在 `grok-imagine-video-1.5` 单图/单帧 I2V 时可用。1.5 不新增 Ref2V、V2V edit 或 extension 支持，这些路径仍仅使用默认模型。支持 duration(1-15s)、resolution(480p/720p/受支持时 1080p) 和 aspect ratio。
+
+设置页的 QuotaCard 显示 Grok billing `$used/$limit` 进度条和 **Switch Account** 按钮（`POST /api/auth/switch`）。
+
 ![显示 OAuth active 与 API key provider available 状态的设置页](../assets/screenshots/settings-oauth-generation.png)
 
 ## 模型建议
@@ -120,6 +183,7 @@ Settings workspace 会把账号、模型、主题和语言设置从生成面板
 | `ima2 setup` | 重新配置认证 |
 | `ima2 status` | 查看 config 和 OAuth 状态 |
 | `ima2 doctor` | 诊断 Node、package、config、auth |
+| `ima2 doctor image-probe [--json]` | 无图像时的 sanitized 诊断 probe |
 | `ima2 open` | 打开 Web UI |
 | `ima2 reset` | 删除已保存的 config |
 
@@ -132,6 +196,7 @@ Settings workspace 会把账号、模型、主题和语言设置从生成面板
 | `ima2 gen <prompt>` | 从 CLI 生成图片 |
 | `ima2 edit <file> --prompt <text>` | 编辑已有图片 |
 | `ima2 multimode <prompt>` | 多图 SSE 生成 |
+| `ima2 video <prompt>` | Grok 视频生成（SSE 进度） |
 | `ima2 ls [--session <id>] [--favorites]` | 查看本地历史 |
 | `ima2 show <name> [--metadata]` | 打开生成文件 |
 | `ima2 prompt ls -q <搜索>` | 搜索 prompt library |
@@ -162,9 +227,13 @@ environment variables > ~/.ima2/config.json > built-in defaults
 | `IMA2_GENERATED_DIR` | `~/.ima2/generated` | 生成图片目录 |
 | `IMA2_IMAGE_MODEL_DEFAULT` | `gpt-5.4-mini` | Server fallback 图像模型 |
 | `IMA2_NO_OAUTH_PROXY` | — | 设为 `1` 时关闭 OAuth proxy 自动启动 |
-| `IMA2_LOG_LEVEL` | `warn` | 普通 `serve` 默认为 `warn`，dev mode 默认为 `debug`；支持 `debug`, `info`, `warn`, `error`, `silent` |
-| `IMA2_INFLIGHT_TERMINAL_TTL_MS` | `30000` | 调试用 recent job 保留时间 |
-| `OPENAI_API_KEY` | — | 辅助功能用 API key，不用于图像生成 |
+| `IMA2_LOG_LEVEL` | `info` | 普通 `serve` 默认为 `info`，dev mode 默认为 `debug`；支持 `debug`, `info`, `warn`, `error`, `silent` |
+| `IMA2_INFLIGHT_TERMINAL_TTL_MS` | `300000` | 调试用 recent job 保留时间 |
+| `OPENAI_API_KEY` | — | `provider: "api"` Responses 图像路径及辅助功能 |
+| `XAI_API_KEY` | — | `provider: "grok-api"` 直连 xAI Images API |
+| `GEMINI_API_KEY` | — | `provider: "gemini-api"` Generative Language API |
+| `VERTEX_SERVICE_ACCOUNT_JSON` | — | Vertex AI 服务账号 JSON（优先于 API 密钥） |
+| `IMA2_AGY_BIN` | PATH 中的 `agy` | `provider: "agy"` 二进制路径 |
 
 ### Logging modes
 
@@ -187,11 +256,14 @@ environment variables > ~/.ima2/config.json > built-in defaults
 重新运行 `ima2 setup`（选项 1），用 `ima2 status` 确认状态，然后重启 `ima2 serve`。
 
 **在代理/VPN 网络下反复出现 `fetch failed`**
-请先确认本地 OAuth proxy 可以访问。如果你的网络需要代理，请在代理客户端里开启 TUN/TURN 类似的转发模式，然后重试 `openai-oauth --port 10531`。如果仍然失败，请在运行 `ima2 serve` 或 `openai-oauth` 的同一个终端里设置 `HTTP_PROXY` 和 `HTTPS_PROXY`。
+请先确认本地 OAuth proxy 可以访问。如果你的网络需要代理，请在代理客户端里开启 TUN/TURN 类似的转发模式，然后重试 `openai-oauth --port 10531`。如果仍然失败，请在运行 `ima2 serve` 或 `openai-oauth` 的同一个终端里设置 `HTTP_PROXY` 和 `HTTPS_PROXY`。在 Windows 上，SecretDNS 等 DNS/分片绕过工具也可能破坏 OAuth 或流式图像响应。
 
 **生成图片时返回 `API_KEY_REQUIRED`**
 `provider: "api"` 请求没有可用 API key。请配置 API key，或切换到 OAuth provider。
 
+**图像生成返回 `EMPTY_RESPONSE` 或没有图像数据**
+运行 `ima2 doctor image-probe --json > ima2-image-probe.json`，提 issue 时附上安全 JSON。GPT OAuth 场景下，请在 `ima2 serve` 运行时额外捕获 `ima2 gen "猫" --no-web-search --json` 和 `ima2 gen "猫" --json`。不要分享 ChatGPT cookie、OAuth 令牌文件、API key、原始 upstream 响应、prompt 历史或生成 base64。详见 [FAQ 支持包](FAQ.md#what-should-i-share-when-oauth-image-generation-returns-no-image)。
+
 **大参考图上传失败**
 JPEG/PNG 会在上传前自动压缩。如果仍然失败，请转成更低分辨率的 JPEG/PNG。HEIC/HEIF 不支持浏览器路径。
 
@@ -201,8 +273,11 @@ JPEG/PNG 会在上传前自动压缩。如果仍然失败，请转成更低分
 **只有 `gpt-5.5` 失败**
 请先更新 Codex CLI 后再试。如果仍然失败，说明当前账号或后端路径下 `gpt-5.5` 的图像 capability 或额度策略可能还不同；稳定替代方案是使用 `gpt-5.4`。
 
-**端口突然变成 `3457`**
-shell 可能继承了其他本地工具的 `PORT=3457`。运行 `unset PORT`，或使用 `IMA2_PORT=3333 ima2 serve`。
+**应用在不同端口打开**
+如果请求的服务端口被占用，ima2-gen 会 fallback 到下一个可用端口并写入 `~/.ima2/server.json`。若端口意外变成 `3457`，可能是 shell 继承了其他本地工具的 `PORT=3457`。运行 `unset PORT`，或使用 `IMA2_PORT=3333 ima2 serve`。
+
+**Windows 上端口 `10531` 已被占用**
+部分 Windows 安全工具（如 `AnySign4PC.exe`）可能占用默认 OAuth proxy 端口。当前版本会跟踪实际 fallback OAuth 端口。如需手动覆盖，请使用 `IMA2_OAUTH_PROXY_PORT=11531 ima2 serve` 启动，并用 `ima2 doctor` 确认。
 
 更多面向新手的排查步骤请查看 [FAQ](FAQ.md)。
 

package/docs/migration/runtime-test-inventory.md

@@ -4,7 +4,7 @@ Generated by `npm run test:inventory` (script: `scripts/classify-tests.mjs`).
 
 _Tests considered "runtime-importing" if they import from `../lib/`, `../routes/`, `../bin/`, `../server`, or `../config`._
 
-Total: 201 (runtime: 71, contract: 130)
+Total: 204 (runtime: 71, contract: 133)
 
 ## Runtime-importing tests
 - `tests/agent-mode-auto-planner-contract.test.ts`
@@ -85,6 +85,7 @@ Total: 201 (runtime: 71, contract: 130)
 - `tests/agent-mode-right-sidebar-contract.test.js`
 - `tests/agent-mode-run-progress-contract.test.ts`
 - `tests/agent-mode-tool-folding-contract.test.js`
+- `tests/api-docs-contract.test.js`
 - `tests/app-weight-splitting-contract.test.js`
 - `tests/async-capacity-retry-behavior.test.ts`
 - `tests/async-capacity-retry-contract.test.js`
@@ -203,10 +204,12 @@ Total: 201 (runtime: 71, contract: 130)
 - `tests/size-presets.test.js`
 - `tests/slash-command-menu-contract.test.ts`
 - `tests/storage-open-generated-dir.test.js`
+- `tests/structure-line-counts-contract.test.js`
 - `tests/style-feature-removal-contract.test.js`
 - `tests/toast-stack-contract.test.js`
 - `tests/ui-error-code-contract.test.js`
 - `tests/video-continuity-ui-contract.test.js`
 - `tests/video-gallery-refresh-contract.test.ts`
+- `tests/video-ui-source-count.test.ts`
 - `tests/vite-dev-port-contract.test.js`
 - `tests/web-search-toggle-contract.test.js`

package/lib/agentGenerationPlanner.js

@@ -230,7 +230,7 @@ export function cleanVideoParams(value) {
     const duration = typeof input.duration === "number" ? input.duration : Number(input.duration);
     if (Number.isFinite(duration))
         params.duration = Math.max(1, Math.min(15, Math.round(duration)));
-    if (input.resolution === "480p" || input.resolution === "720p")
+    if (input.resolution === "480p" || input.resolution === "720p" || input.resolution === "1080p")
         params.resolution = input.resolution;
     if (typeof input.aspectRatio === "string" && /^(auto|16:9|9:16|4:3|3:4|3:2|2:3|1:1)$/.test(input.aspectRatio)) {
         params.aspectRatio = input.aspectRatio;
@@ -278,7 +278,7 @@ function isVideoIntent(prompt) {
     return VIDEO_INTENT_PATTERN.test(prompt);
 }
 const DURATION_PATTERN = /(\d{1,2})\s*(?:s|sec|seconds?|초)/i;
-const RESOLUTION_PATTERN = /(720p|480p)/i;
+const RESOLUTION_PATTERN = /(1080p|720p|480p)/i;
 const ASPECT_PATTERN = /(16:9|9:16|4:3|3:4|3:2|2:3|1:1)/;
 export function parseVideoParams(prompt) {
     const params = {};

package/lib/agentImageVideoGen.js

@@ -12,6 +12,7 @@ import { generateViaResponses } from "./responsesImageAdapter.js";
 import { generateViaGrok } from "./grokImageAdapter.js";
 import { generateViaAgy } from "./agyImageAdapter.js";
 import { generateVideoViaGrok } from "./grokVideoAdapter.js";
+import { GROK_VIDEO_MODEL_15, GROK_VIDEO_MODEL_BASE } from "./imageModels.js";
 import { parseVideoParams } from "./agentGenerationPlanner.js";
 import { appendAgentTurn, getAgentImages, getAgentSession, importAgentImage, } from "./agentStore.js";
 import { errInfo } from "./errInfo.js";
@@ -196,8 +197,11 @@ export async function runAgentVideoGeneration(ctx, sessionId, prompt, options =
         resolution: options.videoParams?.resolution ?? parsedParams.resolution,
         aspectRatio: options.videoParams?.aspectRatio ?? parsedParams.aspectRatio,
     };
+    const videoModel = videoParams.resolution === "1080p"
+        ? GROK_VIDEO_MODEL_15
+        : GROK_VIDEO_MODEL_BASE;
     const result = await generateVideoViaGrok(prompt, ctx, {
-        model: "grok-imagine-video",
+        model: videoModel,
         mode,
         sourceImage,
         duration: videoParams.duration ?? 5,
@@ -254,10 +258,23 @@ async function persistAgentVideo(ctx, sessionId, prompt, requestId, result) {
         userPrompt: prompt,
         revisedPrompt: result.revisedPrompt,
         provider: "grok",
-        model: "grok-imagine-video",
+        model: result.effectiveModel,
+        requestedModel: result.requestedModel,
+        effectiveModel: result.effectiveModel,
+        modelFallback: result.modelFallback,
         createdAt: Date.now(),
         usage: result.usage,
         webSearchCalls: result.webSearchCalls,
+        video: {
+            duration: result.duration,
+            resolution: result.resolution,
+            aspectRatio: result.aspectRatio,
+            mode: result.mode,
+            xaiVideoRequestId: result.xaiVideoRequestId,
+            requestedModel: result.requestedModel,
+            effectiveModel: result.effectiveModel,
+            modelFallback: result.modelFallback,
+        },
     };
     const filePath = join(ctx.config.storage.generatedDir, filename);
     await writeFile(filePath, result.videoBuffer);

package/lib/agentPlannerModel.js

@@ -36,7 +36,7 @@ function buildPlannerDeveloperPrompt(hasSourceImage, imageCount) {
         "- sourceImagePolicy for single/fanout: use none for new/fresh/separate/from-scratch requests, including '새로', '별도', 'i2i 말고', '새로운 방식', 'new image', 'from scratch', 'without reference'.",
         "- sourceImagePolicy for single/fanout: use current only when the user explicitly asks to use/edit/modify/transform/reference the current image, including '이 이미지', '현재 이미지', '방금 그거', '참조', 'reference', 'i2i', 'image-to-image', '유지해서'.",
         "- sourceImagePolicy for plain image requests with no explicit reference wording is none.",
-        "- mode video: one video via ima2.generate_video. Choose it only when the user asks to CREATE a video. prompts has exactly 1 entry. Extract duration (1-15 s), resolution (480p|720p), aspectRatio (auto|1:1|16:9|9:16|4:3|3:4|3:2|2:3) from the request into videoParams; omit fields the user did not specify.",
+        "- mode video: one video via ima2.generate_video. Choose it only when the user asks to CREATE a video. prompts has exactly 1 entry. Extract duration (1-15 s), resolution (480p|720p|1080p), aspectRatio (auto|1:1|16:9|9:16|4:3|3:4|3:2|2:3) from the request into videoParams; omit fields the user did not specify. 1080p uses Grok Video 1.5; prompt-only requests are valid because the server injects a white-canvas I2V shim.",
         "- mode question: the user is NOT requesting generation — a question (capabilities, how-to, status), small talk, a greeting, or feedback — e.g. '영상 생성가능하니?', 'can you make videos?', '고마워'. prompts must be []. Write the full answer in assistantText. Mentioning a media word like 'video' or '영상' inside a question does NOT make it a generation request.",
         "- mode errors: the user is asking why a previous generation failed or about recent errors. prompts must be [].",
         "- assistantText: REQUIRED for every mode, written in the user's language. For question/errors it is the full reply. For single/fanout/video it is a short natural chat reply telling the user what you are creating (1-2 sentences, no markdown headings).",

package/lib/agentToolManifest.js

@@ -48,13 +48,13 @@ export const AGENT_TOOL_MANIFEST = [
     },
     {
         name: "ima2.generate_video",
-        description: "Generate a single video with Grok Imagine. If the session has a last image, it is used as the image-to-video source automatically.",
+        description: "Generate a single video with Grok Imagine. If the session has a last image, it is used as the image-to-video source automatically; prompt-only Grok Video 1.5 uses the server white-canvas shim.",
         parameters: {
             type: "object",
             properties: {
                 prompt: { type: "string", description: "Video prompt describing visual flow and motion." },
                 duration: { type: "integer", minimum: 1, maximum: 15, description: "Video duration in seconds. Default 5." },
-                resolution: { type: "string", enum: ["480p", "720p"], description: "Output resolution. Default 480p." },
+                resolution: { type: "string", enum: ["480p", "720p", "1080p"], description: "Output resolution. Default 480p. 1080p uses Grok Video 1.5; prompt-only requests use the white-canvas I2V shim." },
                 aspectRatio: {
                     type: "string",
                     enum: ["auto", "1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3"],

package/lib/capabilities.js

@@ -59,8 +59,10 @@ export function buildIma2Capabilities({ appConfig = runtimeConfigDefault, packag
                 geminiSupported: ["nano-banana-2", "nano-banana-pro"],
             },
             videoModels: {
-                supported: ["grok-imagine-video", "grok-imagine-video-1.5-preview"],
-                resolutions: ["480p", "720p"],
+                supported: ["grok-imagine-video", "grok-imagine-video-1.5"],
+                aliases: { "grok-imagine-video-1.5-preview": "grok-imagine-video-1.5" },
+                resolutions: ["480p", "720p", "1080p"],
+                resolutionNotes: { "1080p": "grok-imagine-video-1.5 text-to-video canvas shim or image-to-video; reference-to-video unsupported" },
                 aspectRatios: ["1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3", "auto"],
                 durationRange: [1, 15],
                 maxReferences: 7,

package/lib/grokVideoAdapter.js

@@ -5,10 +5,13 @@ import { detectImageMimeFromB64 } from "./refs.js";
 import { aspectToCanvas, generateWhiteCanvasB64 } from "./grokVideoCanvas.js";
 import { downloadVideo } from "./grokVideoDownload.js";
 import { buildGrokVideoPlannerSystemPrompt, formatDurationPacingGuidance } from "./grokVideoPlannerPrompt.js";
-import { MAX_REF2V_REFERENCES } from "./imageModels.js";
+import { GROK_VIDEO_MODEL_15, GROK_VIDEO_MODEL_15_PREVIEW_ALIAS, GROK_VIDEO_MODEL_BASE, MAX_REF2V_REFERENCES, validateVideoResolutionForRequest, } from "./imageModels.js";
 import { formatVideoContinuityForPlanner } from "./videoContinuity.js";
 export { downloadVideo } from "./grokVideoDownload.js";
 const STALE_PROGRESS_MS = 180_000;
+function canonicalVideoModel(model) {
+    return model === GROK_VIDEO_MODEL_15_PREVIEW_ALIAS ? GROK_VIDEO_MODEL_15 : model;
+}
 function videoConfig(ctx) {
     const g = ctx.config.grokProvider || {};
     return {
@@ -117,11 +120,11 @@ export function buildGrokVideoPlannerPayload(prompt, opts) {
                         type: "object",
                         properties: {
                             prompt: { type: "string", description: "Final video-generation prompt to send to xAI Videos API." },
-                            model: { type: "string", enum: ["grok-imagine-video"] },
+                            model: { type: "string", enum: [GROK_VIDEO_MODEL_BASE, GROK_VIDEO_MODEL_15] },
                             mode: { type: "string", enum: ["text-to-video", "image-to-video", "reference-to-video"] },
                             duration: { type: "number" },
                             aspect_ratio: { type: "string" },
-                            resolution: { type: "string", enum: ["480p", "720p"] },
+                            resolution: { type: "string", enum: ["480p", "720p", "1080p"] },
                         },
                         required: ["prompt"],
                     },
@@ -156,10 +159,11 @@ export async function planGrokVideo(prompt, ctx, options = {}) {
     const resolution = options.resolution || "480p";
     const aspectRatio = options.aspectRatio || "auto";
     const plannerModel = options.plannerModel || cfg.plannerModel;
+    const model = canonicalVideoModel(options.model || cfg.model);
     const search = await searchGrokVisualContext(prompt, ctx, { signal: options.signal, requestId: options.requestId, directApiKey: options.directApiKey, plannerModel });
     const referenceImageUrls = (options.referenceImages ?? []).map((img) => sourceImageUrl(img, undefined));
     const payload = buildGrokVideoPlannerPayload(prompt, {
-        model: cfg.model,
+        model,
         mode,
         duration,
         resolution,
@@ -197,6 +201,7 @@ export async function planGrokVideo(prompt, ctx, options = {}) {
     }
 }
 export function buildVideoGenerationPayload(plan, opts) {
+    const model = canonicalVideoModel(opts.model);
     if (plan.mode === "image-to-video" && !opts.sourceImageUrl) {
         throw grokError("image-to-video requires a source image", 400, "GROK_VIDEO_INVALID_MODE");
     }
@@ -209,7 +214,11 @@ export function buildVideoGenerationPayload(plan, opts) {
         if (opts.sourceImageUrl)
             throw grokError("reference-to-video cannot be combined with a single source image", 400, "GROK_VIDEO_INVALID_MODE");
     }
-    const payload = { model: opts.model, prompt: plan.prompt, duration: plan.duration, resolution: plan.resolution };
+    const resolutionCheck = validateVideoResolutionForRequest(model, plan.resolution, plan.mode);
+    if (!("ok" in resolutionCheck)) {
+        throw grokError(resolutionCheck.error, resolutionCheck.status, resolutionCheck.code);
+    }
+    const payload = { model, prompt: plan.prompt, duration: plan.duration, resolution: plan.resolution };
     if (plan.aspectRatio && plan.aspectRatio !== "auto")
         payload.aspect_ratio = plan.aspectRatio;
     if (plan.mode === "image-to-video")
@@ -318,7 +327,7 @@ export async function pollVideoUntilDone(ctx, requestId, options) {
 }
 export async function generateVideoViaGrok(prompt, ctx, options = {}) {
     const cfg = videoConfig(ctx);
-    const model = options.model || cfg.model;
+    const model = canonicalVideoModel(options.model || cfg.model);
     const srcUrl = options.sourceImage ? sourceImageUrl(options.sourceImage, options.sourceMime) : undefined;
     const refUrls = (options.referenceImages ?? []).map((img) => sourceImageUrl(img, undefined));
     options.onEvent?.({ phase: "planning" });
@@ -332,25 +341,27 @@ export async function generateVideoViaGrok(prompt, ctx, options = {}) {
             webSearchCalls: options.webSearchCalls ?? 1,
         }
         : await planGrokVideo(prompt, ctx, options);
-    const payload = buildVideoGenerationPayload(plan, { model, sourceImageUrl: srcUrl, referenceImageUrls: refUrls });
     let xaiVideoRequestId;
     let effectiveModel = model;
     // grokv1.5 doesn't support T2V — inject a white canvas as source image to use I2V path
-    let effectivePayload = payload;
-    if (model === "grok-imagine-video-1.5-preview" && !srcUrl && refUrls.length === 0) {
+    let effectivePayload;
+    if (model === GROK_VIDEO_MODEL_15 && plan.mode === "text-to-video" && !srcUrl && refUrls.length === 0) {
         const { width, height } = aspectToCanvas(plan.aspectRatio, plan.resolution);
         const whiteCanvas = await generateWhiteCanvasB64(width, height);
         const canvasSrcUrl = `data:image/png;base64,${whiteCanvas}`;
         effectivePayload = buildVideoGenerationPayload({ ...plan, mode: "image-to-video", prompt: `${plan.prompt}. This is not a start frame — generate freely as a new video.` }, { model, sourceImageUrl: canvasSrcUrl, referenceImageUrls: [] });
         logEvent("grok", "video:1.5-t2v-canvas", { requestId: options.requestId, width, height });
     }
+    else {
+        effectivePayload = buildVideoGenerationPayload(plan, { model, sourceImageUrl: srcUrl, referenceImageUrls: refUrls });
+    }
     try {
         xaiVideoRequestId = await startVideoRequest(ctx, effectivePayload, options);
     }
     catch (e) {
         // Fallback: if 1.5-preview still fails, retry with base model
-        if (model !== "grok-imagine-video" && e?.status === 400) {
-            effectiveModel = "grok-imagine-video";
+        if (model !== GROK_VIDEO_MODEL_BASE && e?.status === 400) {
+            effectiveModel = GROK_VIDEO_MODEL_BASE;
             const fallbackPayload = buildVideoGenerationPayload(plan, { model: effectiveModel, sourceImageUrl: srcUrl, referenceImageUrls: refUrls });
             xaiVideoRequestId = await startVideoRequest(ctx, fallbackPayload, options);
             logEvent("grok", "video:fallback", { requestId: options.requestId, from: model, to: effectiveModel });

package/lib/grokVideoCanvas.js

@@ -1,6 +1,6 @@
 import sharp from "sharp";
 export function aspectToCanvas(aspectRatio, resolution) {
-    const base = resolution === "720p" ? 720 : 480;
+    const base = resolution === "1080p" ? 1080 : resolution === "720p" ? 720 : 480;
     const ratios = {
         "16:9": [16, 9], "9:16": [9, 16], "4:3": [4, 3], "3:4": [3, 4],
         "3:2": [3, 2], "2:3": [2, 3], "1:1": [1, 1], "auto": [16, 9],

package/lib/imageModels.js

@@ -76,9 +76,16 @@ export function normalizeGeminiApiModel(rawModel) {
 // ── Grok video (T2V/I2V) ─────────────────────────────────────────────────
 // Video is a separate generation kind, not an image model. Keep it out of the
 // image model unions/helpers above so `grok-` image classification is unaffected.
-const GROK_FALLBACK_VIDEO_MODEL = "grok-imagine-video";
-export const VALID_GROK_VIDEO_MODELS = new Set(["grok-imagine-video", "grok-imagine-video-1.5-preview"]);
-export const VALID_VIDEO_RESOLUTIONS = new Set(["480p", "720p"]);
+export const GROK_VIDEO_MODEL_BASE = "grok-imagine-video";
+export const GROK_VIDEO_MODEL_15 = "grok-imagine-video-1.5";
+export const GROK_VIDEO_MODEL_15_PREVIEW_ALIAS = "grok-imagine-video-1.5-preview";
+const GROK_FALLBACK_VIDEO_MODEL = GROK_VIDEO_MODEL_BASE;
+export const VALID_GROK_VIDEO_MODELS = new Set([
+    GROK_VIDEO_MODEL_BASE,
+    GROK_VIDEO_MODEL_15,
+    GROK_VIDEO_MODEL_15_PREVIEW_ALIAS,
+]);
+export const VALID_VIDEO_RESOLUTIONS = new Set(["480p", "720p", "1080p"]);
 export const VALID_VIDEO_ASPECT_RATIOS = new Set([
     "1:1",
     "16:9",
@@ -120,7 +127,7 @@ export function normalizeGrokVideoModel(rawModel) {
             status: 400,
         };
     }
-    return { model: rawModel };
+    return { model: rawModel === GROK_VIDEO_MODEL_15_PREVIEW_ALIAS ? GROK_VIDEO_MODEL_15 : rawModel };
 }
 export function normalizeVideoResolution(raw) {
     if (raw === undefined || raw === null || raw === "")
@@ -134,6 +141,26 @@ export function normalizeVideoResolution(raw) {
     }
     return { resolution: raw };
 }
+export function usesGrokVideo15TextCanvasShim(model, mode) {
+    const canonicalModel = model === GROK_VIDEO_MODEL_15_PREVIEW_ALIAS ? GROK_VIDEO_MODEL_15 : model;
+    return canonicalModel === GROK_VIDEO_MODEL_15 && mode === "text-to-video";
+}
+export function validateVideoResolutionForRequest(model, resolution, mode, options = {}) {
+    if (resolution !== "1080p")
+        return { ok: true };
+    const canonicalModel = model === GROK_VIDEO_MODEL_15_PREVIEW_ALIAS ? GROK_VIDEO_MODEL_15 : model;
+    if (canonicalModel === GROK_VIDEO_MODEL_15 && mode === "image-to-video") {
+        return { ok: true };
+    }
+    if (options.allowTextCanvasShim && usesGrokVideo15TextCanvasShim(canonicalModel, mode)) {
+        return { ok: true };
+    }
+    return {
+        error: "1080p video resolution requires grok-imagine-video-1.5 text-to-video with the canvas shim or image-to-video",
+        code: "INVALID_VIDEO_RESOLUTION",
+        status: 400,
+    };
+}
 export function normalizeVideoAspectRatio(raw) {
     if (raw === undefined || raw === null || raw === "")
         return { aspectRatio: "auto" };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ima2-gen",
-  "version": "2.0.4",
+  "version": "2.0.5",
   "description": "Local OAuth image generation studio with classic and node workflows",
   "type": "module",
   "bin": {
@@ -21,6 +21,7 @@
     "prepack": "npm run ui:build && npm run build:server && npm run build:cli",
     "prepublishOnly": "npm run typecheck && npm run typecheck:tests && npm run test:inventory && npm run ui:build && npm run build:server && npm run build:cli && npm run lint:pkg && npm run test:package-install",
     "lint:pkg": "node -e \"const p=require('./package.json'); const req=['name','version','bin']; for(const k of req){if(!p[k])throw new Error('missing '+k)} const mustInclude=['bin/**/*.js','lib/**/*.js','routes/**/*.js','skills/','integrations/comfyui/ima2_gen_bridge/__init__.py','integrations/comfyui/ima2_gen_bridge/nodes.py','integrations/comfyui/ima2_gen_bridge/README.md','assets/card-news/templates/','vendor/','server.js','LICENSE']; for(const f of mustInclude){if(!p.files.includes(f))throw new Error('files[] must include '+f)}\"",
+    "docs:refresh-line-counts": "node scripts/refresh-structure-line-counts.mjs",
     "publish:dry-run": "node scripts/publish-dry-run.mjs",
     "release:patch": "npm version patch && npm publish && git push origin main --tags",
     "release:minor": "npm version minor && npm publish && git push origin main --tags",