# Nano Studio Pro

> AI image generation and editing platform with a public REST API. Authenticated users get a CLI (`nsp`), a token-based API at `/v1`, and an OpenAPI spec for tool discovery.

## How an agent should use this

1. Run `nsp whoami` to check if the user is logged in. If `command not found`, install with `curl https://nanostudiopro.com/cli/nsp | node -` (or just hit the API directly with their token).
2. If 401 / not logged in: tell the user to run `nsp login` (opens browser, RFC 8628 device flow).
3. For unknown endpoints: fetch `/api/openapi` and read the spec.
4. Capability detection (does this server support feature X?): `GET /v1/meta` — no auth required.

## Auth

- **Token storage:** `~/.config/nsp/credentials.json` (mode 0600). Format: `{ "access_token": "sk_sf_live_...", "server": "https://nanostudiopro.com" }`.
- **Header:** `Authorization: Bearer sk_sf_live_...`
- **Get the token from the CLI:** `nsp token` (prints to stdout, safe to pipe into curl).
- **Manual PAT:** Settings → API Tokens at https://nanostudiopro.com/settings/api-tokens.

## CLI (`nsp`)

Pure Node, no deps. Install: `curl https://nanostudiopro.com/cli/nsp | node -` (or save to `/usr/local/bin/nsp` and `chmod +x`).

| Command | Purpose |
|---|---|
| `nsp login` | Device-flow auth (opens browser) |
| `nsp logout` | Delete saved token |
| `nsp whoami` | Show current user (verifies session) |
| `nsp credits` | Wallet balance + token daily cap |
| `nsp pricing` | Credit cost per operation |
| `nsp token` | Print saved token (for piping) |
| `nsp mcp` | Run the MCP server (downloads/caches on first use) |

Override server: `NSP_SERVER=https://staging.example.com nsp whoami`.

## API endpoints

Base: `https://nanostudiopro.com/api/v1`

### Generative
- `POST /v1/generations` — create an image generation. Returns `{ task_id, ...generation }`. Supports up to **14 reference images** — either upload inline via multipart (`reference_file[]`) or pass existing asset IDs (`reference_asset_id[]`). Uploaded files are auto-saved to the user's asset library; their IDs come back as `saved_asset_ids`. Requires `project_id`.
- `POST /v1/restyle` — AI-edit an existing generation into a NEW one: plain-text edits (`instructions`), one-click product placement (`action: "bring"` + `reference_id`), item recolor/remove/add (`items` names from detections), two-image merge, art-style transfer. `reference_id` = any asset or generation you own.
- `POST /v1/expand` — outpaint to a bigger canvas / new `target_aspect_ratio` (directional `extend`, `zoom` < 1 zooms out).
- `POST /v1/upscale` — re-render at a higher `resolution` (1K/2K/4K).
- `POST /v1/cutouts` — subject cutout: transparent PNG + matte + clean background plate. One image per call.
- `POST /v1/videos` — animate a generation into a 5s/10s video (Kling; std/pro, optional audio on kling-v3*). Async: poll `GET /v1/videos/{task_id}`. Credits deduct on completion; requires purchased credits (`402 video_requires_purchase` on trial).

### Detections (free)
- `GET /v1/detections/{target_id}?type=generation|asset` — what the detection engine sees: item names, categories, textures, hex colors, bounding boxes (0-1000 normalized), scene narrative. Every generation/import is scanned automatically.
- `POST /v1/scans` — run the scan on a never-scanned image (inline, ~5-20s, free).

### Search & assets
- `GET /v1/search?q=...` — full-text + detection-aware search across the user's assets. Supports `regions`, `image_size`, `colors`, date range, sort, aspect filter.
- `GET /v1/assets/{id}` — asset metadata.

### Tasks
- `GET /v1/tasks` — list async tasks.
- `GET /v1/tasks/{id}` — single task status.
- `GET /v1/tasks/stream` — Server-Sent Events stream of task updates.
- `POST /v1/tasks/{id}/cancel` / `POST /v1/tasks/{id}/retry`.

### Account
- `GET /v1/me` — user profile + quotas.
- `GET /v1/account/credits` — balance + token daily-cap status.
- `GET /v1/account/credits/history` — credit transactions.
- `GET /v1/account/usage` — daily timeseries (operation count).
- `GET /v1/account/tokens` — list user's API tokens.
- `GET /v1/account/connected_apps` — OAuth apps the user has authorized.

### Discovery (no auth)
- `GET /v1/meta` — version + capability flags. Use for feature detection instead of parsing OpenAPI.
- `GET /v1/pricing` — credit cost per operation.
- `GET /api/openapi` — full OpenAPI 3.1 spec.
- `GET /docs` — Scalar interactive docs UI.

## MCP (Model Context Protocol)

- **Remote**: `POST https://nanostudiopro.com/api/mcp` — 30 tools (generation, editing/restyle, cutouts, expand/upscale, video, detections, search, projects, assets, tasks) over JSON-RPC 2.0. Authenticate with `Authorization: Bearer sk_sf_live_...`, or via OAuth 2.1: hosts that speak OAuth (claude.ai / Claude Desktop custom connectors) just paste the URL — discovery at `/.well-known/oauth-authorization-server`, dynamic registration supported, PKCE S256 required. Claude Code with a token: `claude mcp add --transport http --scope user nanostudio https://nanostudiopro.com/api/mcp --header "Authorization: Bearer <token>"`.
- **Local (stdio)**: with the CLI installed, `claude mcp add --scope user nanostudio nsp mcp` is the whole setup (`nsp mcp` downloads/caches the server on first use). Standalone: `curl -fsSL https://nanostudiopro.com/cli/mcp -o /usr/local/bin/nsp-mcp && chmod +x /usr/local/bin/nsp-mcp`. Same tools plus local-file parameters (`path`, `save_to`). Reuses the CLI's saved login — and if not signed in, the first tool call starts a device sign-in and returns the approval URL to relay to the user.
- Tip: `import_image` and `upload_asset` accept ANY image, not just ones generated here. Imports get the full detection scan (objects, colors, textures) and become searchable via `search` — bring existing product shots and artwork.

## Errors

All error responses follow:
```json
{ "error": { "code": "string_constant", "message": "human-readable" } }
```

Common codes: `unauthorized`, `insufficient_credits`, `token_cap_exceeded` (HTTP 402, set per-token `dailyCreditCap`), `rate_limited` (HTTP 429, check `Retry-After`), `not_found`, `validation_error`.

## Quick verification snippet

```bash
# Check session
nsp whoami || echo "Not logged in — run: nsp login"

# Or direct curl (if nsp not installed)
curl -H "Authorization: Bearer $(cat ~/.config/nsp/credentials.json | jq -r .access_token)" \
     https://nanostudiopro.com/api/v1/me
```

## Links

- [API docs (interactive)](https://nanostudiopro.com/docs): Scalar UI for the REST API.
- [OpenAPI spec](https://nanostudiopro.com/api/openapi): full OpenAPI 3.1 spec for tool discovery.
- [CLI reference](https://nanostudiopro.com/docs/cli): the `nsp` command-line tool.
- [Device-flow auth guide](https://nanostudiopro.com/docs/device-auth): RFC 8628 login for CLIs and agents.
- [MCP guide](https://nanostudiopro.com/docs/mcp): Model Context Protocol integration.
- [Token management](https://nanostudiopro.com/settings/api-tokens): create and revoke API tokens.