SmartAPI Images for Codex

smartapi-images packages a local MCP server and a Codex skill for generating one image through SmartAPI's explicit POST /v1/images/generations endpoint.

The Codex reasoning model remains a text model such as gpt-5.6-sol. When the user asks for an image, Codex calls the generate_image tool, which spends the user's SmartAPI balance and saves the returned image locally.

Requirements

Node.js 20 or newer
A normal SmartAPI user key with enough available balance

Local setup

corepack pnpm install
corepack pnpm check
export SMARTAPI_API_KEY='sk-smart-...'

The default API URL is https://api.smartapi.shop/v1. Generated files are written to ~/Pictures/SmartAPI by default. Override either setting without editing the repository:

export SMARTAPI_BASE_URL='https://api.smartapi.shop/v1'
export SMARTAPI_IMAGE_OUTPUT_DIR="$HOME/Pictures/SmartAPI"

For a direct Codex MCP configuration:

[mcp_servers.smartapi_images]
command = "node"
args = ["/absolute/path/to/smartapi-images/dist/index.js"]
env_vars = ["SMARTAPI_API_KEY", "SMARTAPI_BASE_URL", "SMARTAPI_IMAGE_OUTPUT_DIR"]
tool_timeout_sec = 360
enabled_tools = ["generate_image"]

Never put a SmartAPI key in .mcp.json, config.toml, source files, logs, or Git.

Tool

generate_image accepts:

prompt: required image description
size: auto or any WIDTHxHEIGHT; SmartAPI reports the normalized effective size
quality: auto, low, medium, or high
output_format: png, jpeg, or webp
filename: optional safe filename without an extension

The tool never overwrites a file and never retries an ambiguous network or timeout failure. It returns the absolute file path, effective size, charged tokens, and SmartAPI request ID.

Development

corepack pnpm typecheck
corepack pnpm test
corepack pnpm build

Tests use a local mock HTTP server and never call SmartAPI.