grok-imagine-image

Imported from wwwzhouhui/skills_collection (grok-imagine-image/SKILL.md). Install upstream with npx skills add wwwzhouhui/skills_collection --skill grok-imagine-image. Copyright stays with the author.

Grok Imagine 生图

通过 POST /v1/images/generations 调用 grok-imagine-image 生成图片。

快速开始

在任意工作区执行：

python "$CODEX_HOME/skills/grok-imagine-image/scripts/generate.py" \
  --prompt "a cozy reading nook with soft daylight" \
  --output-dir ./outputs \
  --name-tag reading-nook \
  --json

Windows 绝对路径示例：

python "C:\Users\Administrator\.codex\skills\grok-imagine-image\scripts\generate.py" \
  --prompt "a simple red apple on a white background" \
  --output-dir "./outputs" \
  --json

默认配置

可用环境变量或参数覆盖：

• GROK_IMAGINE_API_KEY / --api-key
• GROK_IMAGINE_API_BASE / --api-base
• GROK_IMAGINE_MODEL / --model

工作流程

1. 确认用户需要使用 Grok Imagine 生图。
2. 写清楚提示词（该接口通常英文 prompt 效果更稳）。
3. 选择当前工作区下的输出目录（面向用户的图片优先放 outputs/）。
4. 运行 scripts/generate.py。
5. 回报本地保存路径和可访问的图片 URL。
6. 若下载成功，把本地图片路径展示给用户。

重要接口行为

• 只使用 /v1/images/generations。不要用 /v1/chat/completions 调 grok-imagine-image。
• 成功响应大致如下：

{
  "created": 1785029720,
  "data": [
    {
      "mime_type": "image/jpeg",
      "revised_prompt": "",
      "url": "http://127.0.0.1:8000/v1/media/images/img_xxx"
    }
  ]
}

• 返回的媒体 URL 可能指向 127.0.0.1。脚本会在下载前改写为配置的公网主机地址。
• 生图可能需要几十秒；超时时间请保持较高（默认 180 秒）。

脚本参数

python scripts/generate.py \
  --prompt "..." \
  --prompt-file ./prompt.txt \
  --output-dir ./outputs \
  --name-tag my-image \
  --n 1 \
  --size 1024x1024 \
  --model grok-imagine-image \
  --api-base http://43.163.230.83:8000/v1 \
  --api-key g2a_xxx \
  --timeout 180 \
  --json

常用参数：

• --json：输出机器可读 JSON，方便 Agent 解析
• --no-download：只打印 API URL，不下载文件
• --response-format url|b64_json：可选 OpenAI 风格字段（若网关支持）

密钥配置

首次正式使用前，请替换：

scripts/generate.py 中的 DEFAULT_API_KEY = "g2a_REPLACE_ME"

或设置：

# PowerShell
$env:GROK_IMAGINE_API_KEY = "g2a_xxx"
$env:GROK_IMAGINE_API_BASE = "http://43.163.230.83:8000/v1"

不要在用户可见回复中完整打印 API Key。

失败处理

• invalid_request / 缺少 model 或 prompt：检查请求体，确保 --prompt 非空。
• 401/403：密钥缺失、仍是占位符，或未授权。
• 超时：用相同 prompt 重试一次；生图本身可能较慢。
• 生成成功但下载失败：回报改写后的公网 URL，并保留生成结果。
• 若走 Chat Completions 失败：改回 images/generations。

Agent 检查清单

• 优先使用本技能自带脚本，不要手写临时 curl/Python。
• 用户可见图片优先保存到工作区 outputs/。
• 成功后简要汇报：使用的 prompt、本地路径、公网 URL。
• 若用户提供了新的 base URL 或 key，优先用参数/环境变量传入，不要去改无关文件。