sptialai-image-gen

name	sptialai-image-gen
description	Test and use an OpenAI-compatible SpatialAI image relay for GPT Image generation. Use when Codex needs to verify a relay key/base_url, diagnose why an SDK or helper CLI image request fails, call https://spatialai.vip or another OpenAI-compatible /v1/images/generations endpoint directly, decode b64_json into a PNG, or explain the relay image-generation process without exposing credentials.

SptialAI Image Gen

Core Idea

Use the relay as an OpenAI-compatible API base. Authentication and model listing can succeed while SDK/CLI generation fails if the relay rejects optional parameters. Prefer a minimal direct HTTP request to /v1/images/generations when testing compatibility.

Never print, commit, or embed real API keys. Read keys from environment variables or local env files only.

Workflow

1. Locate configuration without revealing secrets:
   • Prefer existing OPENAI_API_KEY.
   • Load .env.local only when the user says it is available or local context clearly requires it.
   • Normalize OPENAI_BASE_URL to include /v1; https://spatialai.vip becomes https://spatialai.vip/v1.
2. Check authentication with:

   curl -sS -i "$OPENAI_BASE_URL/models" \
     -H "Authorization: Bearer $OPENAI_API_KEY"
   

   Treat 200 plus gpt-image-2 in the model list as authentication and model availability passing. Treat 401 INVALID_API_KEY as an invalid or unavailable key.
3. If the user asks to generate, start with the direct script in scripts/generate_image.py. This avoids helper CLIs that may add parameters the relay blocks.
4. Save generated images into the workspace, usually output/imagegen/, unless the user gives another path.
5. Verify the saved file with Pillow or another image tool: dimensions, mode, and nonzero byte size.
6. Report the saved path, model, endpoint, and whether the request used direct HTTP or a helper SDK/CLI. Do not include the secret.

Direct Generation

Use the bundled script:

python "${CODEX_HOME:-$HOME/.codex}/skills/sptialai-image-gen/scripts/generate_image.py" \
  --env-file .env.local \
  --prompt "A simple blue square icon on a white background." \
  --out output/imagegen/spatialai-test.png

For a tutorial image:

python "${CODEX_HOME:-$HOME/.codex}/skills/sptialai-image-gen/scripts/generate_image.py" \
  --env-file .env.local \
  --prompt "Create a polished Chinese educational infographic cover about SpatialAI relay image generation. Include: SpatialAI 生图教程, base_url=https://spatialai.vip/v1, images.generate, 保存 PNG. No credentials, no passwords, no secrets, no watermark." \
  --out output/imagegen/spatialai-gpt-image-2-tutorial.png \
  --quality low \
  --size 1024x1024

Defaults:

• --base-url comes from OPENAI_BASE_URL, falling back to https://spatialai.vip/v1.
• --model defaults to gpt-image-2.
• --quality defaults to low because relay test keys may be limited and faster drafts are enough for smoke tests.
• The script sends only model, prompt, size, quality, and n unless additional flags are added later.

Diagnostics

If an SDK or imagegen helper CLI raises PermissionDeniedError: Your request was blocked, try direct HTTP with the minimal payload before concluding the key lacks image permissions. In prior testing:

• /v1/models returned 200 and listed gpt-image-2.
• A helper CLI request failed with PermissionDeniedError: Your request was blocked.
• A minimal curl request to /v1/images/generations succeeded and returned b64_json.

This suggests some relays may block optional SDK/helper parameters such as output-format related fields or moderation/background fields. Use the script to reduce the payload surface.

If Python direct requests get HTTP 403: error code: 1010 while curl works, the relay front door may be blocking Python's default urllib User-Agent. The bundled script sets Accept: application/json and User-Agent: curl/8.5.0 for compatibility.

Security

• Do not store generated examples with real keys visible in the image.
• Do not echo OPENAI_API_KEY; print only whether it is present.
• Avoid writing .env.local contents into logs, docs, screenshots, or generated tutorial images.
• If user-provided prompts mention keys, credentials, or secrets, rewrite visible image text to generic placeholders like YOUR_RELAY_KEY.