via POST /v1/images/generations call grok-imagine-image to generate images.
Quick start
Run in any workspace:
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 absolute path example:
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
Default configuration
| Item | Default value |
|---|---|
| API address | http://43.163.230.83:8000/v1 |
| Model | grok-imagine-image |
| Size | 1024x1024 |
| Timeout | 180 seconds |
| API Key | The placeholder written in scripts/generate.py (DEFAULT_API_KEY) |
Can be overridden with environment variables or parameters:
GROK_IMAGINE_API_KEY/--api-keyGROK_IMAGINE_API_BASE/--api-baseGROK_IMAGINE_MODEL/--model
Workflow
- Confirm that the user needs to use Grok Imagine image generation.
- Write the prompt clearly (this interface usually works more reliably with English prompts).
- Choose the output directory under the current workspace (images intended for users are preferably placed in
outputs/)。 - Run
scripts/generate.py。 - Report the local save path and the accessible image URL.
- If the download succeeds, show the local image path to the user.
Important interface behavior
- Only use
/v1/images/generations. Do not use/v1/chat/completionsto callgrok-imagine-image。 - A successful response is roughly as follows:
{
"created": 1785029720,
"data": [
{
"mime_type": "image/jpeg",
"revised_prompt": "",
"url": "http://127.0.0.1:8000/v1/media/images/img_xxx"
}
]
}
- The returned media URL may point to
127.0.0.1. The script will rewrite it to the configured public host address before downloading. - Image generation may take tens of seconds; keep the timeout high (default 180 seconds).
Script parameters
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
Common parameters:
--json: Output machine-readable JSON, convenient for Agent parsing--no-download: Only print the API URL, do not download the file--response-format url|b64_json: Optional OpenAI-style fields (if supported by the gateway)
Key configuration
Before first formal use, please replace:
scripts/generate.py in DEFAULT_API_KEY = "g2a_REPLACE_ME"
or set:
# PowerShell
$env:GROK_IMAGINE_API_KEY = "g2a_xxx"
$env:GROK_IMAGINE_API_BASE = "http://43.163.230.83:8000/v1"
Do not print the API Key in full in user-visible replies.
Failure handling
invalid_request/ missing model or prompt: check the request body and ensure that--promptis non-empty.401/403: Key missing, still a placeholder, or unauthorized.- Timeout: retry once with the same prompt; image generation itself may be slow.
- Generation succeeded but download failed: report the rewritten public URL and keep the generation result.
- If Chat Completions fails: switch back to
images/generations。
Agent checklist
- Prefer using this skill's built-in script; do not hand-write temporary curl/Python.
- User-visible images are preferably saved to the workspace
outputs/。 - After success, briefly report: the prompt used, local path, and public URL.
- If the user provides a new base URL or key, prefer passing it in via parameters/environment variables; do not modify unrelated files.