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.

FieldTypeDefault / RequiredDescription
type"resize"RequiredOperation discriminator.
widthinteger (1–16384)Optional*Target width in pixels. Required if height is omitted.
heightinteger (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.
withoutEnlargementbooleanDefault: truePrevents upscaling if the source image is smaller than the target dimensions.
backgroundhex stringOptionalLetterbox/padding color for fit: "contain" (e.g. "#ffffff" or "#0050ff80").
resize.jsonjson
{
  "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")#

FieldTypeDefault / RequiredDescription
type"crop"RequiredOperation discriminator.
mode"region"RequiredExplicit pixel rectangle crop.
xinteger (>= 0)RequiredLeft offset in pixels.
yinteger (>= 0)RequiredTop offset in pixels.
widthinteger (1–16384)RequiredCrop width in pixels.
heightinteger (1–16384)RequiredCrop height in pixels.

Aspect crop (mode: "aspect")#

FieldTypeDefault / RequiredDescription
type"crop"RequiredOperation discriminator.
mode"aspect"RequiredAspect-ratio crop.
aspectRatiostring ("W:H")RequiredPositive 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.
crop-examples.jsonjson
[
  { "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.

FieldTypeDefault / RequiredDescription
type"convert"RequiredOperation discriminator.
format"webp" | "avif" | "png" | "jpeg"RequiredTarget output format. AVIF carries a +$0.0010 encoding surcharge.
qualityinteger (1–100)OptionalEncoder quality factor (applies to webp, avif, jpeg).
losslessbooleanOptionalEnable lossless compression (webp, avif).
progressivebooleanOptionalEnable 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.

FieldTypeDefault / RequiredDescription
type"strip_metadata"RequiredOperation discriminator.
keepOrientationbooleanDefault: trueAuto-orients pixel data from EXIF Orientation before stripping the tag.
keepColorProfilebooleanDefault: truePreserves embedded ICC profile (e.g., Display P3 / sRGB) so colors do not shift.

rotate#

Rotates the image clockwise by an exact right angle.

FieldTypeDefault / RequiredDescription
type"rotate"RequiredOperation discriminator.
angle90 | 180 | 270RequiredClockwise rotation angle in degrees.

Limits & constraints#

LimitValueEnforcementDescription
Max input size50 MiB (52,428,800 B)422 / CUSTOMER_FAULTChecked at pre-flight probe and worker download.
Max megapixels100 MP422 / CUSTOMER_FAULTWidth × height must not exceed 100,000,000 pixels.
Max dimension16,384 px422 ValidationMaximum width or height for input and output.
Max operations10 per job422 ValidationUp to 10 chained operations per job.
Sync wait timeout25swait: trueIf a job takes longer than 25s, poll GET /v1/jobs/:id or use a webhook.
Ephemeral staging TTL24 hoursAutomaticStaged 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 input and omit output.destination. Splixir returns a signed output.downloadUrl valid for 24 hours.
  • Cloud-to-Cloud Direct Delivery: Supply a pre-signed PUT URL in output.destination (S3, R2, GCS). Splixir streams the verified output directly to your bucket.
  • Local File Staging: Call POST /v1/uploads/presign to get a temporary uploadUrl + inputUrl, PUT your local file bytes, then submit POST /v1/jobs with inputUrl. The splixir image ./photo.jpg CLI and MCP server automate this automatically.

Video & Audio roadmap#

Video & Audio schemas are reserved

Video: transcode / trim / thumbnailAudio: convert / normalize

@splixir/types already exports VideoOperationSchema and AudioOperationSchema. Submitting kind: "video" or kind: "audio" during the Image MVP returns 501 Not Implemented with zero charge.