# SPLIXIR — Complete Documentation (llms-full.txt) > Managed media transformation API on elastic compute. > Base API: https://api.splixir.com > Hosted MCP: https://mcp.splixir.com > Console: https://console.splixir.com > Docs: https://docs.splixir.com --- ## 1. Core Principles 1. **Structured jobs only** — Never pass raw FFmpeg flags. Jobs use typed JSON operations (`resize`, `crop`, `convert`, `strip_metadata`, `rotate`). 2. **Zero custody & zero bandwidth fees** — Pass remote HTTPS URLs, pre-signed `PUT` destinations, or stage local files for 24h via `POST /v1/uploads/presign`. Ingress and egress are never billed. 3. **Verification gates delivery / failed jobs bill $0** — Every output is re-probed before delivery and includes a `VerificationReport`. Failures release the pre-flight 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). --- ## 2. 60-Second Quickstart Sign in at `https://console.splixir.com`, verify your email to claim **$1.00 in free promo credit** (valid 30 days, ~1,000 standard WebP/JPEG/PNG images), and create an API key (`splx_...`). ```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 }' ``` `wait: true` holds the connection up to 25 seconds and returns `200 OK` with `output.downloadUrl` (24h ephemeral R2 URL) and `verificationReport`. --- ## 3. Splixir Image Operations Up to `10` operations per job, executed sequentially: - **resize**: `{ "type": "resize", "width"?: 1..16384, "height"?: 1..16384, "fit"?: "inside"|"contain"|"cover"|"fill"|"outside", "withoutEnlargement"?: true, "background"?: "#hex" }` (at least one of `width` or `height` required). - **crop (region)**: `{ "type": "crop", "mode": "region", "x": >=0, "y": >=0, "width": 1..16384, "height": 1..16384 }`. - **crop (aspect)**: `{ "type": "crop", "mode": "aspect", "aspectRatio": "W:H", "gravity"?: "center"|"north"|"south"|"east"|"west"|"smart" }`. - **convert**: `{ "type": "convert", "format": "webp"|"avif"|"png"|"jpeg", "quality"?: 1..100, "lossless"?: boolean, "progressive"?: boolean }`. - **strip_metadata**: `{ "type": "strip_metadata", "keepOrientation"?: true, "keepColorProfile"?: true }`. - **rotate**: `{ "type": "rotate", "angle": 90|180|270 }`. **Limits:** - Max input size: `50 MiB` (`52,428,800` bytes) - Max megapixels: `100 MP` - Max dimension: `16,384 px` - Max operations per job: `10` - Sync `wait: true` timeout: `25s` - Ephemeral R2 staging & downloadUrl TTL: `24 hours` - Video (`transcode`, `trim`, `thumbnail`) & Audio (`convert`, `normalize`) schemas are reserved and return `501 Not Implemented` during the Image MVP. --- ## 4. REST API Reference (`https://api.splixir.com`) Auth header: `Authorization: Bearer splx_...` API key scopes: `jobs:write`, `jobs:read`, `billing:read`, `webhooks:manage`. - `POST /v1/jobs` (`jobs:write`) — Submit job (`200` if `wait: true` completes, `202` async). - `GET /v1/jobs` (`jobs:read`) — List jobs (`?state=&kind=&limit=1..100&cursor=`). - `GET /v1/jobs/:id` (`jobs:read`) — Get `JobResponse`. - `DELETE /v1/jobs/:id` (`jobs:write`) — Cancel non-terminal job and release reservation ($0 billed). - `GET /v1/jobs/:id/report` (`jobs:read`) — Get `VerificationReport`. - `POST /v1/uploads/presign` (`jobs:write`) — Request `{ uploadUrl, inputUrl, expiresAt }` for `{ filename, contentType, bytes }`. - `GET /v1/balance` (`billing:read`) — Get wallet balance (`promoMicros`, `subscriptionMicros`, `purchasedMicros`, `reservedMicros`, `spendOrder`). - `GET /v1/usage` (`billing:read`) — Get paginated wallet ledger entries. - `GET /openapi.json` (public) — OpenAPI 3.1 JSON specification. **HTTP Status Codes:** `200`, `202`, `401` (auth/scope), `402` (insufficient balance), `422` (validation/limits), `429` (rate limit), `501` (video/audio in Image MVP). --- ## 5. Pricing & Wallet 1 USD = `1,000,000` microdollars. - **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 (ingress & egress):** `$0.00` - **Failed / rejected / canceled jobs:** `$0.00` **Wallet & Plans:** - **Free trial:** `$1.00` promo credit on verified email signup (valid 30 days). - **Prepaid top-up:** Custom amounts from `$5.00` to `$10,000`, never expires. - **Monthly bonus plans:** Starter (`$10 -> $12`), Growth (`$20 -> $25`), Scale (`$50 -> $60`), Studio (`$100 -> $120`). - **Spend order:** `Promo -> Monthly Allowance -> Prepaid`. --- ## 6. Webhooks & Verification Gate - **Events:** `job.delivered`, `job.failed`, `job.rejected`. - **Payload:** `{ id, event, timestamp, data: JobResponse }`. - **Error classes:** `CUSTOMER_FAULT` (retryable: false), `VERIFY_FAILED` (retryable: false), `INFRA_FAILURE` (retryable: true). All bill `$0.00`. - **Retries:** Up to 5 attempts with exponential backoff (10s, 30s, 2m, 10m, 30m). - **Signature header:** `X-Splixir-Signature` = hex HMAC-SHA256 of raw body using your `whsec_...` secret. Verify with constant-time comparison. --- ## 7. Splixir CLI (`npm i -g splixir`) - `splixir login [--key splx_...] [--api-url ...]` - `splixir logout` / `splixir whoami` / `splixir balance [--json]` - `splixir image [--resize WxH] [--fit mode] [--allow-enlargement] [--crop x,y,w,h] [--aspect W:H] [--gravity pos] [--format webp|avif|png|jpeg] [--quality 1-100] [--lossless] [--progressive] [--strip|--no-strip] [--rotate 90|180|270] [-o path] [--destination url] [--callback url] [--no-wait] [--json]` - `splixir init [--kind image] [--force]` - `splixir validate [--json]` - `splixir job submit|status|list|report|cancel` - `splixir docs` --- ## 8. MCP Server - **Hosted Remote MCP (Streamable HTTP):** `https://mcp.splixir.com` with `Authorization: Bearer splx_...` - **Local Stdio MCP:** `npx -y splixir mcp` with `SPLIXIR_API_KEY=splx_...` (supports local file staging) - **Tools:** `splixir_transform_image`, `splixir_get_job`, `splixir_list_jobs`, `splixir_get_balance`, `splixir_validate_job` (offline), `splixir_estimate_cost` (offline). - **Resources:** `splixir://balance`, `splixir://pricing`.