Getting Started
Splixir Image
Declarative, ordered image transformation pipelines executed on elastic CPU workers and gated by output verification.
How operations execute#
An Image job accepts an ordered operations array (1 to 10 operations). Operations run sequentially in the exact order provided. All schemas are validated against @splixir/types before any compute is provisioned.
resize#
Resizes the image to target dimensions. At least one of width or height must be specified.
| Field | Type | Default / Required | Description |
|---|---|---|---|
type | "resize" | Required | Operation discriminator. |
width | integer (1–16384) | Optional* | Target width in pixels. Required if height is omitted. |
height | integer (1–16384) | Optional* | Target height in pixels. Required if width is omitted. |
fit | "inside" | "contain" | "cover" | "fill" | "outside" | Default: "inside" | inside preserves aspect ratio within bounds; cover fills bounds and crops excess; contain pads to bounds using background; fill stretches; outside scales so smallest side matches. |
withoutEnlargement | boolean | Default: true | Prevents upscaling if the source image is smaller than the target dimensions. |
background | hex string | Optional | Letterbox/padding color for fit: "contain" (e.g. "#ffffff" or "#0050ff80"). |
{
"type": "resize",
"width": 1200,
"height": 800,
"fit": "cover",
"withoutEnlargement": true
}crop#
Crops the image using either an explicit pixel bounding box (mode: "region") or a target aspect ratio with gravity (mode: "aspect").
Region crop (mode: "region")#
| Field | Type | Default / Required | Description |
|---|---|---|---|
type | "crop" | Required | Operation discriminator. |
mode | "region" | Required | Explicit pixel rectangle crop. |
x | integer (>= 0) | Required | Left offset in pixels. |
y | integer (>= 0) | Required | Top offset in pixels. |
width | integer (1–16384) | Required | Crop width in pixels. |
height | integer (1–16384) | Required | Crop height in pixels. |
Aspect crop (mode: "aspect")#
| Field | Type | Default / Required | Description |
|---|---|---|---|
type | "crop" | Required | Operation discriminator. |
mode | "aspect" | Required | Aspect-ratio crop. |
aspectRatio | string ("W:H") | Required | Positive integer ratio, e.g. "16:9", "4:5", "1:1". |
gravity | "center" | "north" | "south" | "east" | "west" | "smart" | Default: "center" | Anchor point when trimming excess pixels. smart uses entropy/attention-based focal detection. |
[
{ "type": "crop", "mode": "aspect", "aspectRatio": "16:9", "gravity": "smart" },
{ "type": "crop", "mode": "region", "x": 100, "y": 50, "width": 800, "height": 600 }
]convert#
Encodes the output image to a target format. You can also specify output.format and output.quality at the top level of the job request.
| Field | Type | Default / Required | Description |
|---|---|---|---|
type | "convert" | Required | Operation discriminator. |
format | "webp" | "avif" | "png" | "jpeg" | Required | Target output format. AVIF carries a +$0.0010 encoding surcharge. |
quality | integer (1–100) | Optional | Encoder quality factor (applies to webp, avif, jpeg). |
lossless | boolean | Optional | Enable lossless compression (webp, avif). |
progressive | boolean | Optional | Enable progressive/interlaced encoding (jpeg, png). |
strip_metadata#
Removes EXIF, XMP, IPTC, and GPS tags for privacy and smaller payloads, while optionally preserving orientation and ICC color profiles.
| Field | Type | Default / Required | Description |
|---|---|---|---|
type | "strip_metadata" | Required | Operation discriminator. |
keepOrientation | boolean | Default: true | Auto-orients pixel data from EXIF Orientation before stripping the tag. |
keepColorProfile | boolean | Default: true | Preserves embedded ICC profile (e.g., Display P3 / sRGB) so colors do not shift. |
rotate#
Rotates the image clockwise by an exact right angle.
| Field | Type | Default / Required | Description |
|---|---|---|---|
type | "rotate" | Required | Operation discriminator. |
angle | 90 | 180 | 270 | Required | Clockwise rotation angle in degrees. |
Limits & constraints#
| Limit | Value | Enforcement | Description |
|---|---|---|---|
Max input size | 50 MiB (52,428,800 B) | 422 / CUSTOMER_FAULT | Checked at pre-flight probe and worker download. |
Max megapixels | 100 MP | 422 / CUSTOMER_FAULT | Width × height must not exceed 100,000,000 pixels. |
Max dimension | 16,384 px | 422 Validation | Maximum width or height for input and output. |
Max operations | 10 per job | 422 Validation | Up to 10 chained operations per job. |
Sync wait timeout | 25s | wait: true | If a job takes longer than 25s, poll GET /v1/jobs/:id or use a webhook. |
Ephemeral staging TTL | 24 hours | Automatic | Staged inputs and ephemeral R2 output downloadUrls expire automatically after 24 hours. |
Input & output modes#
Splixir supports three zero-custody I/O patterns:
- Remote URL → 24h Ephemeral Download URL: Pass any public HTTPS URL (or pre-signed GET URL) in
inputand omitoutput.destination. Splixir returns a signedoutput.downloadUrlvalid for 24 hours. - Cloud-to-Cloud Direct Delivery: Supply a pre-signed
PUTURL inoutput.destination(S3, R2, GCS). Splixir streams the verified output directly to your bucket. - Local File Staging: Call
POST /v1/uploads/presignto get a temporaryuploadUrl+inputUrl,PUTyour local file bytes, then submitPOST /v1/jobswithinputUrl. Thesplixir image ./photo.jpgCLI and MCP server automate this automatically.
Video & Audio roadmap#
Video & Audio schemas are reserved
@splixir/types already exports VideoOperationSchema and AudioOperationSchema. Submitting kind: "video" or kind: "audio" during the Image MVP returns 501 Not Implemented with zero charge.