Delivery & Transform URL Grammar

Once an image is uploaded you transform it on the fly via its URL — no second API call. This page is the complete grammar for those URLs.

The shape

Paid tier (your dedicated subdomain):

https://<subdomain>.viucraft.com/<operations>/<image_id>.<ext>

Free tier (shared host, namespaced by account):

https://viucraft.com/free/acc_<customer_id>/<operations>/<image_id>.<ext>

See Tenancy & URL Bases for which host to use.

Three rules

1. The file extension is mandatory. The image_id is a bare UUID with no extension. You must append an output extension — e.g. . A bare / (no extension) is not a valid delivery path and is rejected. Use the source metadata.format from the upload response, or any supported output format to convert on delivery.
2. Omit the operations segment for the original image. The canonical (untransformed) URL is just https:// — do not emit an empty segment (//).
3. Chain operations with /. Each operation is its own path segment; they apply left to right.

Supported output extensions: jpg, jpeg, png, webp, avif, gif, tiff.

Operation grammar — long vs short

Each operation can be written in two forms:

The long underscore form is accepted for every operation and is the safest choice — especially for multi-parameter operations. The short dash form is a convenient shorthand for common cases; a few operations that take several dimensions (for example smartcrop and thumbnail) currently accept only the long form, so when in doubt use the underscore syntax. The official SDK always emits a server-valid form for you.

Worked examples

# Original, converted to WebP on delivery
https://<subdomain>.viucraft.com/<image_id>.webp

# Resize, sharpen, and set quality (chained)
https://<subdomain>.viucraft.com/resize-1200-800/sharp-1.2/q-85/<image_id>.webp

# Same chain, long form
https://<subdomain>.viucraft.com/resize_width_1200_height_800/sharpen_sigma_1.2/quality_value_85/<image_id>.webp

# Grayscale only
https://<subdomain>.viucraft.com/grayscale/<image_id>.png

# Thumbnail with smart cropping (long form recommended)
https://<subdomain>.viucraft.com/thumbnail_width_300_height_200_crop_entropy/<image_id>.jpg

# Free-tier equivalent of the first example
https://viucraft.com/free/acc_<customer_id>/<image_id>.webp

The full operation catalog

Roughly 35 operations exist — resize, crop, thumbnail, smartcrop, rotate, flip, grayscale, blur, sharpen, quality, tint, colorize, vignette, watermark, and more — each with its own parameters, ranges, and aliases.

1. Machine-readable, plan-aware catalog: GET /api/v1/whoami (the capabilities.operations array) or GET /api/capabilities.
2. Per-operation reference with parameters and examples: the Image Processing section of these docs and /llms/operations.txt.
3. Full request/response contract: the OpenAPI spec.

Building URLs with the SDK

import { ViucraftClient } from "viucraft";
const client = new ViucraftClient({ apiKey, subdomain });

const url = client.image(image_id)
  .resize(800, 600)
  .setFormat("webp")   // handles the mandatory extension for you
  .toURL();
// -> https://<subdomain>.viucraft.com/resize_width_800_height_600/<image_id>.webp

The builder is pure (no network) and always produces a single-slash, correctly-extensioned URL.