Stepfun Vision Skill

Describe Images

Your current model cannot process images directly (input modalities: text only). When image content is needed, run the bundled script to have an external vision model (default: StepFun step-3.7-flash) describe it, then use the text description as if you had seen the image.

When to use

• The user sends/pastes an image (you will see "image content omitted because you do not support image input" instead of the image)
• The user asks about a local image file (screenshots, photos, diagrams, PDF pages exported as images)
• The user shares an image URL
• You need OCR or visual inspection of any image file

How to run

Script: scripts/describe-image.js (Node.js, no dependencies; run with the node in PATH).

1. User-sent image (no file path known):

   node "<CODEX_HOME>\skills\stepfun-vision-skill\scripts\describe-image.js" --latest
   

   This scans the newest Codex session file, finds the most recent image the user sent (local temp path if still present, otherwise reconstructed from base64), and describes it.

2. Local image file:

   node "<CODEX_HOME>\skills\stepfun-vision-skill\scripts\describe-image.js" "C:\path\to\image.png"
   

   Multiple paths are allowed. Paths with spaces must be quoted.

3. Remote image URL:

   node "<CODEX_HOME>\skills\stepfun-vision-skill\scripts\describe-image.js" --url "https://example.com/img.png"
   

   http(s) URLs are also auto-detected without --url.

4. With a specific question:

   node "<CODEX_HOME>\skills\stepfun-vision-skill\scripts\describe-image.js" --prompt "What is the error message in this screenshot?" "C:\path\to\image.png"
   

<CODEX_HOME> is the Codex home directory, typically C:\Users\<user>\.codex (Windows) or ~/.codex (macOS/Linux).

API configuration

• Key source (first match wins): env var VISION_API_KEY → config.json ({"api_key": "..."}) in the skill directory.
• Endpoint/model/timeout/effort overrides: env vars VISION_API_ENDPOINT / VISION_API_MODEL / VISION_API_TIMEOUT_MS / VISION_REASONING_EFFORT, or the same keys in config.json.
• Default endpoint https://api.stepfun.com/v1/chat/completions, default model step-3.7-flash, default timeout 90 s, default reasoning_effort low.
• step-3.7-flash is a reasoning model: reasoning_effort keeps the thinking phase short so the final answer fits, and the script falls back to reasoning_content/reasoning when content is empty.
• A missing key (or the placeholder YOUR_STEPFUN_API_KEY_HERE) is a hard error telling the user to configure it. The installer (node scripts/install.js) writes the key into config.json and can also export VISION_API_KEY to the shell profile.

Provider guard (important)

The script refuses to run unless the main model in ~/.codex/config.toml is deepseek-v4-flash or deepseek-v4-pro (allowlist). It reads the model line from config.toml at startup and exits with an error otherwise. This guarantees the vision relay is only ever used on the DeepSeek provider, regardless of which provider the user switches to now or adds later. To change the allowlist, edit allowed_models in config.json or set env var VISION_ALLOWED_MODELS (comma-separated).

Notes

• The output is a factual text description; quote OCR text exactly, do not paraphrase.
• Network access required: the script calls the external vision API (api.stepfun.com). If the sandbox blocks it (error like "network restriction" or fetch/EAI_AGAIN), the command needs network permission — request it via network_access / require_escalated approval before retrying. If [sandbox_workspace_write] network_access = true is present in config.toml this will not be needed.
• If the script fails (network error, missing key), tell the user what happened and how to fix it (run the installer, or set VISION_API_KEY).
• The placeholder text in the conversation ("image content omitted...") means the image was never sent to your model; always recover it via --latest before answering anything image-related.
• Images larger than 25 MB are refused (8 MB warning) to protect the API call.