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.

Headershttp
Authorization: Bearer splx_live_your_api_key_here
Content-Type: application/json
Idempotency-Key: optional-unique-request-id-max-128-chars

HTTP status codes#

StatusMeaningBilled?Description
200 OKSuccessOn deliverySynchronous job completed (wait: true) or resource fetched.
202 AcceptedQueuedReservedAsynchronous job accepted and queued for processing.
401 UnauthorizedAuth error$0Missing, invalid, or revoked API key, or missing required scope.
402 Payment RequiredInsufficient balance$0Available wallet balance is lower than the job's pre-flight estimate.
422 Unprocessable EntityValidation error$0Request body failed Zod schema validation or exceeded image limits.
429 Too Many RequestsRate limited$0Per-key rate limit exceeded. Respect Retry-After header.
501 Not ImplementedUnsupported kind$0Submitted kind: "video" or "audio" during the Image MVP.
POST/v1/jobsscope: jobs:write

Creates and validates a structured media transformation job, reserves the estimated microdollar cost, and dispatches it to the worker pool.

FieldTypeDefault / RequiredDescription
kind"image" | "video" | "audio"Default: "image"Use "image" for Image MVP. "video" and "audio" return 501.
inputstring | { url: string }RequiredHTTPS URL or pre-signed GET URL (or inputUrl from /v1/uploads/presign).
operationsImageOperation[]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.
callbackUrlstring (URL)OptionalPer-job webhook URL overriding your account default.
idempotencyKeystring (1–128)OptionalPrevents duplicate job creation on retries.
metadataRecord<string, string>Optional (max 16 keys)Arbitrary key/value tags returned on job reads and webhooks.
waitbooleanDefault: falseHold connection up to 25s and return 200 OK once delivered/failed.
POST /v1/jobs — Requestjson
{
  "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
}
GET/v1/jobsscope: jobs:read

Lists jobs for the authenticated account using cursor pagination. Query parameters: state, kind, limit (1–100, default 20), cursor.

GET/v1/jobs/:idscope: jobs:read

Retrieves the full JobResponse including current state, output, verificationReport, and billed cost.

DELETE/v1/jobs/:idscope: jobs:write

Cancels a non-terminal job (accepted, queued, etc.), transitions it to canceled, and releases any reserved funds ($0 billed).

GET/v1/jobs/:id/reportscope: jobs:read

Returns the standalone VerificationReport JSON for a completed job.

POST/v1/uploads/presignscope: jobs:write

Generates a short-lived pre-signed PUT URL to stage a local file in R2 for 24 hours before submitting a job.

Requestjson
{
  "filename": "hero.jpg",
  "contentType": "image/jpeg",
  "bytes": 1482900
}
200 OKjson
{
  "uploadUrl": "https://...r2.cloudflarestorage.com/...",
  "inputUrl": "https://api.splixir.com/v1/inputs/...",
  "expiresAt": "2026-11-23T14:25:00.000Z"
}
GET/v1/balancescope: billing:read

Returns total available balance in USD and microdollars, broken down across promoMicros, subscriptionMicros, purchasedMicros, active reservedMicros, and spendOrder.

GET/v1/usagescope: billing:read

Returns paginated wallet ledger entries (promo_grant, topup, subscription_grant, reserve, capture, release, refund).

GET/openapi.json

Unauthenticated OpenAPI 3.1 JSON specification generated directly from @splixir/types Zod schemas.

Live OpenAPI 3.1 Specification

GET https://api.splixir.com/openapi.json

Open Raw JSON ↗

Need client SDKs?

Import @splixir/types in TypeScript projects for full Zod validation and type inference, or generate a typed client from https://api.splixir.com/openapi.json.