API & Verification
REST & OpenAPI Reference
All API endpoints live under https://api.splixir.com and authenticate with Bearer API keys (splx_...).
Authentication & headers#
Pass your API key from console.splixir.com in the Authorization header. API keys support granular scopes: jobs:write, jobs:read, billing:read, and webhooks:manage.
Authorization: Bearer splx_live_your_api_key_here
Content-Type: application/json
Idempotency-Key: optional-unique-request-id-max-128-charsHTTP status codes#
| Status | Meaning | Billed? | Description |
|---|---|---|---|
200 OK | Success | On delivery | Synchronous job completed (wait: true) or resource fetched. |
202 Accepted | Queued | Reserved | Asynchronous job accepted and queued for processing. |
401 Unauthorized | Auth error | $0 | Missing, invalid, or revoked API key, or missing required scope. |
402 Payment Required | Insufficient balance | $0 | Available wallet balance is lower than the job's pre-flight estimate. |
422 Unprocessable Entity | Validation error | $0 | Request body failed Zod schema validation or exceeded image limits. |
429 Too Many Requests | Rate limited | $0 | Per-key rate limit exceeded. Respect Retry-After header. |
501 Not Implemented | Unsupported kind | $0 | Submitted kind: "video" or "audio" during the Image MVP. |
/v1/jobsscope: jobs:writeCreates and validates a structured media transformation job, reserves the estimated microdollar cost, and dispatches it to the worker pool.
| Field | Type | Default / Required | Description |
|---|---|---|---|
kind | "image" | "video" | "audio" | Default: "image" | Use "image" for Image MVP. "video" and "audio" return 501. |
input | string | { url: string } | Required | HTTPS URL or pre-signed GET URL (or inputUrl from /v1/uploads/presign). |
operations | ImageOperation[] | Required (1–10) | Ordered array of structured operations. |
output | { format?, quality?, destination? } | Default: {} | Optional output format/quality override and optional pre-signed PUT destination URL. |
callbackUrl | string (URL) | Optional | Per-job webhook URL overriding your account default. |
idempotencyKey | string (1–128) | Optional | Prevents duplicate job creation on retries. |
metadata | Record<string, string> | Optional (max 16 keys) | Arbitrary key/value tags returned on job reads and webhooks. |
wait | boolean | Default: false | Hold connection up to 25s and return 200 OK once delivered/failed. |
{
"kind": "image",
"input": { "url": "https://example.com/source.png" },
"operations": [
{ "type": "crop", "mode": "aspect", "aspectRatio": "16:9", "gravity": "smart" },
{ "type": "resize", "width": 1280, "fit": "inside" },
{ "type": "convert", "format": "avif", "quality": 75 }
],
"wait": true
}/v1/jobsscope: jobs:readLists jobs for the authenticated account using cursor pagination. Query parameters: state, kind, limit (1–100, default 20), cursor.
/v1/jobs/:idscope: jobs:readRetrieves the full JobResponse including current state, output, verificationReport, and billed cost.
/v1/jobs/:idscope: jobs:writeCancels a non-terminal job (accepted, queued, etc.), transitions it to canceled, and releases any reserved funds ($0 billed).
/v1/jobs/:id/reportscope: jobs:readReturns the standalone VerificationReport JSON for a completed job.
/v1/uploads/presignscope: jobs:writeGenerates a short-lived pre-signed PUT URL to stage a local file in R2 for 24 hours before submitting a job.
{
"filename": "hero.jpg",
"contentType": "image/jpeg",
"bytes": 1482900
}{
"uploadUrl": "https://...r2.cloudflarestorage.com/...",
"inputUrl": "https://api.splixir.com/v1/inputs/...",
"expiresAt": "2026-11-23T14:25:00.000Z"
}/v1/balancescope: billing:readReturns total available balance in USD and microdollars, broken down across promoMicros, subscriptionMicros, purchasedMicros, active reservedMicros, and spendOrder.
/v1/usagescope: billing:readReturns paginated wallet ledger entries (promo_grant, topup, subscription_grant, reserve, capture, release, refund).
/openapi.jsonUnauthenticated OpenAPI 3.1 JSON specification generated directly from @splixir/types Zod schemas.
Live OpenAPI 3.1 Specification
GET https://api.splixir.com/openapi.json
Need client SDKs?
@splixir/types in TypeScript projects for full Zod validation and type inference, or generate a typed client from https://api.splixir.com/openapi.json.