# 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

```bash
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:

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

For a direct Codex MCP configuration:

```toml
[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

```bash
corepack pnpm typecheck
corepack pnpm test
corepack pnpm build
```

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