---
name: splixir
description: Add Splixir managed media transformation (Image MVP live; Video & Audio schemas reserved) to an application via REST API, CLI, or MCP.
---

# Splixir — Agent Setup Skill

Splixir is a managed media transformation API on elastic compute. Submit structured JSON jobs, receive verified outputs, and pay only for verified deliveries.

- **Console & API Keys:** `https://console.splixir.com`
- **REST API:** `https://api.splixir.com` (`GET /openapi.json` for OpenAPI 3.1 spec)
- **Hosted Remote MCP:** `https://mcp.splixir.com` (Streamable HTTP)
- **Documentation:** `https://docs.splixir.com` (`https://docs.splixir.com/llms.txt`, `https://docs.splixir.com/llms-full.txt`)
- **Website:** `https://splixir.com`

## Core Rules (Non-Negotiable)

1. **Structured jobs only** — Never pass raw FFmpeg flags. Use typed operations (`resize`, `crop`, `convert`, `strip_metadata`, `rotate`).
2. **Zero custody & zero bandwidth fees** — Pass remote URLs, pre-signed `PUT` destinations, or stage local files for 24h via `POST /v1/uploads/presign`. Ingress/egress are never billed.
3. **Verification gates delivery / failed jobs bill $0** — Every output is re-probed before delivery and returns a `VerificationReport`. Failures release the reservation and bill `$0.00`.
4. **Capability before cost** — Hardware/codec capability routes first (Image CPU now; Video AV1 → Ada/Blackwell+, 4:2:2 → Blackwell coming next; `kind: "video"` / `"audio"` return `501` in Image MVP).

## Step 1: Get an API Key ($1.00 Free Trial)

1. Ask the user to sign in at `https://console.splixir.com` and verify their email.
   - Verified accounts automatically receive **$1.00 in free promo credit** (valid 30 days, ~1,000 standard WebP/JPEG/PNG image transforms, no credit card required).
2. Create an API key (`splx_...`) in the Console with required scopes (`jobs:write`, `jobs:read`, `billing:read`, `webhooks:manage`).
3. Store it in `.env` as `SPLIXIR_API_KEY=splx_...` (never commit secrets).

## Step 2: Choose Integration Path

### Option A: REST API (`https://api.splixir.com`)

Submit a synchronous Image job (`wait: true` holds up to 25s and returns `200 OK` with `output.downloadUrl` and `verificationReport`):

```bash
curl -X POST https://api.splixir.com/v1/jobs \
  -H "Authorization: Bearer $SPLIXIR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "image",
    "input": { "url": "https://example.com/photo.jpg" },
    "operations": [
      { "type": "resize", "width": 1200, "fit": "inside", "withoutEnlargement": true },
      { "type": "convert", "format": "webp", "quality": 85 },
      { "type": "strip_metadata", "keepOrientation": true, "keepColorProfile": true }
    ],
    "wait": true
  }'
```

**Available Image Operations (max 10 per job, 50 MiB, 100 MP, 16384px):**

- `resize`: `{ type: "resize", width?, height?, fit?: "inside"|"contain"|"cover"|"fill"|"outside", withoutEnlargement?: true, background?: "#hex" }`
- `crop` (region): `{ type: "crop", mode: "region", x, y, width, height }`
- `crop` (aspect): `{ type: "crop", mode: "aspect", aspectRatio: "16:9", gravity?: "center"|"north"|"south"|"east"|"west"|"smart" }`
- `convert`: `{ type: "convert", format: "webp"|"avif"|"png"|"jpeg", quality?: 1..100, lossless?, progressive? }`
- `strip_metadata`: `{ type: "strip_metadata", keepOrientation?: true, keepColorProfile?: true }`
- `rotate`: `{ type: "rotate", angle: 90|180|270 }`

**Key Endpoints:**

- `POST /v1/jobs` — Create & run job (`200` if `wait: true` finishes, `202` async)
- `GET /v1/jobs` — List jobs (`?state=&kind=&limit=&cursor=`)
- `GET /v1/jobs/:id` — Get job status, output URL, and `verificationReport`
- `DELETE /v1/jobs/:id` — Cancel non-terminal job ($0 billed)
- `GET /v1/jobs/:id/report` — Get `VerificationReport` JSON
- `POST /v1/uploads/presign` — Stage a local file (`{ filename, contentType, bytes }` → `{ uploadUrl, inputUrl }`)
- `GET /v1/balance` — Wallet balance (`promoMicros`, `subscriptionMicros`, `purchasedMicros`, `spendOrder`)
- `GET /v1/usage` — Wallet ledger entries
- `GET /openapi.json` — OpenAPI 3.1 specification

### Option B: Splixir CLI (`npm i -g splixir` or `npx splixir`)

```bash
npx splixir login --key "$SPLIXIR_API_KEY"
npx splixir image ./local-photo.jpg --resize 1200x800 --fit cover --format webp --quality 85 -o hero.webp
npx splixir validate splixir.job.json
npx splixir balance --json
```

### Option C: Model Context Protocol (MCP)

- **Hosted Remote MCP (Streamable HTTP):**
  - URL: `https://mcp.splixir.com`
  - Header: `Authorization: Bearer splx_...`
- **Local Stdio MCP (supports local file uploads):**
  - Command: `npx -y splixir mcp`
  - Env: `SPLIXIR_API_KEY=splx_...`

**Tools exposed:** `splixir_transform_image`, `splixir_get_job`, `splixir_list_jobs`, `splixir_get_balance`, `splixir_validate_job` (offline), `splixir_estimate_cost` (offline).
**Resources exposed:** `splixir://balance`, `splixir://pricing`.

## Pricing Summary (Microdollars: 1 USD = 1,000,000)

- **Base verified image:** `$0.0010` (`1,000` micros)
- **AVIF encoding surcharge:** `+$0.0010` (`+1,000` micros)
- **High-res surcharge (>12 MP input or output):** `+$0.0005` (`+500` micros)
- **Bandwidth & failed/rejected/canceled jobs:** `$0.00`
- **Spend order:** `Promo ($1 free trial) -> Monthly Allowance ($10->$12, $20->$25, $50->$60, $100->$120) -> Prepaid (min $5, never expires)`

## Webhooks

Verify `X-Splixir-Signature` (hex HMAC-SHA256 of raw request body using your `whsec_...` secret) with constant-time comparison. Events: `job.delivered`, `job.failed`, `job.rejected`.
