ima2-gen 3.15.1 → 3.16.0

package/docs/CLI.zh-CN.md

@@ -14,7 +14,7 @@
 | `ima2 doctor` |诊断节点、包、配置和身份验证|
 | `ima2 doctor image-probe [--json]` |运行实时清理的响应图像探针`EMPTY_RESPONSE`支持|
 | `ima2 open` |打开网络UI在浏览器中|
-| `ima2 grok login/status/models/proxy` |管理捆绑的progrok使用的运行时Grok提供者|
+| `ima2 grok login/status/logout` |管理`Grok`提供者使用的xAI OAuth会话|
 | `ima2 reset` |删除保存的配置|
 | `ima2 backfill-thumbs` |生成图像和视频缺失的图库缩略图（离线，无需运行服务器）|
 
@@ -82,7 +82,7 @@
 
 - `api`迫使API-key 响应路径并需要配置API钥匙。
 - `oauth`迫使当地OAuth代理路径。
-- `grok`使用捆绑的progrok xAI代理人 （`127.0.0.1:18645`）。经典一代首次运行强制xAI通过响应进行网络搜索API，然后询问`grok-4.5`打电话ima2是当地的`generate_image`工具，那么ima2执行xAI `/v1/images/generations`. `grok-4.3`仍然可以作为显式兼容性覆盖使用。如果`--ref`附加图像，最后一步使用xAI `/v1/images/edits`相反，图像到图像/参考上下文被保留。型号：`grok-imagine-image`, `grok-imagine-image-quality`。大小映射到xAI `aspect_ratio`和`resolution`;这UI网络搜索切换是OpenAI-仅提供者因为Grok搜索始终在此路径中进行。
+- `grok`使用`~/.progrok/auth.json`中的xAI OAuth会话直接调用`https://api.x.ai`。经典一代首次运行强制xAI通过响应进行网络搜索API，然后询问`grok-4.5`打电话ima2是当地的`generate_image`工具，那么ima2执行xAI `/v1/images/generations`. `grok-4.3`仍然可以作为显式兼容性覆盖使用。如果`--ref`附加图像，最后一步使用xAI `/v1/images/edits`相反，图像到图像/参考上下文被保留。型号：`grok-imagine-image`, `grok-imagine-image-quality`。大小映射到xAI `aspect_ratio`和`resolution`;这UI网络搜索切换是OpenAI-仅提供者因为Grok搜索始终在此路径中进行。
 - `agy`产生Antigravity CLI通过Google生成Gemini (`nano-banana-2`）。固定1024×1024JPEG输出，最多 3 个参考值没有网络搜索、质量、尺寸或遮罩控制。如果`agy`不在服务器进程 PATH 上，ima2还检查常见的用户本地安装，例如`~/.local/bin/agy`;放`IMA2_AGY_BIN=/absolute/path/to/agy`强制使用特定的二进制文件。
 - `gemini-api`调用 Google 生成语言API直接地。型号：`nano-banana-2` (Gemini3.1 Flash 图像）和`nano-banana-pro` (Gemini3 专业图像）。使用`--model nano-banana-2`或者`--model nano-banana-pro`来选择。支持`--size`对于直接的宽高比和分辨率 (512px–4K)API小路;Vertex AI忽略方面/大小。需要`GEMINI_API_KEY`或一个Vertex AI服务帐户（`VERTEX_SERVICE_ACCOUNT_JSON`）。切换自`agy`或者`gemini-api`提供商自动选择相应的Gemini模型;切换离开重置为GPT默认。
 - `atlascloud`致电 Atlas Cloud 媒体API直接地。型号：`openai/gpt-image-2/text-to-image`用于文本到图像和`openai/gpt-image-2/edit`当附有参考文献时。需要`ATLASCLOUD_API_KEY`;网络搜索、推理、掩码和视频控制将被忽略。
@@ -90,11 +90,11 @@
 - `runway` / `higgsfield`（仅限生成/视频）路线MCP异步管道（`POST /api/mcp/generate` + SSE等待）。Runway需要一个MCP联系;Higgsfield仅保留目录（`locked`）直到付费计划。MCP车道接受`-n 1`仅，画廊文件名`--ref`，并拒绝仅核心标志`FLAG_NOT_SUPPORTED`.
 - `auto`保留路由默认行为并当前解析为GPT OAuth除非服务器路由发生变化（仅限编辑/多模式/节点；在 3.0.0 中从 gen/video 中删除）。
 
-`ima2 serve`开始捆绑Grok自动代理。没有单独的`progrok`
-需要安装。使用`ima2 grok login`一次授权xAI OAuth。登录
-默认为`--manual-paste`所以 PowerShell、终端和远程 shell 都使用
-相同的复制/粘贴流程。放`IMA2_NO_GROK_PROXY=1`仅当您想管理时
-代理自己。
+Grok通道不需要本地代理，也不需要单独安装。使用`ima2 grok login`
+一次授权xAI OAuth；设备代码流程会打印一个URL和验证码，保存下来的
+会话在过期前 2 分钟自动刷新。会话存放在`~/.progrok/auth.json`，
+如果你正好装了progrok CLI，两者共用同一个文件。`ima2 grok status --probe`
+会向xAI核对会话，`ima2 grok logout`删除它。
 
 Grok尺寸映射如下xAI的形象API， 不是OpenAI's `size`场地。ima2
 将请求的大小保留在本地元数据中，但发送`aspect_ratio`例如
@@ -352,7 +352,7 @@ Windows DNS/碎片绕过工具（例如 SecretDNS）正在使用。
 | `ima2 billing` | API使用探针通过`/api/billing` (OpenAI/API- 配置后的密钥积分）。Grok和NovelAI配额仅在网页UI中通过`GET /api/quota`：当前的每周百分比/重置Grok建造xAIauth，每月遗留`usedUsd`/`limitUsd`倒退。|
 | `ima2 providers` |配置的提供商|
 | `ima2 oauth status` | OAuth代理状态|
-| `ima2 grok status` |捆绑式progrok / xAI图像模型探测状态|
+| `ima2 grok status` |保存的xAI OAuth会话状态，加`--probe`可查看图像模型可见性|
 | `ima2 ping` |健康检查正在运行的服务器|
 
 ## 配置

package/docs/CLI.zh-TW.md

@@ -14,7 +14,7 @@
 | `ima2 doctor` |診斷節點、套件、配置和身份驗證|
 | `ima2 doctor image-probe [--json]` |運行即時清理的響應影像探針`EMPTY_RESPONSE`支援|
 | `ima2 open` |開啟網路UI在瀏覽器中|
-| `ima2 grok login/status/models/proxy` |管理捆綁的progrok使用的運行時Grok提供者|
+| `ima2 grok login/status/logout` |管理`Grok`提供者使用的xAI OAuth工作階段|
 | `ima2 reset` |刪除已儲存的配置|
 | `ima2 backfill-thumbs` |產生影像和影片缺少的圖庫縮圖（離線，無需運行伺服器）|
 
@@ -82,7 +82,7 @@
 
 - `api`迫使API-key 回應路徑並需要配置API鑰匙。
 - `oauth`迫使當地OAuth代理路徑。
-- `grok`使用捆綁的progrok xAI代理人 （`127.0.0.1:18645`）。經典一代首次運行強制xAI透過回應進行網路搜尋API，然後詢問`grok-4.5`打電話ima2是當地的`generate_image`工具，那麼ima2執行xAI `/v1/images/generations`. `grok-4.3`仍然可以作為顯式相容性覆蓋使用。如果`--ref`附加圖像，最後一步使用xAI `/v1/images/edits`相反，圖像到圖像/參考上下文被保留。型號：`grok-imagine-image`, `grok-imagine-image-quality`。大小映射到xAI `aspect_ratio`和`resolution`;這UI網路搜尋切換是OpenAI-僅提供者因為Grok搜尋始終在此路徑中進行。
+- `grok`使用`~/.progrok/auth.json`中的xAI OAuth工作階段直接呼叫`https://api.x.ai`。經典一代首次運行強制xAI透過回應進行網路搜尋API，然後詢問`grok-4.5`打電話ima2是當地的`generate_image`工具，那麼ima2執行xAI `/v1/images/generations`. `grok-4.3`仍然可以作為顯式相容性覆蓋使用。如果`--ref`附加圖像，最後一步使用xAI `/v1/images/edits`相反，圖像到圖像/參考上下文被保留。型號：`grok-imagine-image`, `grok-imagine-image-quality`。大小映射到xAI `aspect_ratio`和`resolution`;這UI網路搜尋切換是OpenAI-僅提供者因為Grok搜尋始終在此路徑中進行。
 - `agy`產生Antigravity CLI透過Google生成Gemini (`nano-banana-2`）。固定1024×1024JPEG輸出，最多 3 個參考值沒有網路搜尋、品質、尺寸或遮罩控制。如果`agy`不在伺服器進程 PATH 上，ima2也檢查常見的用戶本地安裝，例如`~/.local/bin/agy`;放`IMA2_AGY_BIN=/absolute/path/to/agy`強制使用特定的二進位。
 - `gemini-api`呼叫 Google 生成語言API直接地。型號：`nano-banana-2` (Gemini3.1 Flash 影像）和`nano-banana-pro` (Gemini3 專業圖像）。使用`--model nano-banana-2`或者`--model nano-banana-pro`來選擇。支援`--size`對於直接的寬高比和解析度 (512px–4K)API小路;Vertex AI忽略方面/大小。需要`GEMINI_API_KEY`或一個Vertex AI服務帳戶（`VERTEX_SERVICE_ACCOUNT_JSON`）。切換自`agy`或者`gemini-api`提供者自動選擇相應的Gemini模型;切換離開重置為GPT預設.
 - `atlascloud`致電 Atlas Cloud 媒體API直接地。型號：`openai/gpt-image-2/text-to-image`用於文字到圖像和`openai/gpt-image-2/edit`當附有參考文獻時。需要`ATLASCLOUD_API_KEY`;網路搜尋、推理、遮罩和視訊控制將被忽略。
@@ -90,11 +90,11 @@
 - `runway` / `higgsfield`（僅限生成/視訊）路線MCP非同步管道（`POST /api/mcp/generate` + SSE等待）。Runway需要一個MCP聯繫;Higgsfield僅保留目錄（`locked`）直到付費計劃。MCP車道接受`-n 1`僅，圖庫檔案名`--ref`，並拒絕僅核心標誌`FLAG_NOT_SUPPORTED`.
 - `auto`保留路由預設行為並目前解析為GPT OAuth除非伺服器路由發生變化（僅限編輯/多模式/節點；在 3.0.0 中從 gen/video 中刪除）。
 
-`ima2 serve`開始捆綁Grok自動代理。沒有單獨的`progrok`
-需要安裝。使用`ima2 grok login`一次授權xAI OAuth。登入
-預設為`--manual-paste`所以 PowerShell、終端機和遠端 shell 都使用
-相同的複製/貼上流程。放`IMA2_NO_GROK_PROXY=1`僅當您想管理時
-代理自己。
+Grok通道不需要本機代理，也不需要另外安裝。使用`ima2 grok login`
+一次授權xAI OAuth；裝置代碼流程會印出一個URL和驗證碼，儲存下來的
+工作階段在過期前 2 分鐘自動更新。工作階段存放在`~/.progrok/auth.json`，
+如果你剛好裝了progrok CLI，兩者共用同一個檔案。`ima2 grok status --probe`
+會向xAI核對工作階段，`ima2 grok logout`刪除它。
 
 Grok尺寸映射如下xAI的形象API， 不是OpenAI's `size`場地。ima2
 將請求的大小保留在本地元資料中，但發送`aspect_ratio`例如
@@ -352,7 +352,7 @@ Windows DNS/碎片繞過工具（例如 SecretDNS）正在使用。
 | `ima2 billing` | API使用探針通過`/api/billing` (OpenAI/API- 配置後的金鑰積分）。Grok和NovelAI配額僅在網頁UI中透過`GET /api/quota`：目前的每週百分比/重置Grok建造xAIauth，每月遺留`usedUsd`/`limitUsd`倒退。|
 | `ima2 providers` |配置的提供者|
 | `ima2 oauth status` | OAuth代理狀態|
-| `ima2 grok status` |捆綁式progrok / xAI影像模型探測狀態|
+| `ima2 grok status` |儲存的xAI OAuth工作階段狀態，加`--probe`可查看影像模型可見性|
 | `ima2 ping` |健康檢查正在運行的伺服器|
 
 ## 配置

package/docs/README.ko.md

@@ -128,12 +128,12 @@ Ctrl+C로 DB, 소켓, 자식 프로세스를 정리할 수 있습니다. Windows
 
 ## 이미지 생성 공급자
 
-이미지 생성은 로컬 Codex/ChatGPT OAuth, OpenAI API key, 번들 Grok 공급자를 지원합니다.
+이미지 생성은 로컬 Codex/ChatGPT OAuth, OpenAI API key, Grok 공급자를 지원합니다.
 
 - `provider: "oauth"`는 로컬 Codex OAuth 프록시를 사용합니다.
 - `provider: "api"`는 OpenAI Responses API의 `image_generation` 도구를 사용합니다.
-- `provider: "grok"`는 번들 `progrok`을 `127.0.0.1:18645`에서 띄우고, xAI Web Search와 플래너(기본: `grok-4.5`, 설정 또는 `--planner-model`로 변경 가능)를 거친 뒤 xAI Images API를 호출합니다. `grok-4.3`은 호환 선택지로 유지합니다.
-- `provider: "grok-api"`는 `XAI_API_KEY`로 xAI Images API를 직접 호출합니다 (progrok OAuth 없음).
+- `provider: "grok"`는 `~/.progrok/auth.json`에 저장된 xAI OAuth 세션으로 `https://api.x.ai`를 직접 호출합니다. xAI Web Search와 플래너(기본: `grok-4.5`, 설정 또는 `--planner-model`로 변경 가능)를 거친 뒤 xAI Images API로 이어집니다. `grok-4.3`은 호환 선택지로 유지합니다. 처음 한 번 `ima2 grok login` 또는 설정 화면의 **Switch Account**로 로그인하면, 이후에는 만료 2분 전에 토큰이 자동으로 갱신됩니다.
+- `provider: "grok-api"`는 `XAI_API_KEY`로 xAI Images API를 직접 호출합니다 (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 우선).
 
@@ -263,9 +263,6 @@ environment variables > ~/.ima2/config.json > built-in defaults
 | `IMA2_GENERATED_DIR` | `~/.ima2/generated` | 생성 이미지 저장 위치 |
 | `IMA2_IMAGE_MODEL_DEFAULT` | `gpt-5.6-luna` | 서버 fallback 이미지 모델 |
 | `IMA2_NO_OAUTH_PROXY` | — | `1`이면 OAuth 프록시 자동 시작 비활성화 |
-| `IMA2_GROK_PROXY_HOST` | `127.0.0.1` | 번들 progrok 프록시 host |
-| `IMA2_GROK_PROXY_PORT` | `18645` | 번들 progrok 프록시 port |
-| `IMA2_NO_GROK_PROXY` | — | `1`이면 progrok 자동 시작 비활성화 |
 | `IMA2_GROK_PLANNER_MODEL` | `grok-4.5` | Grok 플래너 모델 (설정 UI 또는 `--planner-model` CLI 플래그로도 변경 가능) |
 | `IMA2_GROK_IMAGE_MODEL_DEFAULT` | `grok-imagine-image-quality` | 기본 Grok 이미지 모델 |
 | `IMA2_GROK_VIDEO_MODEL_DEFAULT` | `grok-imagine-video-1.5` | 기본 Grok 비디오 모델 |
@@ -278,6 +275,8 @@ environment variables > ~/.ima2/config.json > built-in defaults
 | `IMA2_AGY_BIN` | PATH의 `agy` | `provider: "agy"` 바이너리 경로 |
 | `IMA2_MAX_PARALLEL` | `24` | 서버 전역 병렬 생성 상한 |
 
+`IMA2_GROK_PROXY_HOST`, `IMA2_GROK_PROXY_PORT`, `IMA2_NO_GROK_PROXY`, `IMA2_GROK_RESTART_*`는 로컬 Grok 프록시와 함께 3.16에서 제거되어 더 이상 읽지 않습니다. 값을 남겨 두어도 아무 일도 일어나지 않습니다.
+
 ### 로그 모드
 
 `ima2 serve`는 일반 사용자 기준으로 터미널 출력을 조용하게 유지합니다. 시작 URL, 경고, 오류는 보이지만 요청/노드/OAuth structured log는 기본적으로 숨깁니다.

package/docs/README.zh-CN.md

@@ -165,8 +165,8 @@ ima2 skill install --tmp            # install to temp dir (fallback)
 
 - `provider: "oauth"`使用本地的Codex OAuth代理人。
 - `provider: "api"`称为OpenAI回应API与托管的`image_generation`工具。
-- `provider: "grok"`开始捆绑`progrok`在`127.0.0.1:18645`, 强制运行xAI网络搜索加上规划者通行证（默认：`grok-4.5`，可在设置中配置或通过`--planner-model`），然后调用xAI图片API通过本地代理。`grok-4.3`仍然可以作为显式兼容性覆盖使用。
-- `provider: "grok-api"`称为xAI图片API直接与`XAI_API_KEY`（无捆绑progrok OAuth代理人）。
+- `provider: "grok"`使用`~/.progrok/auth.json`中的xAI OAuth会话直接调用`https://api.x.ai`, 强制运行xAI网络搜索加上规划者通行证（默认：`grok-4.5`，可在设置中配置或通过`--planner-model`），然后调用xAI图片API。`grok-4.3`仍然可以作为显式兼容性覆盖使用。用`ima2 grok login`或网络UI登录一次；令牌在过期前 2 分钟自动刷新。
+- `provider: "grok-api"`称为xAI图片API直接与`XAI_API_KEY`（使用API密钥而不是OAuth会话）。
 - `provider: "agy"`产生Antigravity CLI (`agy -p`）通过Google生成图像Gemini's `default_api:generate_image`工具（型号：`nano-banana-2`）。输出固定为1024×1024JPEG，最多 3 个参考图像。没有网络搜索、质量或大小控制。
 - `provider: "gemini-api"`调用 Google 生成语言API直接地。支持两种型号：`nano-banana-2` (Gemini3.1 Flash 图像）和`nano-banana-pro` (Gemini3 专业图像）。身份验证是通过`GEMINI_API_KEY`环境变量、网络UI密钥管理，或Vertex AI服务帐户JSON (`VERTEX_SERVICE_ACCOUNT_JSON`）。当两者都APIkey 和 Vertex 凭证已配置，Vertex 优先。支持可变宽高比（1:1 至 21:9）和四个分辨率级别（512px、1K、2K、4K）；这些控制仅在直接上受到尊重API路径——Vertex AI端点忽略方面/大小，因为它不接受`response_format`场地。每个型号的成本不同：`nano-banana-2`（闪存）：512=0.001 美元、1K=0.003 美元、2K=0.004 美元、4K=0.006 美元；`nano-banana-pro`：1K=0.007 美元，2K=0.007 美元，4K=0.013 美元。没有网络搜索或掩码控制。
 - API-密钥生成支持经典生成、编辑、掩码引导编辑、多模式和节点生成。
@@ -174,6 +174,8 @@ ima2 skill install --tmp            # install to temp dir (fallback)
 
 如果未指定提供商，应用程序将保留当前的GPT OAuth/默认行为。GPT OAuth和API-密钥生成默认为`gpt-5.6-luna`;这API-key路径也默认为`low`推理和`1024x1024`除非请求通过了经过验证的选项。Grok图像生成默认为`grok-imagine-image-quality`.
 
+关于OAuth Grok通道有一点需要说明：xAI只把`/v1/me`记录为接受OAuth令牌的端点，所以用该令牌调用`api.x.ai`的图像与视频接口走的是未文档化的路径。它目前可用——progrok一直依赖同一条路径——但没有任何兼容性承诺。如果xAI关闭这条路径，用`XAI_API_KEY`的`provider: "grok-api"`是有文档的方案，且不受影响。
+
 Grok图像生成公开了模型选择器（`grok-imagine-image` / `grok-imagine-image-quality`）和尺寸选择器（长宽比 + 1k/2k 分辨率）。设置页面更喜欢Grok建立每周积分百分比并重置时间`GET /v1/billing?format=credits`;如果该来源不可用，则会退回到传统的每月计费窗口，并且`$used/$limit`. A **切换账户**按钮启动设备代码OAuth流动 （`POST /api/auth/switch`）无需离开应用程序即可重新进行身份验证。
 
 Grok视频生成默认为规范`grok-imagine-video-1.5`; `grok-imagine-video`仍然可用于仅限基本模型的 Ref2V、V2V 编辑和扩展路径，以及旧版本`grok-imagine-video-1.5-preview`字符串被接受作为别名。根据引用计数自动检测三种模式：文本到视频（0 引用）、图像到视频（1 引用）和引用到视频（2-14 引用；grok-imagine-video-1.5 最长 15 秒，grok-imagine-video 最长 10 秒）。 1080p 可用于`grok-imagine-video-1.5`仅提示文本到视频和单图像/帧图像到视频；仅提示 1.5 在上游请求之前使用内部白色画布 I2V 填充程序。视频控制包括持续时间（1-15秒）、分辨率（480p、720p、1080p（如果支持））和宽高比（1:1、16:9、9:16、4:3、3:4、3:2、2:3、自动）。
@@ -323,9 +325,6 @@ environment variables > ~/.ima2/config.json > built-in defaults
 | `IMA2_API_REASONING_EFFORT` | `low` |默认推理工作`provider: "api"` |
 | `IMA2_API_IMAGE_SIZE` | `1024x1024` |默认尺寸为`provider: "api"` |
 | `IMA2_API_ALLOW_WEB_SEARCH` | `true` |切换网络搜索`provider: "api"` |
-| `IMA2_GROK_PROXY_HOST` | `127.0.0.1` |捆绑主机progrok代理人|
-| `IMA2_GROK_PROXY_PORT` | `18645` |捆绑端口progrok代理人|
-| `IMA2_NO_GROK_PROXY` | — |放`1`禁用自动progrok启动|
 | `IMA2_GROK_PLANNER_MODEL` | `grok-4.5` | Grok搜索/规划器模型（也可通过设置进行配置UI或者`--planner-model` CLI旗帜）|
 | `IMA2_GROK_PLANNER_TIMEOUT_MS` | `60000` |超时时间为Grok搜索和规划呼叫|
 | `IMA2_GROK_IMAGE_MODEL_DEFAULT` | `grok-imagine-image-quality` |默认最终Grok图像模型|
@@ -337,6 +336,8 @@ environment variables > ~/.ima2/config.json > built-in defaults
 | `IMA2_AGY_BIN` | `agy`在路径上|显式路径Antigravity CLI二进制为`provider: "agy"` |
 | `IMA2_MAX_PARALLEL` | `24` |服务器范围的并行生成上限|
 
+`IMA2_GROK_PROXY_HOST`、`IMA2_GROK_PROXY_PORT`、`IMA2_NO_GROK_PROXY`和`IMA2_GROK_RESTART_*`已随本地Grok代理在 3.16 中移除，不再被读取；即使保留这些值也不会有任何影响。
+
 ### 记录模式
 
 `ima2 serve`故意保持终端输出安静：启动 URL、警告和错误保持可见，而 request/node/OAuth结构化日志默认隐藏。

package/docs/README.zh-TW.md

@@ -159,8 +159,8 @@ Web UI 使用單一 `GET /api/events` 伺服器發送事件（SSE）連線，接
 
 - `provider: "oauth"` 使用本機 Codex OAuth 代理程式。
 - `provider: "api"` 使用 OpenAI Responses API 的 `image_generation` 工具。
-- `provider: "grok"`開始捆綁`progrok`在`127.0.0.1:18645`, 強制運行xAI網路搜尋加上規劃者通行證（預設：`grok-4.5`，可在設定中配置或透過`--planner-model`），然後調用xAI圖片API透過本地代理。`grok-4.3`仍然可以作為顯式相容性覆蓋使用。
-- `provider: "grok-api"`稱為xAI圖片API直接與`XAI_API_KEY`（無捆綁progrok OAuth代理人）。
+- `provider: "grok"`使用`~/.progrok/auth.json`中的xAI OAuth工作階段直接呼叫`https://api.x.ai`, 強制運行xAI網路搜尋加上規劃者通行證（預設：`grok-4.5`，可在設定中配置或透過`--planner-model`），然後調用xAI圖片API。`grok-4.3`仍然可以作為顯式相容性覆蓋使用。用`ima2 grok login`或網頁UI登入一次；權杖在過期前 2 分鐘自動更新。
+- `provider: "grok-api"`稱為xAI圖片API直接與`XAI_API_KEY`（使用API金鑰而不是OAuth工作階段）。
 - `provider: "agy"` 啟動 Antigravity CLI（`agy -p`），透過 Google Gemini 的 `default_api:generate_image` 工具產生圖片（模型：`nano-banana-2`）。輸出固定為 1024×1024 JPEG，最多 3 張參考圖，不提供網路搜尋、品質或尺寸控制。
 - `provider: "gemini-api"` 直接呼叫 Google Generative Language API。支援 `nano-banana-2`（Gemini 3.1 Flash Image）與 `nano-banana-pro`（Gemini 3 Pro Image）；驗證方式包括 `GEMINI_API_KEY` 環境變數、Web UI 金鑰管理，或 Vertex AI 服務帳戶 JSON（`VERTEX_SERVICE_ACCOUNT_JSON`）。同時設定 API 金鑰與 Vertex 憑證時，優先使用 Vertex。支援 1:1 至 21:9 的長寬比與 512px、1K、2K、4K 四種解析度；這些控制只有直接 API 路徑有效，Vertex AI 端點不接受 `response_format` 欄位，因此會忽略長寬比與尺寸設定。
 - API 金鑰產生支援經典模式的產生、編輯、遮罩導向編輯、多階段與節點產生。
@@ -168,6 +168,8 @@ Web UI 使用單一 `GET /api/events` 伺服器發送事件（SSE）連線，接
 
 如果未指定提供者，應用程式將保留目前的GPT OAuth/預設行為。GPT OAuth和API-金鑰產生預設為`gpt-5.6-luna`;這API-key路徑也預設為`low`推理和`1024x1024`除非請求通過了經過驗證的選項。Grok影像生成預設為`grok-imagine-image-quality`.
 
+關於OAuth Grok通道有一點需要說明：xAI只把`/v1/me`記錄為接受OAuth權杖的端點，所以用該權杖呼叫`api.x.ai`的影像與影片介面走的是未文件化的路徑。它目前可用——progrok一直依賴同一條路徑——但沒有任何相容性承諾。如果xAI關閉這條路徑，用`XAI_API_KEY`的`provider: "grok-api"`是有文件的方案，且不受影響。
+
 Grok圖像生成公開了模型選擇器（`grok-imagine-image` / `grok-imagine-image-quality`）和尺寸選擇器（長寬比 + 1k/2k 解析度）。設定頁面更喜歡Grok建立每週積分百分比並重置時間`GET /v1/billing?format=credits`;如果該來源不可用，則會退回到傳統的每月計費窗口，並且`$used/$limit`. A **切換帳戶**按鈕啟動設備代碼OAuth流動 （`POST /api/auth/switch`）無需離開應用程式即可重新進行身份驗證。
 
 Grok影片產生預設為規範`grok-imagine-video-1.5`; `grok-imagine-video`仍可用於僅限基本型號的 Ref2V、V2V 編輯和擴展路徑，以及舊版本`grok-imagine-video-1.5-preview`字串被接受作為別名。根據引用計數自動偵測三種模式：文字到影片（0 引用）、圖像到影片（1 引用）和引用到影片（2-14 引用；grok-imagine-video-1.5 最長 15 秒，grok-imagine-video 最長 10 秒）。 1080p 可用於`grok-imagine-video-1.5`僅提示文字到影片和單圖像/幀圖像到影片；僅提示 1.5 在上游請求之前使用內部白色畫布 I2V 填充程式。視訊控制包括持續時間（1-15秒）、解析度（480p、720p、1080p（如果支援））和寬高比（1:1、16:9、9:16、4:3、3:4、3:2、2:3、自動）。
@@ -317,9 +319,6 @@ environment variables > ~/.ima2/config.json > built-in defaults
 | `IMA2_API_REASONING_EFFORT` | `low` |默認推理工作`provider: "api"` |
 | `IMA2_API_IMAGE_SIZE` | `1024x1024` |預設尺寸為`provider: "api"` |
 | `IMA2_API_ALLOW_WEB_SEARCH` | `true` |切換網路搜尋`provider: "api"` |
-| `IMA2_GROK_PROXY_HOST` | `127.0.0.1` |捆綁主機progrok代理人|
-| `IMA2_GROK_PROXY_PORT` | `18645` |捆綁端口progrok代理人|
-| `IMA2_NO_GROK_PROXY` | — |放`1`停用自動progrok啟動|
 | `IMA2_GROK_PLANNER_MODEL` | `grok-4.5` | Grok搜尋/規劃器模型（也可透過設定進行配置UI或者`--planner-model` CLI旗幟）|
 | `IMA2_GROK_PLANNER_TIMEOUT_MS` | `60000` |超時時間為Grok搜尋和規劃呼叫|
 | `IMA2_GROK_IMAGE_MODEL_DEFAULT` | `grok-imagine-image-quality` |預設最終Grok影像模型|
@@ -331,6 +330,8 @@ environment variables > ~/.ima2/config.json > built-in defaults
 | `IMA2_AGY_BIN` | `agy`在路徑上|顯式路徑Antigravity CLI二進制為`provider: "agy"` |
 | `IMA2_MAX_PARALLEL` | `24` |伺服器範圍的平行產生上限|
 
+`IMA2_GROK_PROXY_HOST`、`IMA2_GROK_PROXY_PORT`、`IMA2_NO_GROK_PROXY`和`IMA2_GROK_RESTART_*`已隨本機Grok代理在 3.16 中移除，不再被讀取；即使保留這些值也不會有任何影響。
+
 ### 記錄模式
 
 `ima2 serve`故意保持終端輸出安靜：啟動 URL、警告和錯誤保持可見，而 request/node/OAuth結構化日誌預設隱藏。

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

@@ -4,9 +4,10 @@ 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: 492 (runtime: 227, contract: 265)
+Total: 490 (runtime: 225, contract: 265)
 
 ## Runtime-importing tests
+- `tests/advertise-payload-contract.test.ts`
 - `tests/agent-image-reference-contract.test.ts`
 - `tests/agent-mode-auto-planner-contract.test.ts`
 - `tests/agent-mode-llm-planner-contract.test.ts`
@@ -78,17 +79,12 @@ Total: 492 (runtime: 227, contract: 265)
 - `tests/generation-request-log.test.ts`
 - `tests/google-execution-parity.test.ts`
 - `tests/gpt56-rollout-contract.test.ts`
-- `tests/grok-advertise-liveness-contract.test.ts`
-- `tests/grok-command-login-contract.test.ts`
 - `tests/grok-execution-parity.test.ts`
 - `tests/grok-image-address-policy.test.ts`
 - `tests/grok-image-download-pinning.test.ts`
 - `tests/grok-image-download-policy.test.ts`
 - `tests/grok-planner-adapter.test.ts`
 - `tests/grok-planner-config-route.test.ts`
-- `tests/grok-proxy-launcher.test.ts`
-- `tests/grok-proxy-restart.test.ts`
-- `tests/grok-proxy-supervisor-contract.test.ts`
 - `tests/grok-size-mapper.test.ts`
 - `tests/grok-upstream-retry.test.ts`
 - `tests/grokVideoAdapter.test.ts`
@@ -233,6 +229,8 @@ Total: 492 (runtime: 227, contract: 265)
 - `tests/videoLineage.test.ts`
 - `tests/videoRoute.test.ts`
 - `tests/voice-picker-contract.test.ts`
+- `tests/xai-auth-contract.test.ts`
+- `tests/xai-device-login-contract.test.ts`
 - `tests/xai-video-model-alias-contract.test.ts`
 
 ## Contract-only tests

package/lib/agentPlannerModel.js

@@ -4,7 +4,8 @@ import { formatToolManifestForPrompt } from "./agentToolManifest.js";
 import { getAgentSession } from "./agentStore.js";
 import { errInfo } from "./errInfo.js";
 import { logEvent } from "./logger.js";
-import { getGrokEndpoint, getPlannerConfig } from "./grokImageCore.js";
+import { getPlannerConfig } from "./grokImageCore.js";
+import { fetchWithGrokAuth, getGrokEndpoint } from "./grokRuntime.js";
 import { waitForOAuthReady } from "./oauthProxy/runtime.js";
 import { requireRuntimeContext } from "./runtimeContext.js";
 function buildPlannerDeveloperPrompt(hasSourceImage, imageCount) {
@@ -92,25 +93,25 @@ export async function requestAgentPlanFromModel(ctxRaw, input) {
     }
 }
 async function requestGrokPlan(ctx, developerPrompt, userPrompt, signal) {
-    const { url, headers } = getGrokEndpoint(ctx, "/v1/chat/completions");
     const planner = getPlannerConfig(ctx);
-    const res = await fetch(url, {
-        method: "POST",
-        headers,
-        signal,
-        body: JSON.stringify({
-            model: planner.model,
-            stream: false,
-            messages: [
-                { role: "system", content: developerPrompt },
-                { role: "user", content: userPrompt },
-            ],
-        }),
+    const body = JSON.stringify({
+        model: planner.model,
+        stream: false,
+        messages: [
+            { role: "system", content: developerPrompt },
+            { role: "user", content: userPrompt },
+        ],
     });
+    // The agent planner only ever runs on the OAuth `grok` lane (the caller branches on
+    // settings.provider === "grok"), so a 401 here means the session needs a refresh.
+    const res = await fetchWithGrokAuth(ctx, "grok", (credential) => {
+        const endpoint = getGrokEndpoint("/v1/chat/completions", credential);
+        return fetch(endpoint.url, { method: "POST", headers: endpoint.headers, signal, body });
+    }, { signal });
     if (!res.ok)
         throw plannerHttpError("grok", res.status);
-    const body = await res.json();
-    return typeof body.choices?.[0]?.message?.content === "string" ? body.choices[0].message.content : "";
+    const parsed = await res.json();
+    return typeof parsed.choices?.[0]?.message?.content === "string" ? parsed.choices[0].message.content : "";
 }
 async function requestResponsesPlan(ctx, developerPrompt, userPrompt, settings, signal) {
     let url;

package/lib/capabilities.js

@@ -140,9 +140,10 @@ export function buildIma2Capabilities({ appConfig = runtimeConfigDefault, packag
                     ],
                     presetsAreAuthoritative: false,
                     // Named by the 400 itself: "Custom voice ids created via the /v1/custom-voices
-                    // API are also accepted." The endpoint answers 200 with a 30-voice cap that is
-                    // documented nowhere else.
+                    // API are also accepted." GET on that endpoint answers 200 with {voices, total_count,
+                    // cap: 30}; the cap appears in no document, so the endpoint is its own source.
                     customVoiceApi: "/v1/custom-voices",
+                    customVoiceCap: 30,
                 },
                 // Which model takes a video in, and which takes audio in. The two split on input
                 // modality, so there is no path that edits a video on 1.5 — it answers 400.

package/lib/errors/providerMap.js

@@ -2,6 +2,10 @@ import { RESPONSE_DIAGNOSTIC_CODES } from "../responsesErrors.js";
 export function statusForErrorCode(code, fallback = 500) {
     if (code === "GROK_API_KEY_MISSING")
         return 401;
+    if (code === "GROK_AUTH_REQUIRED")
+        return 401;
+    if (code === "GROK_AUTH_REFRESH_FAILED")
+        return 502;
     if (code === "OAUTH_UNAVAILABLE" || code === "NETWORK_FAILED")
         return 503;
     if (code === "AUTH_CHATGPT_EXPIRED" || code === "AUTH_API_KEY_INVALID")
@@ -70,6 +74,15 @@ export const PROVIDER_ERROR_MAP = {
     GEMINI_API_MASK_UNSUPPORTED: "CAPABILITY_UNSUPPORTED",
     GROK_API_KEY_MISSING: "AUTH_INVALID",
     GROK_AUTH_FAILED: "AUTH_INVALID",
+    // Raised by lib/xaiAuth.ts: no stored session, or the refresh token was
+    // rejected outright (invalid_grant / revoked). The user must log in again.
+    GROK_AUTH_REQUIRED: "AUTH_EXPIRED",
+    // The refresh could not complete (network, 5xx, 429 budget exhausted); the
+    // stored session is kept and a later attempt may succeed.
+    GROK_AUTH_REFRESH_FAILED: "NETWORK_FAILURE",
+    // A Grok transport call was made without resolving a credential first. Programming
+    // error at the call site, never a user-facing auth state.
+    GROK_CREDENTIAL_UNRESOLVED: "INTERNAL_STATE_ERROR",
     GROK_BAD_REQUEST: "CAPABILITY_UNSUPPORTED",
     GROK_EMPTY_RESPONSE: "INTERNAL_STATE_ERROR",
     GROK_IMAGE_DOWNLOAD_FAILED: "NETWORK_FAILURE",

package/lib/grokImageCore.js

@@ -1,21 +1,9 @@
 import { mapSizeToGrokImageParams } from "./grokSizeMapper.js";
 import { detectImageMimeFromB64 } from "./refs.js";
-import { getGrokProxyUrl } from "./grokRuntime.js";
+import { getGrokEndpoint } from "./grokRuntime.js";
 export { downloadGrokImageUrl } from "./grokImageDownload.js";
+export { getGrokEndpoint } from "./grokRuntime.js";
 import { DEFAULT_GROK_PLANNER_MODEL } from "../config.js";
-export function getGrokEndpoint(ctx, path = "/v1/images/generations", directApiKey) {
-    if (directApiKey) {
-        const normalizedPath = path.startsWith("/") ? path : `/${path}`;
-        return {
-            url: `https://api.x.ai${normalizedPath}`,
-            headers: { "Content-Type": "application/json", Authorization: `Bearer ${directApiKey}` },
-        };
-    }
-    return {
-        url: getGrokProxyUrl(ctx, path),
-        headers: { "Content-Type": "application/json", Authorization: "Bearer dummy" },
-    };
-}
 export function getGrokTimeout(ctx) {
     return ctx.config.grokProvider?.generationTimeoutMs || 300_000;
 }
@@ -81,9 +69,14 @@ export function extractResponsesText(response) {
  * origin already generated and billed, and no idempotency key exists to deduplicate it.
  * Retrying would charge twice.
  * See devlog/_plan/260812_navrail_grok_autotag/020_grok_upstream_retry.md.
+ *
+ * A 401, by contrast, is rejected before anything is generated, so the caller may resolve a
+ * fresh credential and call this once more (lib/grokRuntime.ts fetchWithGrokAuth).
  */
-export async function postGrokImages(ctx, payload, signal, path = "/v1/images/generations", directApiKey) {
-    const { url, headers } = getGrokEndpoint(ctx, path, directApiKey);
+export async function postGrokImages(ctx, payload, signal, path = "/v1/images/generations", credential) {
+    if (!credential)
+        throw grokError("Grok credential was not resolved before the request", 500, "GROK_CREDENTIAL_UNRESOLVED");
+    const { url, headers } = getGrokEndpoint(path, credential);
     const timeoutMs = getGrokTimeout(ctx);
     const { combinedSignal, timer } = withTimeoutSignal(signal, timeoutMs);
     try {

package/lib/grokImagePlanner.js

@@ -4,6 +4,17 @@ import { mapSizeToGrokImageParams } from "./grokSizeMapper.js";
 import { DEFAULT_GROK_PLANNER_MODEL } from "../config.js";
 import { grokError, grokStageError, getPlannerConfig, getGrokEndpoint, withTimeoutSignal, referenceImageUrl, extractResponsesText, } from "./grokImageCore.js";
 import { grokFetchWithRetry } from "./grokUpstreamRetry.js";
+import { resolveGrokCredential } from "./grokRuntime.js";
+/**
+ * Planner and search share the credential the adapter already resolved. Direct callers
+ * (lib/grokImageAdapter re-exports) may omit it, and the OAuth `grok` lane is the right
+ * default there: an explicit credential is what makes a call the `grok-api` lane.
+ */
+async function plannerCredential(ctx, options) {
+    if (options.credential)
+        return options.credential;
+    return await resolveGrokCredential(ctx, "grok", { ...(options.signal ? { signal: options.signal } : {}) });
+}
 export function buildGrokPlannerPayload(prompt, model, size, sizeParams, plannerModel = DEFAULT_GROK_PLANNER_MODEL, searchSummary = "", references = 0, backgroundConstraint = "") {
     const referenceImages = Array.isArray(references) ? references : [];
     const referenceCount = Array.isArray(references) ? references.length : references;
@@ -179,7 +190,7 @@ export async function searchGrokVisualContext(prompt, ctx, options = {}) {
     const planner = getPlannerConfig(ctx);
     const plannerModel = options.plannerModel || planner.model;
     const payload = buildGrokSearchPayload(prompt, plannerModel);
-    const { url, headers } = getGrokEndpoint(ctx, "/v1/responses", options.directApiKey);
+    const { url, headers } = getGrokEndpoint("/v1/responses", await plannerCredential(ctx, options));
     // The search brief has its own, smaller budget: it runs BEFORE the planner call inside
     // the same user request, so charging it the full planner budget lets one slow stage eat
     // the other's time. See devlog/_plan/260817_grok_video_planner_timeout/010.
@@ -249,11 +260,12 @@ export async function planGrokImage(prompt, ctx, options = {}) {
     // record calls actually made (070 QA: search ran even with
     // webSearchEnabled:false, and webSearchCalls was hardcoded to 1).
     const searchEnabled = options.webSearchEnabled !== false;
+    const credential = await plannerCredential(ctx, options);
     const search = searchEnabled
-        ? await searchGrokVisualContext(prompt, ctx, { ...(options.signal ? { signal: options.signal } : {}), ...(options.requestId ? { requestId: options.requestId } : {}), ...(options.directApiKey ? { directApiKey: options.directApiKey } : {}), plannerModel })
+        ? await searchGrokVisualContext(prompt, ctx, { ...(options.signal ? { signal: options.signal } : {}), ...(options.requestId ? { requestId: options.requestId } : {}), credential, plannerModel })
         : { summary: "", skipped: true };
     const payload = buildGrokPlannerPayload(prompt, imageModel, options.size, sizeParams, plannerModel, search.summary, options.references || options.referenceCount || 0, options.backgroundConstraint || "");
-    const { url, headers } = getGrokEndpoint(ctx, "/v1/chat/completions", options.directApiKey);
+    const { url, headers } = getGrokEndpoint("/v1/chat/completions", credential);
     const { combinedSignal, timer } = withTimeoutSignal(options.signal, planner.timeoutMs);
     logEvent("grok", "planner:start", { requestId: options.requestId, plannerModel, imageModel, size: options.size });
     try {

package/lib/grokRuntime.js

@@ -1,21 +1,52 @@
-const DEFAULT_GROK_PROXY_HOST = "127.0.0.1";
-const DEFAULT_GROK_PROXY_PORT = 18645;
-function normalizeBaseUrl(url) {
-    return url.replace(/\/v1\/?$/, "").replace(/\/$/, "");
+import { getGrokAccessToken } from "./xaiAuth.js";
+export function getGrokDirectBaseUrl() {
+    return "https://api.x.ai";
 }
-export function getGrokProxyBaseUrl(ctx = {}) {
-    const grokCfg = ctx.config?.grokProvider || {};
-    const explicitUrl = ctx.grokUrl;
-    if (explicitUrl)
-        return normalizeBaseUrl(explicitUrl);
-    const host = grokCfg.proxyHost || DEFAULT_GROK_PROXY_HOST;
-    const port = ctx.grokActualPort || grokCfg.proxyPort || DEFAULT_GROK_PROXY_PORT;
-    return `http://${host}:${port}`;
+export function grokAuthHeaders(credential) {
+    const bearer = credential.kind === "api-key" ? credential.key : credential.token;
+    return { "Content-Type": "application/json", Authorization: `Bearer ${bearer}` };
 }
-export function getGrokProxyUrl(ctx = {}, path = "/v1") {
+export function getGrokEndpoint(path = "/v1/images/generations", credential) {
     const normalizedPath = path.startsWith("/") ? path : `/${path}`;
-    return `${getGrokProxyBaseUrl(ctx)}${normalizedPath}`;
+    return { url: `${getGrokDirectBaseUrl()}${normalizedPath}`, headers: grokAuthHeaders(credential) };
 }
-export function getGrokDirectBaseUrl() {
-    return "https://api.x.ai";
+function grokCredentialError(code, status, message) {
+    return Object.assign(new Error(message), { code, status });
+}
+/**
+ * The single place a Grok lane turns into a bearer. For `grok` this may refresh the OAuth
+ * session, so it is async; GrokAuthError (GROK_AUTH_REQUIRED / GROK_AUTH_REFRESH_FAILED)
+ * propagates unchanged. For `grok-api` a missing key is GROK_API_KEY_MISSING, the same code
+ * the execution admission check emits.
+ */
+export async function resolveGrokCredential(ctx, lane, opts = {}) {
+    if (lane === "grok-api") {
+        const key = typeof ctx.xaiApiKey === "string" ? ctx.xaiApiKey.trim() : "";
+        if (!key)
+            throw grokCredentialError("GROK_API_KEY_MISSING", 401, "Grok API key is required for grok-api");
+        return { kind: "api-key", key };
+    }
+    const token = await getGrokAccessToken({
+        ...(opts.forceRefresh !== undefined ? { forceRefresh: opts.forceRefresh } : {}),
+        ...(opts.rejectedAccessToken !== undefined ? { rejectedAccessToken: opts.rejectedAccessToken } : {}),
+        ...(opts.signal !== undefined ? { signal: opts.signal } : {}),
+        ...(opts.deps !== undefined ? { deps: opts.deps } : {}),
+        ...(ctx.grokAuthHomeDir !== undefined ? { homeDir: ctx.grokAuthHomeDir } : {}),
+    });
+    return { kind: "oauth", token };
+}
+/**
+ * Runs `doFetch` with a fresh credential and, on a 401 from an OAuth bearer, refreshes
+ * exactly once and replays. Nesting is fixed: this wrapper sits OUTSIDE grokFetchWithRetry
+ * (the 5xx/reset retrier), which cannot rebuild headers itself. grokUpstreamRetry stays a
+ * leaf and never sees credentials. A 401 arrives before any generation is billed, so the
+ * single replay is safe even for the non-idempotent image and video-start calls.
+ */
+export async function fetchWithGrokAuth(ctx, lane, doFetch, opts = {}) {
+    const first = await resolveGrokCredential(ctx, lane, opts);
+    const res = await doFetch(first);
+    if (res.status !== 401 || first.kind !== "oauth")
+        return res;
+    const second = await resolveGrokCredential(ctx, lane, { ...opts, forceRefresh: true, rejectedAccessToken: first.token });
+    return doFetch(second);
 }

package/lib/grokVideoAdapter.js

@@ -8,6 +8,7 @@ import { buildGrokVideoPlannerSystemPrompt, composeFallbackVideoPrompt, formatDu
 import { GROK_VIDEO_MODEL_15, GROK_VIDEO_MODEL_BASE, MAX_REF2V_REFERENCES, MAX_REFERENCE_AUDIOS, canonicalGrokVideoModel, validateVideoDurationForRequest, validateVideoResolutionForRequest, } from "./imageModels.js";
 import { formatVideoContinuityForPlanner } from "./videoContinuity.js";
 import { DEFAULT_GROK_PLANNER_MODEL } from "../config.js";
+import { resolveGrokCredential } from "./grokRuntime.js";
 import { videoConfig, videoEndpoint, withTimeoutSignal, } from "./grokVideoShared.js";
 import { pollVideoUntilDone } from "./grokVideoPoll.js";
 export { downloadVideo } from "./grokVideoDownload.js";
@@ -42,6 +43,17 @@ export function isDegradablePlannerFailure(err) {
     return null;
 }
 const canonicalVideoModel = canonicalGrokVideoModel;
+/**
+ * Every video call carries an explicit credential. Callers that resolved one (the HTTP
+ * routes, the extend operation) pass it down so a whole request uses a single bearer;
+ * callers that did not — the agent surface — get the OAuth lane, which is exactly what
+ * the removed proxy used to supply for them.
+ */
+async function videoCredential(ctx, options) {
+    if (options.credential)
+        return options.credential;
+    return resolveGrokCredential(ctx, "grok", options.signal ? { signal: options.signal } : {});
+}
 function sourceImageUrl(image, mime) {
     if (image.startsWith("data:") || image.startsWith("http"))
         return image;
@@ -144,6 +156,7 @@ export function parseGrokVideoPlanPrompt(response) {
 }
 export async function planGrokVideo(prompt, ctx, options = {}) {
     const cfg = videoConfig(ctx);
+    const credential = await videoCredential(ctx, options);
     const mode = options.mode || (options.sourceImage ? "image-to-video" : "text-to-video");
     const duration = options.duration ?? 5;
     const resolution = options.resolution || "480p";
@@ -170,7 +183,7 @@ export async function planGrokVideo(prompt, ctx, options = {}) {
             // own deadline would turn a slow search — the exact case 020 exists to degrade — into
             // GENERATION_CANCELED. The stage bound is applied inside that function via
             // getPlannerConfig().searchTimeoutMs.
-            const search = await searchGrokVisualContext(prompt, ctx, { signal: phaseSignal, ...(options.requestId ? { requestId: options.requestId } : {}), ...(options.directApiKey ? { directApiKey: options.directApiKey } : {}), plannerModel });
+            const search = await searchGrokVisualContext(prompt, ctx, { signal: phaseSignal, ...(options.requestId ? { requestId: options.requestId } : {}), credential, plannerModel });
             searchSummary = search.summary;
         }
         catch (e) { // justified: adapter rejections are untyped; the shape is narrowed here
@@ -209,7 +222,7 @@ export async function planGrokVideo(prompt, ctx, options = {}) {
             continuityLineage: options.continuityLineage,
             backgroundConstraint: options.backgroundConstraint,
         });
-        const { url, headers } = videoEndpoint(ctx, "/v1/chat/completions", options.directApiKey);
+        const { url, headers } = videoEndpoint(ctx, "/v1/chat/completions", credential);
         const { combinedSignal, timer } = withTimeoutSignal(phaseSignal, cfg.plannerTimeoutMs);
         logEvent("grok", "video:planner:start", { requestId: options.requestId, mode, duration, resolution });
         try {
@@ -332,7 +345,7 @@ export function buildVideoGenerationPayload(plan, opts) {
 }
 export async function startVideoRequest(ctx, payload, options) {
     const cfg = videoConfig(ctx);
-    const { url, headers } = videoEndpoint(ctx, "/v1/videos/generations", options.directApiKey);
+    const { url, headers } = videoEndpoint(ctx, "/v1/videos/generations", await videoCredential(ctx, options));
     const { combinedSignal, timer } = withTimeoutSignal(options.signal, cfg.startTimeoutMs);
     try {
         // NOT wrapped in grokFetchWithRetry on purpose: a reset or 5xx here may follow a job
@@ -364,6 +377,9 @@ export async function startVideoRequest(ctx, payload, options) {
 }
 export async function generateVideoViaGrok(prompt, ctx, options = {}) {
     const cfg = videoConfig(ctx);
+    // Resolve once for the whole request: plan, start, and poll must all carry the same
+    // bearer, and re-resolving per stage would refresh the OAuth session repeatedly.
+    const effective = { ...options, credential: await videoCredential(ctx, options) };
     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));
@@ -378,7 +394,7 @@ export async function generateVideoViaGrok(prompt, ctx, options = {}) {
             aspectRatio: options.aspectRatio || "auto",
             webSearchCalls: options.webSearchCalls ?? 1,
         }
-        : await planGrokVideo(prompt, ctx, options);
+        : await planGrokVideo(prompt, ctx, effective);
     let xaiVideoRequestId;
     let effectiveModel = model;
     // grokv1.5 doesn't support T2V — inject a white canvas as source image to use I2V path
@@ -394,7 +410,7 @@ export async function generateVideoViaGrok(prompt, ctx, options = {}) {
         effectivePayload = buildVideoGenerationPayload(plan, { model, sourceImageUrl: srcUrl, referenceImageUrls: refUrls, ...(voices.length ? { referenceAudios: voices } : {}) });
     }
     try {
-        xaiVideoRequestId = await startVideoRequest(ctx, effectivePayload, options);
+        xaiVideoRequestId = await startVideoRequest(ctx, effectivePayload, effective);
     }
     catch (e) {
         // Fallback: if 1.5-preview still fails, retry with base model.
@@ -404,7 +420,7 @@ export async function generateVideoViaGrok(prompt, ctx, options = {}) {
         if (model !== GROK_VIDEO_MODEL_BASE && e?.status === 400 && voices.length === 0) {
             effectiveModel = GROK_VIDEO_MODEL_BASE;
             const fallbackPayload = buildVideoGenerationPayload(plan, { model: effectiveModel, sourceImageUrl: srcUrl, referenceImageUrls: refUrls });
-            xaiVideoRequestId = await startVideoRequest(ctx, fallbackPayload, options);
+            xaiVideoRequestId = await startVideoRequest(ctx, fallbackPayload, effective);
             logEvent("grok", "video:fallback", { requestId: options.requestId, from: model, to: effectiveModel });
         }
         else {
@@ -414,7 +430,7 @@ export async function generateVideoViaGrok(prompt, ctx, options = {}) {
     const modelFallback = effectiveModel === model ? null : { from: model, to: effectiveModel };
     options.onEvent?.({ phase: "submitted", xaiVideoRequestId, requestedModel: model, effectiveModel, modelFallback });
     logEvent("grok", "video:submitted", { requestId: options.requestId, xaiVideoRequestId, mode: plan.mode });
-    const poll = await pollVideoUntilDone(ctx, xaiVideoRequestId, options);
+    const poll = await pollVideoUntilDone(ctx, xaiVideoRequestId, effective);
     if (!poll.videoUrl)
         throw grokError("Grok video done without a video url", 502, "GROK_VIDEO_EMPTY_RESPONSE");
     if (poll.respectModeration === false)