openrouter

# OpenRouter

Gateway to 300+ AI models through a unified API. Requires `SKILL_OPENROUTER_API_KEY` environment variable.

## Setup

```bash
export SKILL_OPENROUTER_API_KEY="sk-or-..."  # Get key at https://openrouter.ai/keys
```

## Sandbox Compatibility

⚠️ **macOS Limitation**: On macOS, `uv run` may require `dangerouslyDisableSandbox: true` because UV accesses system configuration APIs (`SystemConfiguration.framework`) to detect proxy settings. This is a known UV limitation on macOS systems.

**Behavior:**
- On first execution, Claude may attempt with sandbox enabled
- If it fails with system-configuration errors, Claude will retry with sandbox disabled
- This is expected behavior and does not indicate a security issue

**Alternative (for restricted environments):**
If sandbox restrictions are problematic, you can pre-install dependencies:
```bash
python3 -m pip install requests
python3 /absolute/path/to/scripts/openrouter_client.py chat MODEL "prompt"
```

However, we recommend the standard UV approach for portability and zero-setup benefits.

**Why UV is preferred:**
- Zero setup required (no pip install step)
- Dependencies declared inline (PEP 723 standard)
- Automatic caching and fast execution
- Full portability across systems
- Official Anthropic/Claude Code recommendation

## Quick Reference

**Text completion:**
```bash
UV_CACHE_DIR=/tmp/claude/uv-cache uv run --with requests scripts/openrouter_client.py chat MODEL "prompt" [--system "sys"] [--max-tokens N] [--temperature T]
```

**Image generation:**
```bash
UV_CACHE_DIR=/tmp/claude/uv-cache uv run --with requests scripts/openrouter_client.py image MODEL "description" [--output /absolute/path/file.png] [--aspect 16:9] [--size 2K] [--background transparent] [--quality high] [--output-format png]
```

**Model discovery:**
```bash
UV_CACHE_DIR=/tmp/claude/uv-cache uv run --with requests scripts/openrouter_client.py models [vision|image_gen|tools|long_context]
UV_CACHE_DIR=/tmp/claude/uv-cache uv run --with