{ "components": { "responses": { "Error400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/plain": { "schema": { "description": "The client-safe message.", "type": "string" } } }, "description": "Bad Request: invalid_url." }, "Error403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/plain": { "schema": { "description": "The client-safe message.", "type": "string" } } }, "description": "Forbidden: unauthorized, forbidden." }, "Error404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/plain": { "schema": { "description": "The client-safe message.", "type": "string" } } }, "description": "Not Found: expired, not_found." }, "Error406": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/plain": { "schema": { "description": "The client-safe message.", "type": "string" } } }, "description": "Not Acceptable: not_acceptable." }, "Error414": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/plain": { "schema": { "description": "The client-safe message.", "type": "string" } } }, "description": "Request URI Too Long: the URL is longer than the server accepts." }, "Error422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/plain": { "schema": { "description": "The client-safe message.", "type": "string" } } }, "description": "Unprocessable Entity: source_too_large, limit_exceeded, unsupported, corrupt, hash_mismatch." }, "Error429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/plain": { "schema": { "description": "The client-safe message.", "type": "string" } } }, "description": "Too Many Requests: overloaded. Retry-After is set when the limiter rejected the request." }, "Error500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/plain": { "schema": { "description": "The client-safe message.", "type": "string" } } }, "description": "Internal Server Error: unknown, internal." }, "Error501": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/plain": { "schema": { "description": "The client-safe message.", "type": "string" } } }, "description": "Not Implemented: a request kind this build does not implement yet (for example /info without an inspector)." }, "Error502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/plain": { "schema": { "description": "The client-safe message.", "type": "string" } } }, "description": "Bad Gateway: upstream_error." }, "Error503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/plain": { "schema": { "description": "The client-safe message.", "type": "string" } } }, "description": "Service Unavailable: unavailable. Retry-After is set when the limiter rejected the request." }, "Error504": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/plain": { "schema": { "description": "The client-safe message.", "type": "string" } } }, "description": "Gateway Timeout: upstream_timeout, timeout." } }, "schemas": { "ErrorBody": { "additionalProperties": false, "properties": { "kind": { "description": "Error kind (errs.Kind), one per row of the status table. See the status table in the ErrorResponse description.", "enum": [ "unknown", "invalid_url", "unauthorized", "forbidden", "expired", "not_found", "source_too_large", "limit_exceeded", "unsupported", "corrupt", "hash_mismatch", "not_acceptable", "upstream_error", "upstream_timeout", "overloaded", "unavailable", "timeout", "canceled", "internal" ], "type": "string" }, "message": { "description": "Client-safe message; internal error text is never sent.", "type": "string" }, "request_id": { "description": "Request ID, also in the logs.", "type": "string" } }, "required": [ "kind", "message" ], "type": "object" }, "ErrorResponse": { "additionalProperties": false, "description": "JSON error body, sent when Accept lists application/json (text/plain otherwise). Status per kind (docs/ARCHITECTURE.md §12; XI_COMPAT_IMGPROXY_STATUS=true answers 400 and forbidden 403 with 404, like imgproxy):\n\n| kind | status | message |\n|---|---|---|\n| unknown | 500 | internal server error |\n| invalid_url | 400 | invalid url |\n| unauthorized | 403 | invalid signature |\n| forbidden | 403 | forbidden |\n| expired | 404 | url expired |\n| not_found | 404 | source image not found |\n| source_too_large | 422 | source image too large |\n| limit_exceeded | 422 | image exceeds processing limits |\n| unsupported | 422 | unsupported image format |\n| corrupt | 422 | image cannot be decoded |\n| hash_mismatch | 422 | source hash mismatch |\n| not_acceptable | 406 | no acceptable image format |\n| upstream_error | 502 | upstream error |\n| upstream_timeout | 504 | upstream timeout |\n| overloaded | 429 | too many requests |\n| unavailable | 503 | service unavailable |\n| timeout | 504 | processing timeout |\n| canceled | 499 | request canceled |\n| internal | 500 | internal server error |\n\n499 (canceled) is logged, never written.", "properties": { "error": { "$ref": "#/components/schemas/ErrorBody" } }, "required": [ "error" ], "type": "object" }, "ImgproxyInfoOptions": { "additionalProperties": false, "description": "imgproxy /info options (docs/URL-DIALECTS.md §3.3), encoded like ImgproxyProcessingOptions. Info options have their own namespace: s, f, a, c, p and ph mean something else in processing URLs.", "properties": { "alpha": { "description": "Report whether the source has alpha. URL: `alpha`, `a`; arguments alpha:check_transparency; default false:false.", "examples": [ [ true ] ], "maxItems": 2, "minItems": 1, "prefixItems": [ { "description": "report the alpha channel", "title": "alpha", "type": [ "boolean", "null" ] }, { "description": "check for transparent pixels (not implemented)", "title": "check_transparency", "type": [ "boolean", "null" ] } ], "type": "array", "x-xi-aliases": [ "a" ], "x-xi-default": "false:false", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "alpha:check_transparency" }, "average": { "description": "Report the average colour. URL: `average`, `avg`; arguments enabled:ignore_transparent; default false:true.", "examples": [ [ true, true ] ], "maxItems": 2, "minItems": 1, "prefixItems": [ { "description": "report the average colour", "title": "enabled", "type": [ "boolean", "null" ] }, { "description": "ignore transparent pixels (default true)", "title": "ignore_transparent", "type": [ "boolean", "null" ] } ], "type": "array", "x-xi-aliases": [ "avg" ], "x-xi-default": "false:true", "x-xi-milestone": "M2", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "enabled:ignore_transparent" }, "bands": { "description": "Report the number of bands. URL: `bands`, `b`; arguments bool; default false.", "examples": [ [ true ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "Report the number of bands.", "title": "bands", "type": [ "boolean", "null" ] } ], "type": "array", "x-xi-aliases": [ "b" ], "x-xi-default": "false", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "bool" }, "blurhash": { "description": "Report a BlurHash. URL: `blurhash`, `bh`; arguments x:y (1..9 each, 0:0 off); default 0:0.", "examples": [ [ 4, 3 ] ], "maxItems": 2, "minItems": 2, "prefixItems": [ { "description": "1..9; 0:0 = off", "maximum": 9, "minimum": 0, "title": "x_components", "type": "integer" }, { "description": "1..9; 0:0 = off", "maximum": 9, "minimum": 0, "title": "y_components", "type": "integer" } ], "type": "array", "x-xi-aliases": [ "bh" ], "x-xi-default": "0:0", "x-xi-milestone": "M2", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "x:y (1..9 each, 0:0 off)" }, "bypass_cache": { "description": "Skip the result cache (XI_CACHE_ALLOW_BYPASS). URL: `bypass_cache`, `bc`; arguments bool; default false.", "examples": [ [ true ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "skip the result cache", "title": "bypass", "type": [ "boolean", "null" ] } ], "type": "array", "x-xi-aliases": [ "bc" ], "x-xi-default": "false", "x-xi-milestone": "M2 (WP-52)", "x-xi-pro": true, "x-xi-scope": "request", "x-xi-syntax": "bool" }, "cache_tags": { "description": "Tags for the Cache-Tag response header. URL: `cache_tags`, `ct`; arguments tags… (visible ASCII, no commas; replaces earlier tags); default —.", "examples": [ [ "product", "hero" ] ], "items": { "description": "visible ASCII without commas; a single empty tag clears", "pattern": "^[!-+\\--~]*$", "title": "tag", "type": [ "string", "null" ] }, "minItems": 1, "type": "array", "x-xi-aliases": [ "ct" ], "x-xi-default": "—", "x-xi-milestone": "M2 (WP-34b, WP-64 end-to-end test)", "x-xi-pro": true, "x-xi-scope": "request", "x-xi-syntax": "tags… (visible ASCII, no commas; replaces earlier tags)" }, "cachebuster": { "description": "Changes the URL, the cache key and the ETag. URL: `cachebuster`, `cb`; arguments string; default —.", "examples": [ [ "v2" ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "any string", "title": "value", "type": [ "string", "null" ] } ], "type": "array", "x-xi-aliases": [ "cb" ], "x-xi-default": "—", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "string" }, "calc_hashsums": { "description": "Report source digests. URL: `calc_hashsums`, `chs`; arguments md5, sha1, sha256, sha512…; default —.", "examples": [ [ "md5", "sha256" ] ], "items": { "description": "hash algorithm; a single empty argument clears", "enum": [ "md5", "sha1", "sha256", "sha512", null ], "title": "type", "type": [ "string", "null" ] }, "minItems": 1, "type": "array", "x-xi-aliases": [ "chs" ], "x-xi-default": "—", "x-xi-milestone": "M2", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "md5, sha1, sha256, sha512…" }, "classify": { "description": "Classify the image with the ImageNet classifier of the full image and report the top_k classes (ignored on slim). URL: `classify`, `cl`; arguments top_k:class_names…; default 0.", "examples": [ [ 3 ] ], "items": { "description": "a classifier class name (ImageNet-1k by default: tabby_cat, golden_retriever, pizza, ...; case-insensitive, _ for a space)", "pattern": "^.+$", "title": "class_name", "type": "string" }, "minItems": 1, "prefixItems": [ { "description": "number of classes; 0 = off", "maximum": 64, "minimum": 0, "title": "top_k", "type": "integer" } ], "type": "array", "x-xi-aliases": [ "cl" ], "x-xi-default": "0", "x-xi-milestone": "M4 (WP-110)", "x-xi-pro": true, "x-xi-scope": "request", "x-xi-syntax": "top_k:class_names…" }, "colorspace": { "description": "Report the libvips interpretation. URL: `colorspace`, `cs`; arguments bool; default false.", "examples": [ [ true ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "Report the libvips interpretation.", "title": "colorspace", "type": [ "boolean", "null" ] } ], "type": "array", "x-xi-aliases": [ "cs" ], "x-xi-default": "false", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "bool" }, "crop": { "anyOf": [ { "maxItems": 5, "minItems": 1, "prefixItems": [ { "description": "0 = full size, \u003c 1 relative, \u003e= 1 pixels", "maximum": 2147483646, "minimum": 0, "title": "width", "type": "number" }, { "description": "0 = full size, \u003c 1 relative, \u003e= 1 pixels", "maximum": 2147483646, "minimum": 0, "title": "height", "type": "number" }, { "description": "compass gravity", "enum": [ "ce", "no", "so", "ea", "we", "noea", "nowe", "soea", "sowe", null ], "title": "type", "type": [ "string", "null" ] }, { "description": "offset in pixels (relative when \u003c 1)", "title": "x_offset", "type": [ "number", "null" ] }, { "description": "offset in pixels (relative when \u003c 1)", "title": "y_offset", "type": [ "number", "null" ] } ], "type": "array" }, { "maxItems": 3, "minItems": 1, "prefixItems": [ { "description": "0 = full size, \u003c 1 relative, \u003e= 1 pixels", "maximum": 2147483646, "minimum": 0, "title": "width", "type": "number" }, { "description": "0 = full size, \u003c 1 relative, \u003e= 1 pixels", "maximum": 2147483646, "minimum": 0, "title": "height", "type": "number" }, { "enum": [ "sm" ], "title": "type", "type": "string" } ], "type": "array" }, { "maxItems": 5, "minItems": 5, "prefixItems": [ { "description": "0 = full size, \u003c 1 relative, \u003e= 1 pixels", "maximum": 2147483646, "minimum": 0, "title": "width", "type": "number" }, { "description": "0 = full size, \u003c 1 relative, \u003e= 1 pixels", "maximum": 2147483646, "minimum": 0, "title": "height", "type": "number" }, { "enum": [ "fp" ], "title": "type", "type": "string" }, { "description": "focus point x (0..1)", "maximum": 1, "minimum": 0, "title": "x", "type": "number" }, { "description": "focus point y (0..1)", "maximum": 1, "minimum": 0, "title": "y", "type": "number" } ], "type": "array" }, { "items": { "description": "face, a COCO object class (person, car, dog, traffic_light, ...) or supercategory (vehicle, animal, ...)", "pattern": "^.+$", "title": "class", "type": "string" }, "minItems": 1, "prefixItems": [ { "description": "0 = full size, \u003c 1 relative, \u003e= 1 pixels", "maximum": 2147483646, "minimum": 0, "title": "width", "type": "number" }, { "description": "0 = full size, \u003c 1 relative, \u003e= 1 pixels", "maximum": 2147483646, "minimum": 0, "title": "height", "type": "number" }, { "enum": [ "obj" ], "title": "type", "type": "string" } ], "type": "array" }, { "items": { "anyOf": [ { "description": "face, a COCO object class (person, car, dog, traffic_light, ...) or supercategory (vehicle, animal, ...)", "pattern": "^.+$", "title": "class", "type": "string" }, { "description": "class weight", "minimum": 0, "title": "weight", "type": "number" } ] }, "minItems": 5, "prefixItems": [ { "description": "0 = full size, \u003c 1 relative, \u003e= 1 pixels", "maximum": 2147483646, "minimum": 0, "title": "width", "type": "number" }, { "description": "0 = full size, \u003c 1 relative, \u003e= 1 pixels", "maximum": 2147483646, "minimum": 0, "title": "height", "type": "number" }, { "enum": [ "objw" ], "title": "type", "type": "string" } ], "type": "array" } ], "description": "Report the crop area. URL: `crop`, `c`; arguments w:h:gravity (as processing `crop`); default —.", "examples": [ [ 300, 200, "sm" ] ], "type": "array", "x-xi-aliases": [ "c" ], "x-xi-default": "—", "x-xi-milestone": "M2", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "w:h:gravity (as processing `crop`)" }, "detect_objects": { "description": "Report detected faces and objects. URL: `detect_objects`, `do`; arguments bool; default false.", "examples": [ [ true ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "Report detected faces and objects.", "title": "detect_objects", "type": [ "boolean", "null" ] } ], "type": "array", "x-xi-aliases": [ "do" ], "x-xi-default": "false", "x-xi-milestone": "M3 (WP-73)", "x-xi-pro": true, "x-xi-scope": "request", "x-xi-syntax": "bool" }, "dimensions": { "description": "Report width, height and orientation. URL: `dimensions`, `d`; arguments bool; default true.", "examples": [ [ true ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "Report width, height and orientation.", "title": "dimensions", "type": [ "boolean", "null" ] } ], "type": "array", "x-xi-aliases": [ "d" ], "x-xi-default": "true", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "bool" }, "dominant_colors": { "description": "Report dominant colours. URL: `dominant_colors`, `dc`; arguments enabled:build_missed; default false:false.", "examples": [ [ true, false ] ], "maxItems": 2, "minItems": 1, "prefixItems": [ { "description": "report dominant colours", "title": "enabled", "type": [ "boolean", "null" ] }, { "description": "derive missing colours", "title": "build_missed", "type": [ "boolean", "null" ] } ], "type": "array", "x-xi-aliases": [ "dc" ], "x-xi-default": "false:false", "x-xi-milestone": "M2", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "enabled:build_missed" }, "exif": { "description": "Report EXIF tags. URL: `exif`; arguments enabled:canonical_names; default true:false.", "examples": [ [ true, false ] ], "maxItems": 2, "minItems": 1, "prefixItems": [ { "description": "report EXIF", "title": "enabled", "type": [ "boolean", "null" ] }, { "description": "canonical tag names (not implemented)", "title": "canonical_names", "type": [ "boolean", "null" ] } ], "type": "array", "x-xi-aliases": [], "x-xi-default": "true:false", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "enabled:canonical_names" }, "expires": { "description": "URL expiry (404 afterwards). URL: `expires`, `exp`; arguments unix ts; default —.", "examples": [ [ 4102444800 ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "unix seconds; ≤ 0 never expires", "title": "timestamp", "type": "integer" } ], "type": "array", "x-xi-aliases": [ "exp" ], "x-xi-default": "—", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "unix ts" }, "format": { "description": "Report the format and media type. URL: `format`, `f`; arguments bool; default true.", "examples": [ [ true ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "Report the format and media type.", "title": "format", "type": [ "boolean", "null" ] } ], "type": "array", "x-xi-aliases": [ "f" ], "x-xi-default": "true", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "bool" }, "hashsum": { "description": "Check the source bytes against a digest. URL: `hashsum`, `hs`; arguments none, or md5/sha1/sha256/sha512:hex; default none.", "examples": [ [ "sha256", "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" ] ], "maxItems": 2, "minItems": 1, "prefixItems": [ { "description": "hash algorithm; none or empty removes the check", "enum": [ "none", "md5", "sha1", "sha256", "sha512", null ], "title": "type", "type": [ "string", "null" ] }, { "description": "hex digest", "pattern": "^[0-9a-fA-F]*$", "title": "hashsum", "type": [ "string", "null" ] } ], "type": "array", "x-xi-aliases": [ "hs" ], "x-xi-default": "none", "x-xi-milestone": "M2 (WP-64)", "x-xi-pro": true, "x-xi-scope": "request", "x-xi-syntax": "none, or md5/sha1/sha256/sha512:hex" }, "iptc": { "description": "Report IPTC datasets (and Photoshop resolution). URL: `iptc`; arguments bool; default true.", "examples": [ [ true ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "Report IPTC datasets (and Photoshop resolution).", "title": "iptc", "type": [ "boolean", "null" ] } ], "type": "array", "x-xi-aliases": [], "x-xi-default": "true", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "bool" }, "max_src_file_size": { "description": "Lower (or raise) the source size limit. URL: `max_src_file_size`, `msfs`; arguments int; default config. Needs XI_SECURITY_ALLOW_SECURITY_OPTIONS (403 otherwise).", "examples": [ [ 10 ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "bytes", "maximum": 2147483647, "minimum": 0, "title": "bytes", "type": "integer" } ], "type": "array", "x-xi-aliases": [ "msfs" ], "x-xi-default": "config", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-security": true, "x-xi-syntax": "int" }, "max_src_resolution": { "description": "Lower (or raise) the source resolution limit. URL: `max_src_resolution`, `msr`; arguments int; default config. Needs XI_SECURITY_ALLOW_SECURITY_OPTIONS (403 otherwise).", "examples": [ [ 10 ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "megapixels", "minimum": 0, "title": "megapixels", "type": "number" } ], "type": "array", "x-xi-aliases": [ "msr" ], "x-xi-default": "config", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-security": true, "x-xi-syntax": "int" }, "objects_position": { "anyOf": [ { "maxItems": 3, "minItems": 1, "prefixItems": [ { "description": "compass position", "enum": [ "ce", "no", "so", "ea", "we", "noea", "nowe", "soea", "sowe" ], "title": "type", "type": "string" }, { "description": "offset in pixels", "maximum": 65536, "minimum": -65536, "title": "x_offset", "type": [ "number", "null" ] }, { "description": "offset in pixels", "maximum": 65536, "minimum": -65536, "title": "y_offset", "type": [ "number", "null" ] } ], "type": "array" }, { "maxItems": 3, "minItems": 1, "prefixItems": [ { "enum": [ "fp" ], "title": "type", "type": "string" }, { "description": "x (0..1)", "maximum": 1, "minimum": 0, "title": "x", "type": [ "number", "null" ] }, { "description": "y (0..1)", "maximum": 1, "minimum": 0, "title": "y", "type": [ "number", "null" ] } ], "type": "array" }, { "maxItems": 1, "minItems": 1, "prefixItems": [ { "enum": [ "prop" ], "title": "type", "type": "string" } ], "type": "array" } ], "description": "Objects position for the reported crop. URL: `objects_position`, `obj_pos`, `op`; arguments as processing; default ce:0:0.", "examples": [ [ "prop" ] ], "type": "array", "x-xi-aliases": [ "obj_pos", "op" ], "x-xi-default": "ce:0:0", "x-xi-milestone": "M3 (WP-73)", "x-xi-pro": true, "x-xi-scope": "request", "x-xi-syntax": "as processing" }, "page": { "description": "First page of a multi-page source. URL: `page`, `pg`; arguments int; default 0.", "examples": [ [ 1 ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "first page, from 0", "maximum": 2147483647, "minimum": 0, "title": "page", "type": "integer" } ], "type": "array", "x-xi-aliases": [ "pg" ], "x-xi-default": "0", "x-xi-milestone": "M2 (WP-50, WP-62)", "x-xi-pro": true, "x-xi-scope": "pipeline", "x-xi-syntax": "int" }, "pages_number": { "description": "Report the number of pages or frames. URL: `pages_number`, `pn`; arguments bool; default false.", "examples": [ [ true ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "Report the number of pages or frames.", "title": "pages_number", "type": [ "boolean", "null" ] } ], "type": "array", "x-xi-aliases": [ "pn" ], "x-xi-default": "false", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "bool" }, "palette": { "description": "Report a palette. URL: `palette`, `p`; arguments 0 or 2..256; default 0.", "examples": [ [ 16 ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "0 = off, else 2..256", "maximum": 256, "minimum": 0, "title": "colors", "type": "integer" } ], "type": "array", "x-xi-aliases": [ "p" ], "x-xi-default": "0", "x-xi-milestone": "M2", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "0 or 2..256" }, "pdf_password": { "description": "Open a password-protected PDF; signed URLs only. URL: `pdf_password`, `pdp`; arguments encrypted password (base64url); default none.", "examples": [ [ "MDEyMzQ1Njc4OWFiY2RlZlsN0ZQuFO2sitmy5C87M2o" ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "the document password encrypted like an enc/ source (AES-CBC with the XI_ENCRYPTION_KEYS key, base64url); empty removes it", "pattern": "^[A-Za-z0-9_-]*=*$", "title": "token", "type": [ "string", "null" ] } ], "type": "array", "x-xi-aliases": [ "pdp" ], "x-xi-default": "none", "x-xi-milestone": "M4 (WP-115)", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "encrypted password (base64url)" }, "perceptual_hash": { "description": "Report a perceptual hash. URL: `perceptual_hash`, `phash`, `ph`; arguments bool; default false.", "examples": [ [ true ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "Report a perceptual hash.", "title": "perceptual_hash", "type": [ "boolean", "null" ] } ], "type": "array", "x-xi-aliases": [ "phash", "ph" ], "x-xi-default": "false", "x-xi-milestone": "M2", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "bool" }, "preset": { "description": "Expand presets in place. URL: `preset`, `pr`; arguments names…; default —.", "examples": [ [ "thumbnail" ] ], "items": { "description": "preset name", "pattern": "^.+$", "title": "name", "type": "string" }, "minItems": 1, "type": "array", "x-xi-aliases": [ "pr" ], "x-xi-default": "—", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "pipeline", "x-xi-syntax": "names…" }, "sample_format": { "description": "Report the libvips band format. URL: `sample_format`, `sf`; arguments bool; default false.", "examples": [ [ true ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "Report the libvips band format.", "title": "sample_format", "type": [ "boolean", "null" ] } ], "type": "array", "x-xi-aliases": [ "sf" ], "x-xi-default": "false", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "bool" }, "size": { "description": "Report the source size in bytes. URL: `size`, `s`; arguments bool; default true.", "examples": [ [ true ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "Report the source size in bytes.", "title": "size", "type": [ "boolean", "null" ] } ], "type": "array", "x-xi-aliases": [ "s" ], "x-xi-default": "true", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "bool" }, "thumbhash": { "description": "Report a ThumbHash. URL: `thumbhash`, `thumb_hash`, `th`; arguments bool; default false.", "examples": [ [ true ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "Report a ThumbHash.", "title": "thumbhash", "type": [ "boolean", "null" ] } ], "type": "array", "x-xi-aliases": [ "thumb_hash", "th" ], "x-xi-default": "false", "x-xi-milestone": "M2", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "bool" }, "video_meta": { "description": "Report video metadata. URL: `video_meta`, `vm`; arguments bool; default true.", "examples": [ [ true ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "Report video metadata.", "title": "video_meta", "type": [ "boolean", "null" ] } ], "type": "array", "x-xi-aliases": [ "vm" ], "x-xi-default": "true", "x-xi-milestone": "M3 (WP-74)", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "bool" }, "video_thumbnail_keyframes": { "description": "Seek to keyframes only. URL: `video_thumbnail_keyframes`, `vtk`; arguments bool; default config.", "examples": [ [ true ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "use keyframes only", "title": "keyframes", "type": [ "boolean", "null" ] } ], "type": "array", "x-xi-aliases": [ "vtk" ], "x-xi-default": "config", "x-xi-milestone": "M3 (WP-74)", "x-xi-pro": true, "x-xi-scope": "pipeline", "x-xi-syntax": "bool" }, "video_thumbnail_second": { "description": "Video frame to use as the image (negative: from the end; unset: the configured second or the best frame). URL: `video_thumbnail_second`, `vts`; arguments float; default config.", "examples": [ [ 5 ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "timestamp in seconds; negative counts from the end", "maximum": 2147483647, "minimum": -2147483647, "title": "second", "type": "number" } ], "type": "array", "x-xi-aliases": [ "vts" ], "x-xi-default": "config", "x-xi-milestone": "M3 (WP-74)", "x-xi-pro": true, "x-xi-scope": "pipeline", "x-xi-syntax": "float" }, "xmp": { "description": "Report XMP properties. URL: `xmp`; arguments bool; default true.", "examples": [ [ true ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "Report XMP properties.", "title": "xmp", "type": [ "boolean", "null" ] } ], "type": "array", "x-xi-aliases": [], "x-xi-default": "true", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "bool" } }, "type": "object" }, "ImgproxyProcessingOptions": { "additionalProperties": false, "description": "imgproxy processing options (docs/URL-DIALECTS.md §3.2), one property per canonical option name. Each value is the option's positional arguments: /name:a:b/ is {\"name\": [a, b]}. Booleans are JSON booleans (1/0 in URLs); null is an empty argument (keeps the previous or default value). Chained pipelines (\"/-/\") are one object each; request-scoped options apply to the whole request.", "properties": { "adjust": { "description": "Brightness, contrast and saturation in one option. URL: `adjust`, `a`; arguments brightness:contrast:saturation; default —.", "examples": [ [ 10, 1.1, 0.9 ] ], "maxItems": 3, "minItems": 1, "prefixItems": [ { "description": "brightness", "maximum": 255, "minimum": -255, "title": "brightness", "type": [ "number", "null" ] }, { "description": "contrast factor", "maximum": 1000, "minimum": 0, "title": "contrast", "type": [ "number", "null" ] }, { "description": "saturation factor", "maximum": 1000, "minimum": 0, "title": "saturation", "type": [ "number", "null" ] } ], "type": "array", "x-xi-aliases": [ "a" ], "x-xi-default": "—", "x-xi-milestone": "M2", "x-xi-pro": true, "x-xi-scope": "pipeline", "x-xi-syntax": "brightness:contrast:saturation" }, "auto_rotate": { "description": "Apply the EXIF orientation. URL: `auto_rotate`, `ar`; arguments bool; default config (true).", "examples": [ [ true ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "apply the EXIF orientation", "title": "auto_rotate", "type": [ "boolean", "null" ] } ], "type": "array", "x-xi-aliases": [ "ar" ], "x-xi-default": "config (true)", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "pipeline", "x-xi-syntax": "bool" }, "autoquality": { "description": "Search the lowest quality that meets a target. URL: `autoquality`, `aq`; arguments method:target:min:max:allowed_error; method `none`/`size`/`dssim`/`ml` (`ml` parsed, run as no auto-quality and reported skipped); `size` target in bytes (≤ 2³⁰); default config.", "examples": [ [ "dssim", 0.02, 70, 85, 0.001 ] ], "maxItems": 5, "minItems": 1, "prefixItems": [ { "description": "search method", "enum": [ "dssim", "ml", "none", "size", null ], "title": "method", "type": [ "string", "null" ] }, { "description": "target (bytes for size, DSSIM otherwise)", "maximum": 1073741824, "minimum": 0, "title": "target", "type": [ "number", "null" ] }, { "description": "lowest quality", "maximum": 100, "minimum": 0, "title": "min_quality", "type": [ "integer", "null" ] }, { "description": "highest quality", "maximum": 100, "minimum": 0, "title": "max_quality", "type": [ "integer", "null" ] }, { "description": "allowed error (0..1)", "maximum": 1, "minimum": 0, "title": "allowed_error", "type": [ "number", "null" ] } ], "type": "array", "x-xi-aliases": [ "aq" ], "x-xi-default": "config", "x-xi-milestone": "M2 (WP-56, FORMATS §6.4)", "x-xi-pro": true, "x-xi-scope": "request", "x-xi-syntax": "method:target:min:max:allowed_error; method `none`/`size`/`dssim`/`ml` (`ml` parsed, run as no auto-quality and reported skipped); `size` target in bytes (≤ 2³⁰)" }, "avif_options": { "description": "AVIF encoder settings. URL: `avif_options`, `avifo`; arguments subsample; default config.", "examples": [ [ "off" ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "auto, on (4:2:0) or off (4:4:4)", "enum": [ "auto", "off", "on" ], "title": "subsample", "type": "string" } ], "type": "array", "x-xi-aliases": [ "avifo" ], "x-xi-default": "config", "x-xi-milestone": "M2 (WP-64)", "x-xi-pro": true, "x-xi-scope": "request", "x-xi-syntax": "subsample" }, "background": { "anyOf": [ { "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "hex colour; empty removes the background", "pattern": "^([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$", "title": "color", "type": [ "string", "null" ] } ], "type": "array" }, { "maxItems": 3, "minItems": 3, "prefixItems": [ { "description": "red", "maximum": 255, "minimum": 0, "title": "r", "type": "integer" }, { "description": "green", "maximum": 255, "minimum": 0, "title": "g", "type": "integer" }, { "description": "blue", "maximum": 255, "minimum": 0, "title": "b", "type": "integer" } ], "type": "array" } ], "description": "Background colour for transparency, extend and padding. URL: `background`, `bg`; arguments r:g:b or hex; default none.", "examples": [ [ "ffffff" ] ], "type": "array", "x-xi-aliases": [ "bg" ], "x-xi-default": "none", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "pipeline", "x-xi-syntax": "r:g:b or hex" }, "background_alpha": { "description": "Background opacity. URL: `background_alpha`, `bga`; arguments 0..1; default 1.", "examples": [ [ 0.5 ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "background opacity (0..1)", "maximum": 1, "minimum": 0, "title": "alpha", "type": "number" } ], "type": "array", "x-xi-aliases": [ "bga" ], "x-xi-default": "1", "x-xi-milestone": "M2", "x-xi-pro": true, "x-xi-scope": "pipeline", "x-xi-syntax": "0..1" }, "blur": { "description": "Gaussian blur. URL: `blur`, `bl`; arguments sigma; default off.", "examples": [ [ 2 ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "Gaussian sigma", "minimum": 0, "title": "sigma", "type": "number" } ], "type": "array", "x-xi-aliases": [ "bl" ], "x-xi-default": "off", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "pipeline", "x-xi-syntax": "sigma" }, "blur_areas": { "description": "Blur rectangular areas (relative coordinates). URL: `blur_areas`, `ba`; arguments sigma:l:t:w:h… (relative to the oriented source; follow rotate/flip/crops); default off.", "examples": [ [ 10, 0, 0, 0.5, 0.5 ] ], "items": { "anyOf": [ { "description": "left (0..1)", "maximum": 1, "minimum": 0, "title": "left", "type": "number" }, { "description": "top (0..1)", "maximum": 1, "minimum": 0, "title": "top", "type": "number" }, { "description": "width (0..1)", "maximum": 1, "minimum": 0, "title": "width", "type": "number" }, { "description": "height (0..1)", "maximum": 1, "minimum": 0, "title": "height", "type": "number" } ] }, "minItems": 1, "prefixItems": [ { "description": "blur sigma; 0 = off", "maximum": 1000, "minimum": 0, "title": "sigma", "type": "number" } ], "type": "array", "x-xi-aliases": [ "ba" ], "x-xi-default": "off", "x-xi-milestone": "M2 (WP-61)", "x-xi-pro": true, "x-xi-scope": "pipeline", "x-xi-syntax": "sigma:l:t:w:h… (relative to the oriented source; follow rotate/flip/crops)" }, "blur_detections": { "description": "Blur detected objects. URL: `blur_detections`, `bd`; arguments sigma:classes…; default off.", "examples": [ [ 10, "face" ] ], "items": { "description": "face, a COCO object class (person, car, dog, traffic_light, ...) or supercategory (vehicle, animal, ...)", "pattern": "^.+$", "title": "class", "type": "string" }, "minItems": 1, "prefixItems": [ { "description": "blur sigma; 0 = off", "maximum": 1000, "minimum": 0, "title": "sigma", "type": "number" } ], "type": "array", "x-xi-aliases": [ "bd" ], "x-xi-default": "off", "x-xi-milestone": "M3 (WP-73)", "x-xi-pro": true, "x-xi-scope": "pipeline", "x-xi-syntax": "sigma:classes…" }, "brightness": { "description": "Brightness. URL: `brightness`, `br`; arguments −255..255; default 0.", "examples": [ [ 10 ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "brightness", "maximum": 255, "minimum": -255, "title": "brightness", "type": "number" } ], "type": "array", "x-xi-aliases": [ "br" ], "x-xi-default": "0", "x-xi-milestone": "M2", "x-xi-pro": true, "x-xi-scope": "pipeline", "x-xi-syntax": "−255..255" }, "bypass_cache": { "description": "Skip the result cache (XI_CACHE_ALLOW_BYPASS). URL: `bypass_cache`, `bc`; arguments bool; default false.", "examples": [ [ true ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "skip the result cache", "title": "bypass", "type": [ "boolean", "null" ] } ], "type": "array", "x-xi-aliases": [ "bc" ], "x-xi-default": "false", "x-xi-milestone": "M2 (WP-52)", "x-xi-pro": true, "x-xi-scope": "request", "x-xi-syntax": "bool" }, "cache_tags": { "description": "Tags for the Cache-Tag response header. URL: `cache_tags`, `ct`; arguments tags… (visible ASCII, no commas; replaces earlier tags); default —.", "examples": [ [ "product", "hero" ] ], "items": { "description": "visible ASCII without commas; a single empty tag clears", "pattern": "^[!-+\\--~]*$", "title": "tag", "type": [ "string", "null" ] }, "minItems": 1, "type": "array", "x-xi-aliases": [ "ct" ], "x-xi-default": "—", "x-xi-milestone": "M2 (WP-34b, WP-64 end-to-end test)", "x-xi-pro": true, "x-xi-scope": "request", "x-xi-syntax": "tags… (visible ASCII, no commas; replaces earlier tags)" }, "cachebuster": { "description": "Changes the URL, the cache key and the ETag. URL: `cachebuster`, `cb`; arguments string; default —.", "examples": [ [ "v2" ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "any string", "title": "value", "type": [ "string", "null" ] } ], "type": "array", "x-xi-aliases": [ "cb" ], "x-xi-default": "—", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "string" }, "color_profile": { "description": "Target colour profile. URL: `color_profile`, `cp`, `icc`; arguments srgb, cmyk, file; default —.", "examples": [ [ "srgb" ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "srgb, cmyk or a profile file name (no path)", "title": "profile", "type": [ "string", "null" ] } ], "type": "array", "x-xi-aliases": [ "cp", "icc" ], "x-xi-default": "—", "x-xi-milestone": "M2", "x-xi-pro": true, "x-xi-scope": "request", "x-xi-syntax": "srgb, cmyk, file" }, "colorize": { "description": "Colour overlay. URL: `colorize`, `col`; arguments opacity:color:keep_alpha; default off.", "examples": [ [ 0.5, "ff0000", true ] ], "maxItems": 3, "minItems": 1, "prefixItems": [ { "description": "overlay opacity (0..1)", "maximum": 1, "minimum": 0, "title": "opacity", "type": [ "number", "null" ] }, { "description": "overlay colour", "pattern": "^([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$", "title": "color", "type": [ "string", "null" ] }, { "description": "keep the alpha channel", "title": "keep_alpha", "type": [ "boolean", "null" ] } ], "type": "array", "x-xi-aliases": [ "col" ], "x-xi-default": "off", "x-xi-milestone": "M2", "x-xi-pro": true, "x-xi-scope": "pipeline", "x-xi-syntax": "opacity:color:keep_alpha" }, "contrast": { "description": "Contrast factor. URL: `contrast`, `co`; arguments float; default 1.", "examples": [ [ 1.2 ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "contrast factor", "maximum": 1000, "minimum": 0, "title": "contrast", "type": "number" } ], "type": "array", "x-xi-aliases": [ "co" ], "x-xi-default": "1", "x-xi-milestone": "M2", "x-xi-pro": true, "x-xi-scope": "pipeline", "x-xi-syntax": "float" }, "crop": { "anyOf": [ { "maxItems": 5, "minItems": 1, "prefixItems": [ { "description": "0 = full size, \u003c 1 relative, \u003e= 1 pixels", "maximum": 2147483646, "minimum": 0, "title": "width", "type": "number" }, { "description": "0 = full size, \u003c 1 relative, \u003e= 1 pixels", "maximum": 2147483646, "minimum": 0, "title": "height", "type": "number" }, { "description": "compass gravity", "enum": [ "ce", "no", "so", "ea", "we", "noea", "nowe", "soea", "sowe", null ], "title": "type", "type": [ "string", "null" ] }, { "description": "offset in pixels (relative when \u003c 1)", "title": "x_offset", "type": [ "number", "null" ] }, { "description": "offset in pixels (relative when \u003c 1)", "title": "y_offset", "type": [ "number", "null" ] } ], "type": "array" }, { "maxItems": 3, "minItems": 1, "prefixItems": [ { "description": "0 = full size, \u003c 1 relative, \u003e= 1 pixels", "maximum": 2147483646, "minimum": 0, "title": "width", "type": "number" }, { "description": "0 = full size, \u003c 1 relative, \u003e= 1 pixels", "maximum": 2147483646, "minimum": 0, "title": "height", "type": "number" }, { "enum": [ "sm" ], "title": "type", "type": "string" } ], "type": "array" }, { "maxItems": 5, "minItems": 5, "prefixItems": [ { "description": "0 = full size, \u003c 1 relative, \u003e= 1 pixels", "maximum": 2147483646, "minimum": 0, "title": "width", "type": "number" }, { "description": "0 = full size, \u003c 1 relative, \u003e= 1 pixels", "maximum": 2147483646, "minimum": 0, "title": "height", "type": "number" }, { "enum": [ "fp" ], "title": "type", "type": "string" }, { "description": "focus point x (0..1)", "maximum": 1, "minimum": 0, "title": "x", "type": "number" }, { "description": "focus point y (0..1)", "maximum": 1, "minimum": 0, "title": "y", "type": "number" } ], "type": "array" }, { "items": { "description": "face, a COCO object class (person, car, dog, traffic_light, ...) or supercategory (vehicle, animal, ...)", "pattern": "^.+$", "title": "class", "type": "string" }, "minItems": 1, "prefixItems": [ { "description": "0 = full size, \u003c 1 relative, \u003e= 1 pixels", "maximum": 2147483646, "minimum": 0, "title": "width", "type": "number" }, { "description": "0 = full size, \u003c 1 relative, \u003e= 1 pixels", "maximum": 2147483646, "minimum": 0, "title": "height", "type": "number" }, { "enum": [ "obj" ], "title": "type", "type": "string" } ], "type": "array" }, { "items": { "anyOf": [ { "description": "face, a COCO object class (person, car, dog, traffic_light, ...) or supercategory (vehicle, animal, ...)", "pattern": "^.+$", "title": "class", "type": "string" }, { "description": "class weight", "minimum": 0, "title": "weight", "type": "number" } ] }, "minItems": 5, "prefixItems": [ { "description": "0 = full size, \u003c 1 relative, \u003e= 1 pixels", "maximum": 2147483646, "minimum": 0, "title": "width", "type": "number" }, { "description": "0 = full size, \u003c 1 relative, \u003e= 1 pixels", "maximum": 2147483646, "minimum": 0, "title": "height", "type": "number" }, { "enum": [ "objw" ], "title": "type", "type": "string" } ], "type": "array" } ], "description": "Crop before resizing. URL: `crop`, `c`; arguments w:h[:gravity] (abs ≥1, rel \u003c1); default —.", "examples": [ [ 300, 200, "nowe" ] ], "type": "array", "x-xi-aliases": [ "c" ], "x-xi-default": "—", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "pipeline", "x-xi-syntax": "w:h[:gravity] (abs ≥1, rel \u003c1)" }, "crop_aspect_ratio": { "description": "Correct the crop area (the whole image without crop) to an aspect ratio. URL: `crop_aspect_ratio`, `crop_ar`, `car`; arguments ratio:enlarge; default 0.", "examples": [ [ 1.5, true ] ], "maxItems": 2, "minItems": 1, "prefixItems": [ { "description": "width / height; 0 = off", "maximum": 1000, "minimum": 0, "title": "aspect_ratio", "type": [ "number", "null" ] }, { "description": "enlarge the crop area", "title": "enlarge", "type": [ "boolean", "null" ] } ], "type": "array", "x-xi-aliases": [ "crop_ar", "car" ], "x-xi-default": "0", "x-xi-milestone": "M2", "x-xi-pro": true, "x-xi-scope": "pipeline", "x-xi-syntax": "ratio:enlarge" }, "crop_objects": { "description": "Crop to detected objects before resizing. URL: `crop_objects`, `c_obj`; arguments scale:classes…; default off.", "examples": [ [ 1.2, "face" ] ], "items": { "description": "face, a COCO object class (person, car, dog, traffic_light, ...) or supercategory (vehicle, animal, ...)", "pattern": "^.+$", "title": "class", "type": "string" }, "minItems": 1, "prefixItems": [ { "description": "scale factor of the object box; 0 = off", "maximum": 1000, "minimum": 0, "title": "scale", "type": "number" } ], "type": "array", "x-xi-aliases": [ "c_obj" ], "x-xi-default": "off", "x-xi-milestone": "M3 (WP-72)", "x-xi-pro": true, "x-xi-scope": "pipeline", "x-xi-syntax": "scale:classes…" }, "disable_animation": { "description": "Process only the first frame. URL: `disable_animation`, `da`; arguments bool; default false.", "examples": [ [ true ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "use the first frame only", "title": "disable", "type": [ "boolean", "null" ] } ], "type": "array", "x-xi-aliases": [ "da" ], "x-xi-default": "false", "x-xi-milestone": "M1", "x-xi-pro": true, "x-xi-scope": "pipeline", "x-xi-syntax": "bool" }, "dpi": { "description": "DPI metadata of the result. URL: `dpi`; arguments int; default 0.", "examples": [ [ 300 ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "DPI; 0 = unchanged", "maximum": 10000, "minimum": 0, "title": "dpi", "type": "integer" } ], "type": "array", "x-xi-aliases": [], "x-xi-default": "0", "x-xi-milestone": "M2 (WP-64)", "x-xi-pro": true, "x-xi-scope": "request", "x-xi-syntax": "int" }, "dpr": { "description": "Device pixel ratio multiplying the size. URL: `dpr`; arguments float; default 1.", "examples": [ [ 2 ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "device pixel ratio", "exclusiveMinimum": 0, "title": "dpr", "type": "number" } ], "type": "array", "x-xi-aliases": [], "x-xi-default": "1", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "pipeline", "x-xi-syntax": "float" }, "draw_detections": { "description": "Draw boxes and labels around detected objects. URL: `draw_detections`, `dd`; arguments bool:classes…; default off.", "examples": [ [ true, "face" ] ], "items": { "description": "face, a COCO object class (person, car, dog, traffic_light, ...) or supercategory (vehicle, animal, ...)", "pattern": "^.+$", "title": "class", "type": "string" }, "minItems": 1, "prefixItems": [ { "description": "draw boxes", "title": "draw", "type": [ "boolean", "null" ] } ], "type": "array", "x-xi-aliases": [ "dd" ], "x-xi-default": "off", "x-xi-milestone": "M3 (WP-73)", "x-xi-pro": true, "x-xi-scope": "pipeline", "x-xi-syntax": "bool:classes…" }, "duotone": { "description": "Duotone effect. URL: `duotone`, `dt`; arguments intensity:c1:c2; default 0:000000:ffffff.", "examples": [ [ 1, "000000", "ffffff" ] ], "maxItems": 3, "minItems": 1, "prefixItems": [ { "description": "effect intensity (0..1)", "maximum": 1, "minimum": 0, "title": "intensity", "type": [ "number", "null" ] }, { "description": "shadow colour", "pattern": "^([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$", "title": "color1", "type": [ "string", "null" ] }, { "description": "highlight colour", "pattern": "^([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$", "title": "color2", "type": [ "string", "null" ] } ], "type": "array", "x-xi-aliases": [ "dt" ], "x-xi-default": "0:000000:ffffff", "x-xi-milestone": "M2", "x-xi-pro": true, "x-xi-scope": "pipeline", "x-xi-syntax": "intensity:c1:c2" }, "enforce_thumbnail": { "description": "Use the embedded thumbnail when present. URL: `enforce_thumbnail`, `eth`; arguments bool; default config.", "examples": [ [ true ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "use the embedded thumbnail", "title": "enforce", "type": [ "boolean", "null" ] } ], "type": "array", "x-xi-aliases": [ "eth" ], "x-xi-default": "config", "x-xi-milestone": "M2 (WP-64)", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "bool" }, "enlarge": { "description": "Allow upscaling. URL: `enlarge`, `el`; arguments bool; default false.", "examples": [ [ true ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "allow upscaling", "title": "enlarge", "type": [ "boolean", "null" ] } ], "type": "array", "x-xi-aliases": [ "el" ], "x-xi-default": "false", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "pipeline", "x-xi-syntax": "bool" }, "expires": { "description": "URL expiry (404 afterwards). URL: `expires`, `exp`; arguments unix ts; default —.", "examples": [ [ 4102444800 ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "unix seconds; ≤ 0 never expires", "title": "timestamp", "type": "integer" } ], "type": "array", "x-xi-aliases": [ "exp" ], "x-xi-default": "—", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "unix ts" }, "extend": { "description": "Extend the image to the requested size with the background. URL: `extend`, `ex`; arguments bool:gravity:x:y; default false:ce:0:0.", "examples": [ [ true, "so" ] ], "maxItems": 4, "minItems": 1, "prefixItems": [ { "description": "extend the image to the requested size", "title": "extend", "type": [ "boolean", "null" ] }, { "description": "extend gravity (compass or fp)", "enum": [ "ce", "no", "so", "ea", "we", "noea", "nowe", "soea", "sowe", "fp", null ], "title": "gravity", "type": [ "string", "null" ] }, { "description": "gravity x offset (fp: 0..1)", "title": "x_offset", "type": [ "number", "null" ] }, { "description": "gravity y offset (fp: 0..1)", "title": "y_offset", "type": [ "number", "null" ] } ], "type": "array", "x-xi-aliases": [ "ex" ], "x-xi-default": "false:ce:0:0", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "pipeline", "x-xi-syntax": "bool:gravity:x:y" }, "extend_aspect_ratio": { "description": "Extend the image to the requested aspect ratio. URL: `extend_aspect_ratio`, `extend_ar`, `exar`; arguments bool:gravity:x:y; default false.", "examples": [ [ true, "ce" ] ], "maxItems": 4, "minItems": 1, "prefixItems": [ { "description": "extend the image to the requested size", "title": "extend", "type": [ "boolean", "null" ] }, { "description": "extend gravity (compass or fp)", "enum": [ "ce", "no", "so", "ea", "we", "noea", "nowe", "soea", "sowe", "fp", null ], "title": "gravity", "type": [ "string", "null" ] }, { "description": "gravity x offset (fp: 0..1)", "title": "x_offset", "type": [ "number", "null" ] }, { "description": "gravity y offset (fp: 0..1)", "title": "y_offset", "type": [ "number", "null" ] } ], "type": "array", "x-xi-aliases": [ "extend_ar", "exar" ], "x-xi-default": "false", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "pipeline", "x-xi-syntax": "bool:gravity:x:y" }, "fallback_image_url": { "description": "Image served when the source fails (XI_FALLBACK_ALLOW_REQUEST_URL). URL: `fallback_image_url`, `fiu`; arguments base64url URL; default config.", "examples": [ [ "aHR0cHM6Ly9leGFtcGxlLmNvbS9mLnBuZw" ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "url-safe base64 of the fallback source URL; empty = configured", "pattern": "^[A-Za-z0-9_-]*=*$", "title": "url", "type": [ "string", "null" ] } ], "type": "array", "x-xi-aliases": [ "fiu" ], "x-xi-default": "config", "x-xi-milestone": "M1 (WP-34c)", "x-xi-pro": true, "x-xi-scope": "request", "x-xi-syntax": "base64url URL" }, "filename": { "description": "Content-Disposition file name. URL: `filename`, `fn`; arguments name:encoded; default source basename.", "examples": [ [ "photo" ] ], "maxItems": 2, "minItems": 1, "prefixItems": [ { "description": "file name without extension", "title": "name", "type": [ "string", "null" ] }, { "description": "name is url-safe base64", "title": "encoded", "type": [ "boolean", "null" ] } ], "type": "array", "x-xi-aliases": [ "fn" ], "x-xi-default": "source basename", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "name:encoded" }, "flip": { "description": "Mirror the image. URL: `flip`, `fl`; arguments h:v bools; default false:false.", "examples": [ [ true, false ] ], "maxItems": 2, "minItems": 1, "prefixItems": [ { "description": "flip horizontally", "title": "horizontal", "type": [ "boolean", "null" ] }, { "description": "flip vertically", "title": "vertical", "type": [ "boolean", "null" ] } ], "type": "array", "x-xi-aliases": [ "fl" ], "x-xi-default": "false:false", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "pipeline", "x-xi-syntax": "h:v bools" }, "format": { "description": "Output format. `mp4` (Pro), `webm` and `hevc` encode the (animated) result as video: VP9 WebM, MP4 with H.264 in the gpl image or AV1 in full, HEVC only in gpl. URL: `format`, `f`, `ext`; arguments extension or `best` Pro; default source/negotiated.", "examples": [ [ "webp" ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "output format; best picks the smallest (Pro)", "enum": [ "jpeg", "jpg", "png", "webp", "avif", "jxl", "heic", "gif", "tiff", "bmp", "ico", "svg", "mp4", "webm", "hevc", "h265", "best" ], "title": "format", "type": "string" } ], "type": "array", "x-xi-aliases": [ "f", "ext" ], "x-xi-default": "source/negotiated", "x-xi-milestone": "M1 (`best` M2, `mp4`/`webm`/`hevc` M3 WP-76)", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "extension or `best` Pro" }, "format_quality": { "description": "Quality per output format. URL: `format_quality`, `fq`; arguments fmt:q…; default —.", "examples": [ [ "webp", 70, "avif", 50 ] ], "items": { "anyOf": [ { "description": "output format", "enum": [ "jpeg", "jpg", "png", "webp", "avif", "jxl", "heic", "gif", "tiff", "bmp", "ico", "svg", "mp4", "webm", "hevc", "h265" ], "title": "format", "type": "string" }, { "description": "0 removes the entry", "maximum": 100, "minimum": 0, "title": "quality", "type": "integer" } ] }, "minItems": 2, "type": "array", "x-xi-aliases": [ "fq" ], "x-xi-default": "—", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "fmt:q…" }, "gain_map": { "description": "What an HDR gain map (UltraHDR, ISO 21496-1) does: auto renders HDR with preserve_hdr for AVIF, JPEG XL and JPEG outputs, hdr does so without preserve_hdr, sdr keeps the SDR base. URL: `gain_map`, `gm`; arguments auto, hdr, sdr; default auto.", "examples": [ [ "hdr" ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "auto follows preserve_hdr, hdr applies the gain map, sdr keeps the SDR base", "enum": [ "auto", "hdr", "sdr" ], "title": "mode", "type": "string" } ], "type": "array", "x-xi-aliases": [ "gm" ], "x-xi-default": "auto", "x-xi-milestone": "M4 (WP-104)", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "auto, hdr, sdr" }, "gif_options": { "deprecated": true, "description": "Removed upstream; accepted and ignored for old URLs. URL: `gif_options`, `gifo`; arguments —; default —.", "examples": [ [ "1" ] ], "items": { "description": "ignored", "title": "value", "type": [ "string", "null" ] }, "minItems": 1, "type": "array", "x-xi-aliases": [ "gifo" ], "x-xi-default": "—", "x-xi-milestone": "—", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "—" }, "gradient": { "description": "Gradient overlay. URL: `gradient`, `gr`; arguments opacity:color:direction:start:stop; direction `down`/`up`/`left`/`right` or degrees clockwise like imgproxy (0 = top to bottom like `down`, 90 = right to left like `left`); default 0:000:down:0:1.", "examples": [ [ 0.5, "000000", "down", 0.5, 1 ] ], "maxItems": 5, "minItems": 1, "prefixItems": [ { "description": "gradient opacity (0..1)", "maximum": 1, "minimum": 0, "title": "opacity", "type": [ "number", "null" ] }, { "description": "gradient colour", "pattern": "^([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$", "title": "color", "type": [ "string", "null" ] }, { "anyOf": [ { "enum": [ "down", "up", "left", "right" ], "type": "string" }, { "maximum": 360, "minimum": -360, "type": "number" }, { "type": "null" } ], "description": "down, up, left, right or degrees clockwise (0 = down, 90 = left)", "title": "direction" }, { "description": "start (0..1)", "maximum": 1, "minimum": 0, "title": "start", "type": [ "number", "null" ] }, { "description": "stop (0..1)", "maximum": 1, "minimum": 0, "title": "stop", "type": [ "number", "null" ] } ], "type": "array", "x-xi-aliases": [ "gr" ], "x-xi-default": "0:000:down:0:1", "x-xi-milestone": "M2", "x-xi-pro": true, "x-xi-scope": "pipeline", "x-xi-syntax": "opacity:color:direction:start:stop; direction `down`/`up`/`left`/`right` or degrees clockwise like imgproxy (0 = top to bottom like `down`, 90 = right to left like `left`)" }, "gravity": { "anyOf": [ { "maxItems": 3, "minItems": 1, "prefixItems": [ { "description": "compass gravity", "enum": [ "ce", "no", "so", "ea", "we", "noea", "nowe", "soea", "sowe", null ], "title": "type", "type": [ "string", "null" ] }, { "description": "offset in pixels (relative when \u003c 1)", "title": "x_offset", "type": [ "number", "null" ] }, { "description": "offset in pixels (relative when \u003c 1)", "title": "y_offset", "type": [ "number", "null" ] } ], "type": "array" }, { "maxItems": 1, "minItems": 1, "prefixItems": [ { "enum": [ "sm" ], "title": "type", "type": "string" } ], "type": "array" }, { "maxItems": 3, "minItems": 3, "prefixItems": [ { "enum": [ "fp" ], "title": "type", "type": "string" }, { "description": "focus point x (0..1)", "maximum": 1, "minimum": 0, "title": "x", "type": "number" }, { "description": "focus point y (0..1)", "maximum": 1, "minimum": 0, "title": "y", "type": "number" } ], "type": "array" }, { "items": { "description": "face, a COCO object class (person, car, dog, traffic_light, ...) or supercategory (vehicle, animal, ...)", "pattern": "^.+$", "title": "class", "type": "string" }, "minItems": 1, "prefixItems": [ { "enum": [ "obj" ], "title": "type", "type": "string" } ], "type": "array" }, { "items": { "anyOf": [ { "description": "face, a COCO object class (person, car, dog, traffic_light, ...) or supercategory (vehicle, animal, ...)", "pattern": "^.+$", "title": "class", "type": "string" }, { "description": "class weight", "minimum": 0, "title": "weight", "type": "number" } ] }, "minItems": 3, "prefixItems": [ { "enum": [ "objw" ], "title": "type", "type": "string" } ], "type": "array" } ], "description": "Where to crop from when the aspect ratio changes; `sm` crops on faces when there are some (XI_DETECT_SMART_FACES). URL: `gravity`, `g`; arguments no,so,ea,we,noea,nowe,soea,sowe,ce[:x:y]; `sm`; `fp:x:y`; `obj:classes…` Pro; `objw:class:weight…` Pro; default ce:0:0.", "examples": [ [ "fp", 0.5, 0.3 ] ], "type": "array", "x-xi-aliases": [ "g" ], "x-xi-default": "ce:0:0", "x-xi-milestone": "M1 (sm, fp), M3 (obj, objw: WP-72)", "x-xi-pro": false, "x-xi-scope": "pipeline", "x-xi-syntax": "no,so,ea,we,noea,nowe,soea,sowe,ce[:x:y]; `sm`; `fp:x:y`; `obj:classes…` Pro; `objw:class:weight…` Pro" }, "hashsum": { "description": "Check the source bytes against a digest. URL: `hashsum`, `hs`; arguments none, or md5/sha1/sha256/sha512:hex; default none.", "examples": [ [ "sha256", "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" ] ], "maxItems": 2, "minItems": 1, "prefixItems": [ { "description": "hash algorithm; none or empty removes the check", "enum": [ "none", "md5", "sha1", "sha256", "sha512", null ], "title": "type", "type": [ "string", "null" ] }, { "description": "hex digest", "pattern": "^[0-9a-fA-F]*$", "title": "hashsum", "type": [ "string", "null" ] } ], "type": "array", "x-xi-aliases": [ "hs" ], "x-xi-default": "none", "x-xi-milestone": "M2 (WP-64)", "x-xi-pro": true, "x-xi-scope": "request", "x-xi-syntax": "none, or md5/sha1/sha256/sha512:hex" }, "height": { "description": "Target height; 0 keeps the aspect ratio. URL: `height`, `h`; arguments int; default 0.", "examples": [ [ 200 ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "height in pixels", "maximum": 2147483647, "minimum": 0, "title": "height", "type": "integer" } ], "type": "array", "x-xi-aliases": [ "h" ], "x-xi-default": "0", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "pipeline", "x-xi-syntax": "int" }, "jpeg_options": { "description": "JPEG encoder settings. URL: `jpeg_options`, `jpgo`; arguments progressive:no_subsample:trellis_quant:overshoot_deringing:optimize_scans:quant_table; default config.", "examples": [ [ true, false, true, true, true, 3 ] ], "maxItems": 6, "minItems": 1, "prefixItems": [ { "description": "progressive JPEG", "title": "progressive", "type": [ "boolean", "null" ] }, { "description": "disable chroma subsampling", "title": "no_subsample", "type": [ "boolean", "null" ] }, { "description": "trellis quantisation", "title": "trellis_quant", "type": [ "boolean", "null" ] }, { "description": "overshoot deringing", "title": "overshoot_deringing", "type": [ "boolean", "null" ] }, { "description": "optimise progressive scans", "title": "optimize_scans", "type": [ "boolean", "null" ] }, { "description": "quantisation table", "maximum": 8, "minimum": 0, "title": "quant_table", "type": [ "integer", "null" ] } ], "type": "array", "x-xi-aliases": [ "jpgo" ], "x-xi-default": "config", "x-xi-milestone": "M2 (WP-64)", "x-xi-pro": true, "x-xi-scope": "request", "x-xi-syntax": "progressive:no_subsample:trellis_quant:overshoot_deringing:optimize_scans:quant_table" }, "keep_copyright": { "description": "Keep copyright when stripping metadata. URL: `keep_copyright`, `kcr`; arguments bool; default config (true).", "examples": [ [ true ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "keep copyright metadata", "title": "keep", "type": [ "boolean", "null" ] } ], "type": "array", "x-xi-aliases": [ "kcr" ], "x-xi-default": "config (true)", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "bool" }, "max_animation_frame_resolution": { "description": "Lower (or raise) the frame resolution limit. URL: `max_animation_frame_resolution`, `mafr`; arguments int; default config. Needs XI_SECURITY_ALLOW_SECURITY_OPTIONS (403 otherwise).", "examples": [ [ 10 ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "megapixels", "minimum": 0, "title": "megapixels", "type": "number" } ], "type": "array", "x-xi-aliases": [ "mafr" ], "x-xi-default": "config", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-security": true, "x-xi-syntax": "int" }, "max_animation_frames": { "description": "Lower (or raise) the animation frame limit. URL: `max_animation_frames`, `maf`; arguments int; default config. Needs XI_SECURITY_ALLOW_SECURITY_OPTIONS (403 otherwise).", "examples": [ [ 10 ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "frames", "maximum": 2147483647, "minimum": 1, "title": "frames", "type": "integer" } ], "type": "array", "x-xi-aliases": [ "maf" ], "x-xi-default": "config", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-security": true, "x-xi-syntax": "int" }, "max_bytes": { "description": "Lower the quality until the result fits. URL: `max_bytes`, `mb`; arguments int; default 0.", "examples": [ [ 100000 ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "0 = no limit", "maximum": 2147483647, "minimum": 0, "title": "bytes", "type": "integer" } ], "type": "array", "x-xi-aliases": [ "mb" ], "x-xi-default": "0", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "int" }, "max_result_dimension": { "description": "Lower (or raise) the result dimension limit. URL: `max_result_dimension`, `mrd`; arguments int; default config. Needs XI_SECURITY_ALLOW_SECURITY_OPTIONS (403 otherwise).", "examples": [ [ 10 ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "pixels", "maximum": 2147483647, "minimum": 0, "title": "pixels", "type": "integer" } ], "type": "array", "x-xi-aliases": [ "mrd" ], "x-xi-default": "config", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-security": true, "x-xi-syntax": "int" }, "max_src_file_size": { "description": "Lower (or raise) the source size limit. URL: `max_src_file_size`, `msfs`; arguments int; default config. Needs XI_SECURITY_ALLOW_SECURITY_OPTIONS (403 otherwise).", "examples": [ [ 10 ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "bytes", "maximum": 2147483647, "minimum": 0, "title": "bytes", "type": "integer" } ], "type": "array", "x-xi-aliases": [ "msfs" ], "x-xi-default": "config", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-security": true, "x-xi-syntax": "int" }, "max_src_resolution": { "description": "Lower (or raise) the source resolution limit. URL: `max_src_resolution`, `msr`; arguments int; default config. Needs XI_SECURITY_ALLOW_SECURITY_OPTIONS (403 otherwise).", "examples": [ [ 10 ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "megapixels", "minimum": 0, "title": "megapixels", "type": "number" } ], "type": "array", "x-xi-aliases": [ "msr" ], "x-xi-default": "config", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-security": true, "x-xi-syntax": "int" }, "min-height": { "description": "Minimum result height. URL: `min-height`, `mh`; arguments int; default 0.", "examples": [ [ 100 ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "min_height in pixels", "maximum": 2147483647, "minimum": 0, "title": "min_height", "type": "integer" } ], "type": "array", "x-xi-aliases": [ "mh" ], "x-xi-default": "0", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "pipeline", "x-xi-syntax": "int" }, "min-width": { "description": "Minimum result width. URL: `min-width`, `mw`; arguments int; default 0.", "examples": [ [ 100 ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "min_width in pixels", "maximum": 2147483647, "minimum": 0, "title": "min_width", "type": "integer" } ], "type": "array", "x-xi-aliases": [ "mw" ], "x-xi-default": "0", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "pipeline", "x-xi-syntax": "int" }, "monochrome": { "description": "Monochrome effect. URL: `monochrome`, `mc`; arguments intensity:color; default 0:b3b3b3.", "examples": [ [ 1, "b3b3b3" ] ], "maxItems": 2, "minItems": 1, "prefixItems": [ { "description": "effect intensity (0..1)", "maximum": 1, "minimum": 0, "title": "intensity", "type": [ "number", "null" ] }, { "description": "tint colour", "pattern": "^([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$", "title": "color", "type": [ "string", "null" ] } ], "type": "array", "x-xi-aliases": [ "mc" ], "x-xi-default": "0:b3b3b3", "x-xi-milestone": "M2", "x-xi-pro": true, "x-xi-scope": "pipeline", "x-xi-syntax": "intensity:color" }, "objects_position": { "anyOf": [ { "maxItems": 3, "minItems": 1, "prefixItems": [ { "description": "compass position", "enum": [ "ce", "no", "so", "ea", "we", "noea", "nowe", "soea", "sowe" ], "title": "type", "type": "string" }, { "description": "offset in pixels", "maximum": 65536, "minimum": -65536, "title": "x_offset", "type": [ "number", "null" ] }, { "description": "offset in pixels", "maximum": 65536, "minimum": -65536, "title": "y_offset", "type": [ "number", "null" ] } ], "type": "array" }, { "maxItems": 3, "minItems": 1, "prefixItems": [ { "enum": [ "fp" ], "title": "type", "type": "string" }, { "description": "x (0..1)", "maximum": 1, "minimum": 0, "title": "x", "type": [ "number", "null" ] }, { "description": "y (0..1)", "maximum": 1, "minimum": 0, "title": "y", "type": [ "number", "null" ] } ], "type": "array" }, { "maxItems": 1, "minItems": 1, "prefixItems": [ { "enum": [ "prop" ], "title": "type", "type": "string" } ], "type": "array" } ], "description": "Position of the detected objects' box in the crop (face, obj and objw gravity). URL: `objects_position`, `obj_pos`, `op`; arguments type:x:y, `fp:x:y`, `prop`; default ce.", "examples": [ [ "prop" ] ], "type": "array", "x-xi-aliases": [ "obj_pos", "op" ], "x-xi-default": "ce", "x-xi-milestone": "M3 (WP-72)", "x-xi-pro": true, "x-xi-scope": "pipeline", "x-xi-syntax": "type:x:y, `fp:x:y`, `prop`" }, "padding": { "description": "Padding with the background colour, CSS shorthand. URL: `padding`, `pd`; arguments t:r:b:l (CSS shorthand); default —.", "examples": [ [ 10, 20 ] ], "maxItems": 4, "minItems": 1, "prefixItems": [ { "description": "top padding", "maximum": 2147483647, "minimum": 0, "title": "top", "type": [ "integer", "null" ] }, { "description": "right padding (default: top)", "maximum": 2147483647, "minimum": 0, "title": "right", "type": [ "integer", "null" ] }, { "description": "bottom padding (default: top)", "maximum": 2147483647, "minimum": 0, "title": "bottom", "type": [ "integer", "null" ] }, { "description": "left padding (default: right)", "maximum": 2147483647, "minimum": 0, "title": "left", "type": [ "integer", "null" ] } ], "type": "array", "x-xi-aliases": [ "pd" ], "x-xi-default": "—", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "pipeline", "x-xi-syntax": "t:r:b:l (CSS shorthand)" }, "page": { "description": "First page of a multi-page source. URL: `page`, `pg`; arguments int; default 0.", "examples": [ [ 1 ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "first page, from 0", "maximum": 2147483647, "minimum": 0, "title": "page", "type": "integer" } ], "type": "array", "x-xi-aliases": [ "pg" ], "x-xi-default": "0", "x-xi-milestone": "M2 (WP-50, WP-62)", "x-xi-pro": true, "x-xi-scope": "pipeline", "x-xi-syntax": "int" }, "pages": { "description": "Number of pages stacked into the result. URL: `pages`, `pgs`; arguments int; default 1.", "examples": [ [ 2 ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "number of pages, ≥ 1, or -1 for all", "maximum": 2147483647, "minimum": -1, "title": "pages", "type": "integer" } ], "type": "array", "x-xi-aliases": [ "pgs" ], "x-xi-default": "1", "x-xi-milestone": "M2 (WP-50, WP-62)", "x-xi-pro": true, "x-xi-scope": "pipeline", "x-xi-syntax": "int" }, "pdf_password": { "description": "Open a password-protected PDF; signed URLs only. URL: `pdf_password`, `pdp`; arguments encrypted password (base64url); default none.", "examples": [ [ "MDEyMzQ1Njc4OWFiY2RlZlsN0ZQuFO2sitmy5C87M2o" ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "the document password encrypted like an enc/ source (AES-CBC with the XI_ENCRYPTION_KEYS key, base64url); empty removes it", "pattern": "^[A-Za-z0-9_-]*=*$", "title": "token", "type": [ "string", "null" ] } ], "type": "array", "x-xi-aliases": [ "pdp" ], "x-xi-default": "none", "x-xi-milestone": "M4 (WP-115)", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "encrypted password (base64url)" }, "pixelate": { "description": "Pixelate. URL: `pixelate`, `pix`; arguments size; default off.", "examples": [ [ 8 ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "pixel block size", "maximum": 2147483647, "minimum": 0, "title": "size", "type": "integer" } ], "type": "array", "x-xi-aliases": [ "pix" ], "x-xi-default": "off", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "pipeline", "x-xi-syntax": "size" }, "png_options": { "description": "PNG encoder settings. URL: `png_options`, `pngo`; arguments interlaced:quantize:quantization_colors; default config.", "examples": [ [ false, true, 128 ] ], "maxItems": 3, "minItems": 1, "prefixItems": [ { "description": "Adam7 interlacing", "title": "interlaced", "type": [ "boolean", "null" ] }, { "description": "palette quantisation", "title": "quantize", "type": [ "boolean", "null" ] }, { "description": "palette size, 2..256; 0 = default", "maximum": 256, "minimum": 0, "title": "quantization_colors", "type": [ "integer", "null" ] } ], "type": "array", "x-xi-aliases": [ "pngo" ], "x-xi-default": "config", "x-xi-milestone": "M2 (WP-64)", "x-xi-pro": true, "x-xi-scope": "request", "x-xi-syntax": "interlaced:quantize:quantization_colors" }, "preserve_hdr": { "description": "Keep HDR data (gain maps, high bit depth). URL: `preserve_hdr`, `ph`; arguments bool; default config (false).", "examples": [ [ true ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "keep HDR data", "title": "preserve", "type": [ "boolean", "null" ] } ], "type": "array", "x-xi-aliases": [ "ph" ], "x-xi-default": "config (false)", "x-xi-milestone": "M2", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "bool" }, "preset": { "description": "Expand presets in place. URL: `preset`, `pr`; arguments names…; default —.", "examples": [ [ "thumbnail" ] ], "items": { "description": "preset name", "pattern": "^.+$", "title": "name", "type": "string" }, "minItems": 1, "type": "array", "x-xi-aliases": [ "pr" ], "x-xi-default": "—", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "pipeline", "x-xi-syntax": "names…" }, "progressive_blur": { "description": "Blur that increases along a direction. URL: `progressive_blur`, `pbl`; arguments sigma:direction:start:stop; direction as `gradient`; default off (…:down:0:1).", "examples": [ [ 10, "down", 0.5, 1 ] ], "maxItems": 4, "minItems": 1, "prefixItems": [ { "description": "blur sigma; 0 = off", "maximum": 1000, "minimum": 0, "title": "sigma", "type": [ "number", "null" ] }, { "anyOf": [ { "enum": [ "down", "up", "left", "right" ], "type": "string" }, { "maximum": 360, "minimum": -360, "type": "number" }, { "type": "null" } ], "description": "down, up, left, right or degrees clockwise (0 = down, 90 = left)", "title": "direction" }, { "description": "start of the ramp (0..1)", "maximum": 1, "minimum": 0, "title": "start", "type": [ "number", "null" ] }, { "description": "end of the ramp (0..1)", "maximum": 1, "minimum": 0, "title": "stop", "type": [ "number", "null" ] } ], "type": "array", "x-xi-aliases": [ "pbl" ], "x-xi-default": "off (…:down:0:1)", "x-xi-milestone": "M2 (WP-61)", "x-xi-pro": true, "x-xi-scope": "pipeline", "x-xi-syntax": "sigma:direction:start:stop; direction as `gradient`" }, "quality": { "description": "Encoder quality. URL: `quality`, `q`; arguments 0..100; default 0 (config).", "examples": [ [ 80 ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "0 = format default", "maximum": 100, "minimum": 0, "title": "quality", "type": "integer" } ], "type": "array", "x-xi-aliases": [ "q" ], "x-xi-default": "0 (config)", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "0..100" }, "raw": { "description": "Stream the source without processing. URL: `raw`; arguments bool; default false.", "examples": [ [ true ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "stream the source unprocessed", "title": "raw", "type": [ "boolean", "null" ] } ], "type": "array", "x-xi-aliases": [], "x-xi-default": "false", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "bool" }, "resize": { "description": "Resizing type, size, enlarge and extend in one option. URL: `resize`, `rs`; arguments type:w:h:enlarge:extend(:gravity…); default —.", "examples": [ [ "fill", 300, 400, false ] ], "maxItems": 8, "minItems": 1, "prefixItems": [ { "description": "resizing type", "enum": [ "auto", "fill", "fill-down", "fit", "force", null ], "title": "type", "type": [ "string", "null" ] }, { "description": "width in pixels; 0 keeps the aspect ratio", "maximum": 2147483647, "minimum": 0, "title": "width", "type": [ "integer", "null" ] }, { "description": "height in pixels; 0 keeps the aspect ratio", "maximum": 2147483647, "minimum": 0, "title": "height", "type": [ "integer", "null" ] }, { "description": "allow upscaling", "title": "enlarge", "type": [ "boolean", "null" ] }, { "description": "extend the image to the requested size", "title": "extend", "type": [ "boolean", "null" ] }, { "description": "extend gravity (compass or fp)", "enum": [ "ce", "no", "so", "ea", "we", "noea", "nowe", "soea", "sowe", "fp", null ], "title": "gravity", "type": [ "string", "null" ] }, { "description": "gravity x offset (fp: 0..1)", "title": "x_offset", "type": [ "number", "null" ] }, { "description": "gravity y offset (fp: 0..1)", "title": "y_offset", "type": [ "number", "null" ] } ], "type": "array", "x-xi-aliases": [ "rs" ], "x-xi-default": "—", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "pipeline", "x-xi-syntax": "type:w:h:enlarge:extend(:gravity…)" }, "resizing_algorithm": { "description": "Resampling kernel. URL: `resizing_algorithm`, `ra`; arguments nearest, linear, cubic, lanczos2, lanczos3; default lanczos3.", "examples": [ [ "lanczos3" ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "resampling kernel", "enum": [ "cubic", "lanczos2", "lanczos3", "linear", "nearest" ], "title": "algorithm", "type": "string" } ], "type": "array", "x-xi-aliases": [ "ra" ], "x-xi-default": "lanczos3", "x-xi-milestone": "M1", "x-xi-pro": true, "x-xi-scope": "pipeline", "x-xi-syntax": "nearest, linear, cubic, lanczos2, lanczos3" }, "resizing_type": { "description": "How the image fits the requested size. URL: `resizing_type`, `rt`; arguments fit, fill, fill-down, force, auto; default fit.", "examples": [ [ "fill" ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "resizing type", "enum": [ "auto", "fill", "fill-down", "fit", "force" ], "title": "type", "type": "string" } ], "type": "array", "x-xi-aliases": [ "rt" ], "x-xi-default": "fit", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "pipeline", "x-xi-syntax": "fit, fill, fill-down, force, auto" }, "return_attachment": { "description": "Download instead of inline display. URL: `return_attachment`, `att`; arguments bool; default config.", "examples": [ [ true ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "Content-Disposition: attachment", "title": "attachment", "type": [ "boolean", "null" ] } ], "type": "array", "x-xi-aliases": [ "att" ], "x-xi-default": "config", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "bool" }, "rotate": { "description": "Rotate after the EXIF orientation. URL: `rotate`, `rot`; arguments multiple of 90; default 0.", "examples": [ [ 90 ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "degrees, a multiple of 90", "maximum": 2147483647, "minimum": -2147483648, "multipleOf": 90, "title": "angle", "type": "integer" } ], "type": "array", "x-xi-aliases": [ "rot" ], "x-xi-default": "0", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "pipeline", "x-xi-syntax": "multiple of 90" }, "saturation": { "description": "Saturation factor. URL: `saturation`, `sa`; arguments float; default 1.", "examples": [ [ 0.8 ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "saturation factor", "maximum": 1000, "minimum": 0, "title": "saturation", "type": "number" } ], "type": "array", "x-xi-aliases": [ "sa" ], "x-xi-default": "1", "x-xi-milestone": "M2", "x-xi-pro": true, "x-xi-scope": "pipeline", "x-xi-syntax": "float" }, "sharpen": { "description": "Sharpen. URL: `sharpen`, `sh`; arguments sigma; default off.", "examples": [ [ 0.5 ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "sharpening sigma", "minimum": 0, "title": "sigma", "type": "number" } ], "type": "array", "x-xi-aliases": [ "sh" ], "x-xi-default": "off", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "pipeline", "x-xi-syntax": "sigma" }, "size": { "description": "Size, enlarge and extend in one option. URL: `size`, `s`; arguments w:h:enlarge:extend; default —.", "examples": [ [ 300, 400, true ] ], "maxItems": 7, "minItems": 1, "prefixItems": [ { "description": "width in pixels; 0 keeps the aspect ratio", "maximum": 2147483647, "minimum": 0, "title": "width", "type": [ "integer", "null" ] }, { "description": "height in pixels; 0 keeps the aspect ratio", "maximum": 2147483647, "minimum": 0, "title": "height", "type": [ "integer", "null" ] }, { "description": "allow upscaling", "title": "enlarge", "type": [ "boolean", "null" ] }, { "description": "extend the image to the requested size", "title": "extend", "type": [ "boolean", "null" ] }, { "description": "extend gravity (compass or fp)", "enum": [ "ce", "no", "so", "ea", "we", "noea", "nowe", "soea", "sowe", "fp", null ], "title": "gravity", "type": [ "string", "null" ] }, { "description": "gravity x offset (fp: 0..1)", "title": "x_offset", "type": [ "number", "null" ] }, { "description": "gravity y offset (fp: 0..1)", "title": "y_offset", "type": [ "number", "null" ] } ], "type": "array", "x-xi-aliases": [ "s" ], "x-xi-default": "—", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "pipeline", "x-xi-syntax": "w:h:enlarge:extend" }, "skip_processing": { "description": "Serve sources of these formats unprocessed. URL: `skip_processing`, `skp`, `sp`; arguments ext…; default —.", "examples": [ [ "svg", "gif" ] ], "items": { "description": "source format served as is", "enum": [ "jpeg", "jpg", "png", "webp", "avif", "jxl", "heic", "gif", "tiff", "bmp", "ico", "svg", "mp4", "webm", "hevc", "h265" ], "title": "format", "type": "string" }, "minItems": 1, "type": "array", "x-xi-aliases": [ "skp", "sp" ], "x-xi-default": "—", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "ext…" }, "strip_color_profile": { "description": "Convert to sRGB and drop the ICC profile. URL: `strip_color_profile`, `scp`; arguments bool; default config (true).", "examples": [ [ true ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "convert to sRGB and drop the profile", "title": "strip", "type": [ "boolean", "null" ] } ], "type": "array", "x-xi-aliases": [ "scp" ], "x-xi-default": "config (true)", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "bool" }, "strip_metadata": { "description": "Strip metadata from the result. URL: `strip_metadata`, `sm`; arguments bool; default config (true).", "examples": [ [ true ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "strip metadata", "title": "strip", "type": [ "boolean", "null" ] } ], "type": "array", "x-xi-aliases": [ "sm" ], "x-xi-default": "config (true)", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "bool" }, "style": { "description": "CSS applied to SVG sources. URL: `style`, `stl`, `st`; arguments base64url CSS; default —.", "examples": [ [ "c3Zn" ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "url-safe base64 of CSS", "pattern": "^[A-Za-z0-9_-]*=*$", "title": "css", "type": "string" } ], "type": "array", "x-xi-aliases": [ "stl", "st" ], "x-xi-default": "—", "x-xi-milestone": "M2 (WP-64)", "x-xi-pro": true, "x-xi-scope": "pipeline", "x-xi-syntax": "base64url CSS" }, "trim": { "description": "Remove borders of a uniform colour. URL: `trim`, `t`; arguments threshold:color:equal_hor:equal_ver; default —.", "examples": [ [ 10, "ffffff", true, true ] ], "maxItems": 4, "minItems": 1, "prefixItems": [ { "description": "colour distance threshold; empty disables trimming", "title": "threshold", "type": [ "number", "null" ] }, { "description": "colour to trim (default: top-left pixel)", "pattern": "^([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$", "title": "color", "type": [ "string", "null" ] }, { "description": "trim left and right equally", "title": "equal_hor", "type": [ "boolean", "null" ] }, { "description": "trim top and bottom equally", "title": "equal_ver", "type": [ "boolean", "null" ] } ], "type": "array", "x-xi-aliases": [ "t" ], "x-xi-default": "—", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "pipeline", "x-xi-syntax": "threshold:color:equal_hor:equal_ver" }, "unsharp_masking": { "description": "Unsharp masking after downscaling. URL: `unsharp_masking`, `ush`; arguments mode:weight:divider (3×3 kernel, ARCHITECTURE §8.1 step 8); default auto:1:24 when given; off otherwise.", "examples": [ [ "always", 1, 24 ] ], "maxItems": 3, "minItems": 1, "prefixItems": [ { "description": "when to sharpen", "enum": [ "always", "auto", "none", null ], "title": "mode", "type": [ "string", "null" ] }, { "description": "sharpening weight", "maximum": 1000, "minimum": 0, "title": "weight", "type": [ "number", "null" ] }, { "description": "divider", "maximum": 1000, "minimum": 0, "title": "divider", "type": [ "number", "null" ] } ], "type": "array", "x-xi-aliases": [ "ush" ], "x-xi-default": "auto:1:24 when given; off otherwise", "x-xi-milestone": "M2 (WP-61)", "x-xi-pro": true, "x-xi-scope": "pipeline", "x-xi-syntax": "mode:weight:divider (3×3 kernel, ARCHITECTURE §8.1 step 8)" }, "video_thumbnail_animation": { "description": "Animation of video frames. URL: `video_thumbnail_animation`, `vta`; arguments step:delay(ms):frames:fw:fh:extend:trim:fill:fx:fy; step as `vtt`; default off.", "examples": [ [ 1, 100, 10, 320, 180 ] ], "maxItems": 10, "minItems": 1, "prefixItems": [ { "description": "seconds between frames; 0 = off, \u003c 0 = from the duration", "maximum": 2147483647, "minimum": -2147483647, "title": "step", "type": "number" }, { "description": "frame delay in milliseconds", "maximum": 2147483647, "minimum": 0, "title": "delay", "type": [ "number", "null" ] }, { "description": "number of frames", "maximum": 65536, "minimum": 0, "title": "frames", "type": [ "integer", "null" ] }, { "description": "frame width", "maximum": 65536, "minimum": 0, "title": "frame_width", "type": [ "integer", "null" ] }, { "description": "frame height", "maximum": 65536, "minimum": 0, "title": "frame_height", "type": [ "integer", "null" ] }, { "description": "extend frames to the requested size", "title": "extend_frame", "type": [ "boolean", "null" ] }, { "description": "trim the black borders", "title": "trim", "type": [ "boolean", "null" ] }, { "description": "fill the frame (crop)", "title": "fill", "type": [ "boolean", "null" ] }, { "description": "focus x (0..1)", "maximum": 1, "minimum": 0, "title": "focus_x", "type": [ "number", "null" ] }, { "description": "focus y (0..1)", "maximum": 1, "minimum": 0, "title": "focus_y", "type": [ "number", "null" ] } ], "type": "array", "x-xi-aliases": [ "vta" ], "x-xi-default": "off", "x-xi-milestone": "M3 (WP-75)", "x-xi-pro": true, "x-xi-scope": "pipeline", "x-xi-syntax": "step:delay(ms):frames:fw:fh:extend:trim:fill:fx:fy; step as `vtt`" }, "video_thumbnail_keyframes": { "description": "Seek to keyframes only. URL: `video_thumbnail_keyframes`, `vtk`; arguments bool; default config.", "examples": [ [ true ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "use keyframes only", "title": "keyframes", "type": [ "boolean", "null" ] } ], "type": "array", "x-xi-aliases": [ "vtk" ], "x-xi-default": "config", "x-xi-milestone": "M3 (WP-74)", "x-xi-pro": true, "x-xi-scope": "pipeline", "x-xi-syntax": "bool" }, "video_thumbnail_second": { "description": "Video frame to use as the image (negative: from the end; unset: the configured second or the best frame). URL: `video_thumbnail_second`, `vts`; arguments float; default config.", "examples": [ [ 5 ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "timestamp in seconds; negative counts from the end", "maximum": 2147483647, "minimum": -2147483647, "title": "second", "type": "number" } ], "type": "array", "x-xi-aliases": [ "vts" ], "x-xi-default": "config", "x-xi-milestone": "M3 (WP-74)", "x-xi-pro": true, "x-xi-scope": "pipeline", "x-xi-syntax": "float" }, "video_thumbnail_tile": { "description": "Sprite sheet of video frames. URL: `video_thumbnail_tile`, `vtt`; arguments step:cols:rows:tw:th:extend:trim:fill:fx:fy; step 0 = off, \u003c 0 = from duration (stored as 0); default off.", "examples": [ [ 1, 4, 4, 160, 90 ] ], "maxItems": 10, "minItems": 1, "prefixItems": [ { "description": "seconds between frames; 0 = off, \u003c 0 = from the duration", "maximum": 2147483647, "minimum": -2147483647, "title": "step", "type": "number" }, { "description": "columns", "maximum": 65536, "minimum": 0, "title": "columns", "type": [ "integer", "null" ] }, { "description": "rows", "maximum": 65536, "minimum": 0, "title": "rows", "type": [ "integer", "null" ] }, { "description": "tile width", "maximum": 65536, "minimum": 0, "title": "tile_width", "type": [ "integer", "null" ] }, { "description": "tile height", "maximum": 65536, "minimum": 0, "title": "tile_height", "type": [ "integer", "null" ] }, { "description": "extend tiles to the requested size", "title": "extend_tile", "type": [ "boolean", "null" ] }, { "description": "trim the black borders", "title": "trim", "type": [ "boolean", "null" ] }, { "description": "fill the tile (crop)", "title": "fill", "type": [ "boolean", "null" ] }, { "description": "focus x (0..1)", "maximum": 1, "minimum": 0, "title": "focus_x", "type": [ "number", "null" ] }, { "description": "focus y (0..1)", "maximum": 1, "minimum": 0, "title": "focus_y", "type": [ "number", "null" ] } ], "type": "array", "x-xi-aliases": [ "vtt" ], "x-xi-default": "off", "x-xi-milestone": "M3 (WP-75)", "x-xi-pro": true, "x-xi-scope": "pipeline", "x-xi-syntax": "step:cols:rows:tw:th:extend:trim:fill:fx:fy; step 0 = off, \u003c 0 = from duration (stored as 0)" }, "watermark": { "description": "Draw the watermark. URL: `watermark`, `wm`; arguments opacity:pos:x:y:scale; pos incl. `re` (tile), `ch` (chessboard, Pro); default off.", "examples": [ [ 0.5, "soea", 10, 10, 0.2 ] ], "maxItems": 5, "minItems": 1, "prefixItems": [ { "description": "opacity (0..1); 0 disables", "maximum": 1, "minimum": 0, "title": "opacity", "type": "number" }, { "description": "compass position, re (tile) or ch (chessboard)", "enum": [ "ce", "no", "so", "ea", "we", "noea", "nowe", "soea", "sowe", "re", "ch", null ], "title": "position", "type": [ "string", "null" ] }, { "description": "x offset", "title": "x_offset", "type": [ "number", "null" ] }, { "description": "y offset", "title": "y_offset", "type": [ "number", "null" ] }, { "description": "scale relative to the image", "exclusiveMinimum": 0, "title": "scale", "type": [ "number", "null" ] } ], "type": "array", "x-xi-aliases": [ "wm" ], "x-xi-default": "off", "x-xi-milestone": "M1 (`re` M1, `ch` M3 WP-77)", "x-xi-pro": false, "x-xi-scope": "pipeline", "x-xi-syntax": "opacity:pos:x:y:scale; pos incl. `re` (tile), `ch` (chessboard, Pro)" }, "watermark_rotate": { "description": "Watermark rotation, clockwise. URL: `watermark_rotate`, `wm_rot`, `wmr`; arguments degrees; default 0.", "examples": [ [ 45 ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "degrees", "title": "angle", "type": "number" } ], "type": "array", "x-xi-aliases": [ "wm_rot", "wmr" ], "x-xi-default": "0", "x-xi-milestone": "M3 (WP-77)", "x-xi-pro": true, "x-xi-scope": "pipeline", "x-xi-syntax": "degrees" }, "watermark_shadow": { "description": "Watermark shadow: its alpha blurred with sigma, in black. URL: `watermark_shadow`, `wmsh`; arguments sigma; default off.", "examples": [ [ 2 ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "shadow blur sigma", "maximum": 1000, "minimum": 0, "title": "sigma", "type": "number" } ], "type": "array", "x-xi-aliases": [ "wmsh" ], "x-xi-default": "off", "x-xi-milestone": "M3 (WP-77)", "x-xi-pro": true, "x-xi-scope": "pipeline", "x-xi-syntax": "sigma" }, "watermark_size": { "description": "Watermark size in pixels (fit, enlarging; used when the wm scale is 0). URL: `watermark_size`, `wms`; arguments w:h; default 0:0.", "examples": [ [ 100, 0 ] ], "maxItems": 2, "minItems": 1, "prefixItems": [ { "description": "width; 0 = auto", "maximum": 65536, "minimum": 0, "title": "width", "type": [ "integer", "null" ] }, { "description": "height; 0 = auto", "maximum": 65536, "minimum": 0, "title": "height", "type": [ "integer", "null" ] } ], "type": "array", "x-xi-aliases": [ "wms" ], "x-xi-default": "0:0", "x-xi-milestone": "M3 (WP-77)", "x-xi-pro": true, "x-xi-scope": "pipeline", "x-xi-syntax": "w:h" }, "watermark_text": { "description": "Text watermark (replaces watermark_url); markup is sanitised to a whitelist, font `sans 16` by default. URL: `watermark_text`, `wmt`; arguments base64url Pango markup; default —.", "examples": [ [ "SGVsbG8" ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "url-safe base64 of Pango markup", "pattern": "^[A-Za-z0-9_-]*=*$", "title": "text", "type": [ "string", "null" ] } ], "type": "array", "x-xi-aliases": [ "wmt" ], "x-xi-default": "—", "x-xi-milestone": "M3 (WP-78)", "x-xi-pro": true, "x-xi-scope": "pipeline", "x-xi-syntax": "base64url Pango markup" }, "watermark_url": { "description": "Watermark image source, fetched like a source (allowlist, SSRF policy, byte limit, origin cache). URL: `watermark_url`, `wmu`; arguments base64url URL; default config image.", "examples": [ [ "aHR0cHM6Ly9leGFtcGxlLmNvbS93LnBuZw" ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "url-safe base64 of the watermark source URL; empty = configured image", "pattern": "^[A-Za-z0-9_-]*=*$", "title": "url", "type": [ "string", "null" ] } ], "type": "array", "x-xi-aliases": [ "wmu" ], "x-xi-default": "config image", "x-xi-milestone": "M3 (WP-77)", "x-xi-pro": true, "x-xi-scope": "pipeline", "x-xi-syntax": "base64url URL" }, "webp_options": { "description": "WebP encoder settings. URL: `webp_options`, `webpo`; arguments compression:smart_subsample:preset; default config.", "examples": [ [ "lossy", true, "photo" ] ], "maxItems": 3, "minItems": 1, "prefixItems": [ { "description": "compression", "enum": [ "lossless", "lossy", "near_lossless", null ], "title": "compression", "type": [ "string", "null" ] }, { "description": "smart chroma subsampling", "title": "smart_subsample", "type": [ "boolean", "null" ] }, { "description": "encoder preset", "enum": [ "default", "drawing", "icon", "photo", "picture", "text", null ], "title": "preset", "type": [ "string", "null" ] } ], "type": "array", "x-xi-aliases": [ "webpo" ], "x-xi-default": "config", "x-xi-milestone": "M2 (WP-64)", "x-xi-pro": true, "x-xi-scope": "request", "x-xi-syntax": "compression:smart_subsample:preset" }, "width": { "description": "Target width; 0 keeps the aspect ratio. URL: `width`, `w`; arguments int; default 0.", "examples": [ [ 300 ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "width in pixels", "maximum": 2147483647, "minimum": 0, "title": "width", "type": "integer" } ], "type": "array", "x-xi-aliases": [ "w" ], "x-xi-default": "0", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "pipeline", "x-xi-syntax": "int" }, "zoom": { "description": "Zoom factor applied after resizing. URL: `zoom`, `z`; arguments x[:y]; default 1.", "examples": [ [ 1.5, 2 ] ], "maxItems": 2, "minItems": 1, "prefixItems": [ { "description": "horizontal zoom factor", "exclusiveMinimum": 0, "title": "x", "type": "number" }, { "description": "vertical zoom factor (default: x)", "exclusiveMinimum": 0, "title": "y", "type": "number" } ], "type": "array", "x-xi-aliases": [ "z" ], "x-xi-default": "1", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "pipeline", "x-xi-syntax": "x[:y]" } }, "type": "object" }, "ImgproxyVideoOptions": { "additionalProperties": false, "description": "imgproxy-style /video options (docs/URL-DIALECTS.md §3.8, video transformations), encoded like ImgproxyProcessingOptions. Video options have their own namespace: geometry names (rs, s, w, h, g, c, rot, fl, bg, q, f) follow imgproxy's argument rules with video semantics.", "properties": { "audio_bitrate": { "description": "Audio bit rate (8k..512k; ignored by flac and wav). URL: `audio_bitrate`, `ab`; arguments bit/s (k); default codec default.", "examples": [ [ "128k" ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "bits per second, k suffix", "pattern": "^([0-9]+(\\.[0-9]+)?[kKmM]?)?$", "title": "bitrate", "type": "string" } ], "type": "array", "x-xi-aliases": [ "ab" ], "x-xi-default": "codec default", "x-xi-milestone": "M5 (WP-123)", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "bit/s (k)" }, "audio_channels": { "description": "Downmix to mono or stereo. URL: `audio_channels`, `ach`; arguments 1 or 2; default source.", "examples": [ [ 1 ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "1 mono, 2 stereo; 0 = source (at most 2)", "maximum": 2, "minimum": 0, "title": "channels", "type": "integer" } ], "type": "array", "x-xi-aliases": [ "ach" ], "x-xi-default": "source", "x-xi-milestone": "M5 (WP-123)", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "1 or 2" }, "audio_codec": { "description": "Audio codec (must suit the container). URL: `audio_codec`, `ac`; arguments auto, aac, opus, mp3, flac, pcm; default auto.", "examples": [ [ "aac" ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "audio codec", "enum": [ "aac", "auto", "flac", "mp3", "opus", "pcm" ], "title": "codec", "type": "string" } ], "type": "array", "x-xi-aliases": [ "ac" ], "x-xi-default": "auto", "x-xi-milestone": "M5 (WP-122)", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "auto, aac, opus, mp3, flac, pcm" }, "background": { "description": "Colour of the bars of extend. URL: `background`, `bg`; arguments hex; default 000000.", "examples": [ [ "ffffff" ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "hex colour", "pattern": "^([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$", "title": "color", "type": [ "string", "null" ] } ], "type": "array", "x-xi-aliases": [ "bg" ], "x-xi-default": "000000", "x-xi-milestone": "M5 (WP-122)", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "hex" }, "bypass_cache": { "description": "Skip the result cache (XI_CACHE_ALLOW_BYPASS). URL: `bypass_cache`, `bc`; arguments bool; default false.", "examples": [ [ true ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "skip the result cache", "title": "bypass", "type": [ "boolean", "null" ] } ], "type": "array", "x-xi-aliases": [ "bc" ], "x-xi-default": "false", "x-xi-milestone": "M2 (WP-52)", "x-xi-pro": true, "x-xi-scope": "request", "x-xi-syntax": "bool" }, "cache_tags": { "description": "Tags for the Cache-Tag response header. URL: `cache_tags`, `ct`; arguments tags… (visible ASCII, no commas; replaces earlier tags); default —.", "examples": [ [ "product", "hero" ] ], "items": { "description": "visible ASCII without commas; a single empty tag clears", "pattern": "^[!-+\\--~]*$", "title": "tag", "type": [ "string", "null" ] }, "minItems": 1, "type": "array", "x-xi-aliases": [ "ct" ], "x-xi-default": "—", "x-xi-milestone": "M2 (WP-34b, WP-64 end-to-end test)", "x-xi-pro": true, "x-xi-scope": "request", "x-xi-syntax": "tags… (visible ASCII, no commas; replaces earlier tags)" }, "cachebuster": { "description": "Changes the URL, the cache key and the ETag. URL: `cachebuster`, `cb`; arguments string; default —.", "examples": [ [ "v2" ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "any string", "title": "value", "type": [ "string", "null" ] } ], "type": "array", "x-xi-aliases": [ "cb" ], "x-xi-default": "—", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "string" }, "crf": { "description": "Constant rate factor (wins over quality). URL: `crf`; arguments 0..63; default 0.", "examples": [ [ 30 ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "constant rate factor; 0 = default", "maximum": 63, "minimum": 0, "title": "crf", "type": "integer" } ], "type": "array", "x-xi-aliases": [], "x-xi-default": "0", "x-xi-milestone": "M5 (WP-122)", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "0..63" }, "crop": { "description": "Crop a rectangle (pixels) of the rotated frame before the resize. URL: `crop`, `c`; arguments w:h:gravity; default —.", "examples": [ [ 640, 360, "nowe" ] ], "maxItems": 5, "minItems": 1, "prefixItems": [ { "description": "pixels; 0 = full width", "maximum": 8192, "minimum": 0, "title": "width", "type": "integer" }, { "description": "pixels; 0 = full height", "maximum": 8192, "minimum": 0, "title": "height", "type": [ "integer", "null" ] }, { "description": "compass gravity", "enum": [ "ce", "no", "so", "ea", "we", "noea", "nowe", "soea", "sowe", null ], "title": "type", "type": [ "string", "null" ] }, { "description": "offset in pixels towards the inside of the frame (moves crops)", "maximum": 8192, "minimum": 0, "title": "x_offset", "type": [ "integer", "null" ] }, { "description": "offset in pixels towards the inside of the frame (moves crops)", "maximum": 8192, "minimum": 0, "title": "y_offset", "type": [ "integer", "null" ] } ], "type": "array", "x-xi-aliases": [ "c" ], "x-xi-default": "—", "x-xi-milestone": "M5 (WP-122)", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "w:h:gravity" }, "duration": { "description": "Length of the output from start (exclusive with end). URL: `duration`, `vd`; arguments seconds; default to the end.", "examples": [ [ 3 ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "length of the output", "maximum": 86400, "minimum": 0, "title": "seconds", "type": "number" } ], "type": "array", "x-xi-aliases": [ "vd" ], "x-xi-default": "to the end", "x-xi-milestone": "M5 (WP-122)", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "seconds" }, "end": { "description": "End the output at this time of the source (exclusive with duration). URL: `end`, `ve`; arguments seconds; default end of the source.", "examples": [ [ 4 ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "end of the output in the source", "maximum": 86400, "minimum": 0, "title": "seconds", "type": "number" } ], "type": "array", "x-xi-aliases": [ "ve" ], "x-xi-default": "end of the source", "x-xi-milestone": "M5 (WP-122)", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "seconds" }, "enlarge": { "description": "Let fit enlarge a smaller source. URL: `enlarge`, `el`; arguments bool; default false.", "examples": [ [ true ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "fit may enlarge", "title": "enlarge", "type": [ "boolean", "null" ] } ], "type": "array", "x-xi-aliases": [ "el" ], "x-xi-default": "false", "x-xi-milestone": "M5 (WP-122)", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "bool" }, "expires": { "description": "URL expiry (404 afterwards). URL: `expires`, `exp`; arguments unix ts; default —.", "examples": [ [ 4102444800 ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "unix seconds; ≤ 0 never expires", "title": "timestamp", "type": "integer" } ], "type": "array", "x-xi-aliases": [ "exp" ], "x-xi-default": "—", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "unix ts" }, "extend": { "description": "Pad a fit to the whole box with the background colour. URL: `extend`, `ex`; arguments bool; default false.", "examples": [ [ true ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "pad to the box", "title": "extend", "type": [ "boolean", "null" ] } ], "type": "array", "x-xi-aliases": [ "ex" ], "x-xi-default": "false", "x-xi-milestone": "M5 (WP-122)", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "bool" }, "fade": { "description": "Fade in from black and silence, and out to them (seconds). URL: `fade`, `fd`; arguments in:out; default 0:0.", "examples": [ [ 1, 2 ] ], "maxItems": 2, "minItems": 1, "prefixItems": [ { "description": "fade-in seconds", "maximum": 86400, "minimum": 0, "title": "in", "type": [ "number", "null" ] }, { "description": "fade-out seconds", "maximum": 86400, "minimum": 0, "title": "out", "type": [ "number", "null" ] } ], "type": "array", "x-xi-aliases": [ "fd" ], "x-xi-default": "0:0", "x-xi-milestone": "M5 (WP-123)", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "in:out" }, "filename": { "description": "Content-Disposition file name. URL: `filename`, `fn`; arguments name:encoded; default source basename.", "examples": [ [ "photo" ] ], "maxItems": 2, "minItems": 1, "prefixItems": [ { "description": "file name without extension", "title": "name", "type": [ "string", "null" ] }, { "description": "name is url-safe base64", "title": "encoded", "type": [ "boolean", "null" ] } ], "type": "array", "x-xi-aliases": [ "fn" ], "x-xi-default": "source basename", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "name:encoded" }, "flip": { "description": "Mirror after the rotation. URL: `flip`, `fl`; arguments h:v; default false:false.", "examples": [ [ true, false ] ], "maxItems": 2, "minItems": 1, "prefixItems": [ { "description": "mirror left-right", "title": "horizontal", "type": [ "boolean", "null" ] }, { "description": "mirror top-bottom", "title": "vertical", "type": [ "boolean", "null" ] } ], "type": "array", "x-xi-aliases": [ "fl" ], "x-xi-default": "false:false", "x-xi-milestone": "M5 (WP-122)", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "h:v" }, "format": { "description": "Output container (the source extension sets it too); png and webp are waveform pictures, m3u8 and mpd streams (WP-126). URL: `format`, `f`, `ext`; arguments mp4, webm, m4a, mp3, opus, ogg, flac, wav, png, webp, m3u8, mpd; default mp4.", "examples": [ [ "webm" ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "output container", "enum": [ "mp4", "webm", "m4a", "mp3", "opus", "ogg", "flac", "wav", "png", "webp", "m3u8", "mpd" ], "title": "format", "type": "string" } ], "type": "array", "x-xi-aliases": [ "f", "ext" ], "x-xi-default": "mp4", "x-xi-milestone": "M5 (WP-122)", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "mp4, webm, m4a, mp3, opus, ogg, flac, wav, png, webp, m3u8, mpd" }, "fps": { "description": "Output frame rate (capped by XI_VIDEO_TRANSFORM_MAX_FPS). URL: `fps`; arguments rate; default source.", "examples": [ [ 24 ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "frames per second; 0 keeps the source's", "maximum": 240, "minimum": 0, "title": "fps", "type": "number" } ], "type": "array", "x-xi-aliases": [], "x-xi-default": "source", "x-xi-milestone": "M5 (WP-122)", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "rate" }, "gravity": { "description": "Anchor of fill crops, pads and crops (a compass point; the pixel offsets move crops). URL: `gravity`, `g`; arguments type:x:y; default ce:0:0.", "examples": [ [ "soea", 10, 10 ] ], "maxItems": 3, "minItems": 1, "prefixItems": [ { "description": "compass gravity", "enum": [ "ce", "no", "so", "ea", "we", "noea", "nowe", "soea", "sowe" ], "title": "type", "type": "string" }, { "description": "offset in pixels towards the inside of the frame (moves crops)", "maximum": 8192, "minimum": 0, "title": "x_offset", "type": [ "integer", "null" ] }, { "description": "offset in pixels towards the inside of the frame (moves crops)", "maximum": 8192, "minimum": 0, "title": "y_offset", "type": [ "integer", "null" ] } ], "type": "array", "x-xi-aliases": [ "g" ], "x-xi-default": "ce:0:0", "x-xi-milestone": "M5 (WP-122)", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "type:x:y" }, "hashsum": { "description": "Check the source bytes against a digest. URL: `hashsum`, `hs`; arguments none, or md5/sha1/sha256/sha512:hex; default none.", "examples": [ [ "sha256", "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" ] ], "maxItems": 2, "minItems": 1, "prefixItems": [ { "description": "hash algorithm; none or empty removes the check", "enum": [ "none", "md5", "sha1", "sha256", "sha512", null ], "title": "type", "type": [ "string", "null" ] }, { "description": "hex digest", "pattern": "^[0-9a-fA-F]*$", "title": "hashsum", "type": [ "string", "null" ] } ], "type": "array", "x-xi-aliases": [ "hs" ], "x-xi-default": "none", "x-xi-milestone": "M2 (WP-64)", "x-xi-pro": true, "x-xi-scope": "request", "x-xi-syntax": "none, or md5/sha1/sha256/sha512:hex" }, "height": { "description": "Output height (rounded down to even). URL: `height`, `h`; arguments px; default 0.", "examples": [ [ 360 ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "pixels", "maximum": 8192, "minimum": 0, "title": "height", "type": "integer" } ], "type": "array", "x-xi-aliases": [ "h" ], "x-xi-default": "0", "x-xi-milestone": "M5 (WP-122)", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "px" }, "keyframe_interval": { "description": "Time between keyframes (GOP length, 0.1..60 s). URL: `keyframe_interval`, `ki`; arguments seconds; default 2.", "examples": [ [ 1 ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "seconds between keyframes", "maximum": 60, "minimum": 0, "title": "seconds", "type": "number" } ], "type": "array", "x-xi-aliases": [ "ki" ], "x-xi-default": "2", "x-xi-milestone": "M5 (WP-122)", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "seconds" }, "loudnorm": { "description": "EBU R128 loudness normalisation (single-pass loudnorm). URL: `loudnorm`, `ln`; arguments enabled:I:TP:LRA; default false:-23:-1:7.", "examples": [ [ true, -16, -1.5, 11 ] ], "maxItems": 4, "minItems": 1, "prefixItems": [ { "description": "normalise the loudness", "title": "enabled", "type": [ "boolean", "null" ] }, { "description": "integrated loudness target, LUFS", "maximum": -5, "minimum": -70, "title": "integrated", "type": [ "number", "null" ] }, { "description": "true peak, dBTP", "maximum": 0, "minimum": -9, "title": "true_peak", "type": [ "number", "null" ] }, { "description": "loudness range, LU", "maximum": 50, "minimum": 1, "title": "range", "type": [ "number", "null" ] } ], "type": "array", "x-xi-aliases": [ "ln" ], "x-xi-default": "false:-23:-1:7", "x-xi-milestone": "M5 (WP-123)", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "enabled:I:TP:LRA" }, "mute": { "description": "Drop the audio stream. URL: `mute`, `mu`; arguments bool; default false.", "examples": [ [ true ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "drop the audio", "title": "mute", "type": [ "boolean", "null" ] } ], "type": "array", "x-xi-aliases": [ "mu" ], "x-xi-default": "false", "x-xi-milestone": "M5 (WP-123)", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "bool" }, "overlay_fade": { "description": "Fade the watermark overlay in and out (seconds, within its window). URL: `overlay_fade`, `of`; arguments in:out; default 0:0.", "examples": [ [ 0.5, 0.5 ] ], "maxItems": 2, "minItems": 1, "prefixItems": [ { "description": "fade-in seconds", "maximum": 86400, "minimum": 0, "title": "in", "type": [ "number", "null" ] }, { "description": "fade-out seconds", "maximum": 86400, "minimum": 0, "title": "out", "type": [ "number", "null" ] } ], "type": "array", "x-xi-aliases": [ "of" ], "x-xi-default": "0:0", "x-xi-milestone": "M5 (WP-124)", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "in:out" }, "overlay_window": { "description": "Show the watermark overlay (wm, wmu, wmt) from start to end seconds of the output. URL: `overlay_window`, `ow`; arguments start:end; default 0:0.", "examples": [ [ 1, 4 ] ], "maxItems": 2, "minItems": 1, "prefixItems": [ { "description": "first second of the overlay on the output", "maximum": 86400, "minimum": 0, "title": "start", "type": [ "number", "null" ] }, { "description": "end of the overlay; 0 = the end", "maximum": 86400, "minimum": 0, "title": "end", "type": [ "number", "null" ] } ], "type": "array", "x-xi-aliases": [ "ow" ], "x-xi-default": "0:0", "x-xi-milestone": "M5 (WP-124)", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "start:end" }, "preset": { "description": "Expand video presets (XI_VIDEO_TRANSFORM_PRESETS) in place. URL: `preset`, `pr`; arguments names…; default —.", "examples": [ [ "web" ] ], "items": { "description": "video preset name", "pattern": "^.+$", "title": "name", "type": "string" }, "minItems": 1, "type": "array", "x-xi-aliases": [ "pr" ], "x-xi-default": "—", "x-xi-milestone": "M5 (WP-132)", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "names…" }, "quality": { "description": "Video quality, mapped onto the codec's CRF scale. URL: `quality`, `q`; arguments 1..100; default 0.", "examples": [ [ 70 ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "1..100; 0 = default", "maximum": 100, "minimum": 0, "title": "quality", "type": "integer" } ], "type": "array", "x-xi-aliases": [ "q" ], "x-xi-default": "0", "x-xi-milestone": "M5 (WP-122)", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "1..100" }, "raw": { "description": "Stream the source without processing. URL: `raw`; arguments bool; default false.", "examples": [ [ true ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "stream the source unprocessed", "title": "raw", "type": [ "boolean", "null" ] } ], "type": "array", "x-xi-aliases": [], "x-xi-default": "false", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "bool" }, "resize": { "description": "Resize like imgproxy: fit (scale-down, or contain with enlarge; extend pads), fill and fill-down (cover, cropped by gravity), force (stretch). URL: `resize`, `rs`; arguments type:w:h:enlarge:extend; default fit:0:0:false:false.", "examples": [ [ "fill", 640, 360 ] ], "maxItems": 5, "minItems": 1, "prefixItems": [ { "description": "resizing type", "enum": [ "fit", "fill", "fill-down", "force", null ], "title": "type", "type": [ "string", "null" ] }, { "description": "output width in pixels; 0 keeps the aspect ratio", "maximum": 8192, "minimum": 0, "title": "width", "type": [ "integer", "null" ] }, { "description": "output height in pixels; 0 keeps the aspect ratio", "maximum": 8192, "minimum": 0, "title": "height", "type": [ "integer", "null" ] }, { "description": "fit may enlarge", "title": "enlarge", "type": [ "boolean", "null" ] }, { "description": "pad to the box with the background", "title": "extend", "type": [ "boolean", "null" ] } ], "type": "array", "x-xi-aliases": [ "rs" ], "x-xi-default": "fit:0:0:false:false", "x-xi-milestone": "M5 (WP-122)", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "type:w:h:enlarge:extend" }, "resizing_type": { "description": "Resizing type (auto is not available for video). URL: `resizing_type`, `rt`; arguments fit, fill, fill-down, force; default fit.", "examples": [ [ "fill" ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "resizing type", "enum": [ "fit", "fill", "fill-down", "force" ], "title": "type", "type": "string" } ], "type": "array", "x-xi-aliases": [ "rt" ], "x-xi-default": "fit", "x-xi-milestone": "M5 (WP-122)", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "fit, fill, fill-down, force" }, "return_attachment": { "description": "Download instead of inline display. URL: `return_attachment`, `att`; arguments bool; default config.", "examples": [ [ true ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "Content-Disposition: attachment", "title": "attachment", "type": [ "boolean", "null" ] } ], "type": "array", "x-xi-aliases": [ "att" ], "x-xi-default": "config", "x-xi-milestone": "M1", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "bool" }, "rotate": { "description": "Rotate clockwise after the display matrix. URL: `rotate`, `rot`; arguments multiple of 90; default 0.", "examples": [ [ 90 ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "clockwise degrees, a multiple of 90", "multipleOf": 90, "title": "angle", "type": "integer" } ], "type": "array", "x-xi-aliases": [ "rot" ], "x-xi-default": "0", "x-xi-milestone": "M5 (WP-122)", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "multiple of 90" }, "sample_rate": { "description": "Output sample rate (the codec must support it: Opus 8/12/16/24/48 kHz). URL: `sample_rate`, `sr`; arguments Hz; default source.", "examples": [ [ 44100 ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "8000, 11025, 12000, 16000, 22050, 24000, 32000, 44100, 48000, 88200 or 96000", "maximum": 96000, "minimum": 0, "title": "hz", "type": "integer" } ], "type": "array", "x-xi-aliases": [ "sr" ], "x-xi-default": "source", "x-xi-milestone": "M5 (WP-123)", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "Hz" }, "segment_duration": { "description": "Length of a stream's segments (1..30 s). URL: `segment_duration`, `sgd`; arguments seconds; default XI_VIDEO_TRANSFORM_SEGMENT_DURATION (6).", "examples": [ [ 4 ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "whole seconds", "maximum": 30, "minimum": 1, "title": "seconds", "type": "integer" } ], "type": "array", "x-xi-aliases": [ "sgd" ], "x-xi-default": "XI_VIDEO_TRANSFORM_SEGMENT_DURATION (6)", "x-xi-milestone": "M5 (WP-126)", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "seconds" }, "segment_format": { "description": "Container of a stream's segments: fmp4 (CMAF, HLS 7 and DASH) or ts (MPEG-TS for older HLS players: HLS only, H.264 and AAC muxed in each segment; images with libx264 only). URL: `segment_format`, `sgf`; arguments format; default fmp4.", "examples": [ [ "ts" ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "CMAF (fragmented MP4: fmp4, cmaf) or MPEG-TS (ts, mpegts)", "enum": [ "cmaf", "fmp4", "mpegts", "ts" ], "title": "format", "type": "string" } ], "type": "array", "x-xi-aliases": [ "sgf" ], "x-xi-default": "fmp4", "x-xi-milestone": "M5 (WP-131)", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "format" }, "size": { "description": "Resize without the type. URL: `size`, `s`; arguments w:h:enlarge:extend; default 0:0:false:false.", "examples": [ [ 640, 360, false, true ] ], "maxItems": 4, "minItems": 1, "prefixItems": [ { "description": "output width in pixels; 0 keeps the aspect ratio", "maximum": 8192, "minimum": 0, "title": "width", "type": [ "integer", "null" ] }, { "description": "output height in pixels; 0 keeps the aspect ratio", "maximum": 8192, "minimum": 0, "title": "height", "type": [ "integer", "null" ] }, { "description": "fit may enlarge", "title": "enlarge", "type": [ "boolean", "null" ] }, { "description": "pad to the box with the background", "title": "extend", "type": [ "boolean", "null" ] } ], "type": "array", "x-xi-aliases": [ "s" ], "x-xi-default": "0:0:false:false", "x-xi-milestone": "M5 (WP-122)", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "w:h:enlarge:extend" }, "start": { "description": "Start the output at this time of the source (exact, from the keyframe before it). URL: `start`, `vs`; arguments seconds; default 0.", "examples": [ [ 1.5 ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "start of the output in the source", "maximum": 86400, "minimum": 0, "title": "seconds", "type": "number" } ], "type": "array", "x-xi-aliases": [ "vs" ], "x-xi-default": "0", "x-xi-milestone": "M5 (WP-122)", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "seconds" }, "stream": { "description": "Deliver an HLS or DASH stream (as the m3u8 or mpd extension does) with these renditions (at most 8; none: the configured ladder). Rungs above the source are dropped. URL: `stream`, `st`; arguments protocol:height…; default none (a file).", "examples": [ [ "hls", 360, 720 ] ], "items": { "description": "a rendition by the short side of its frame", "maximum": 4320, "minimum": 64, "title": "height", "type": [ "integer", "null" ] }, "minItems": 1, "prefixItems": [ { "description": "manifest: HLS (m3u8) or DASH (mpd)", "enum": [ "dash", "hls" ], "title": "protocol", "type": "string" } ], "type": "array", "x-xi-aliases": [ "st" ], "x-xi-default": "none (a file)", "x-xi-milestone": "M5 (WP-126)", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "protocol:height…" }, "timecode": { "description": "Draw the output's running time (FFmpeg drawtext with a fixed expansion). URL: `timecode`, `tc`; arguments format:position:x:y:size:color:opacity; default none:sowe:0:0:0:ffffff:1.", "examples": [ [ "hms", "sowe", 8, 8, 20 ] ], "maxItems": 7, "minItems": 1, "prefixItems": [ { "description": "HH:MM:SS.mmm, seconds, or none", "enum": [ "hms", "seconds", "none" ], "title": "format", "type": "string" }, { "description": "compass position", "enum": [ "ce", "no", "so", "ea", "we", "noea", "nowe", "soea", "sowe", null ], "title": "position", "type": [ "string", "null" ] }, { "description": "offset in pixels", "title": "x_offset", "type": [ "number", "null" ] }, { "description": "offset in pixels", "title": "y_offset", "type": [ "number", "null" ] }, { "description": "font size in pixels; 0 = default", "maximum": 512, "minimum": 0, "title": "size", "type": [ "integer", "null" ] }, { "description": "text colour (white)", "pattern": "^([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$", "title": "color", "type": [ "string", "null" ] }, { "description": "opacity (1)", "maximum": 1, "minimum": 0, "title": "opacity", "type": [ "number", "null" ] } ], "type": "array", "x-xi-aliases": [ "tc" ], "x-xi-default": "none:sowe:0:0:0:ffffff:1", "x-xi-milestone": "M5 (WP-124)", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "format:position:x:y:size:color:opacity" }, "video_bitrate": { "description": "Cap the video bit rate (50k..200M). URL: `video_bitrate`, `vb`; arguments bit/s (k, M); default uncapped.", "examples": [ [ "2M" ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "bits per second, k or M suffix", "pattern": "^([0-9]+(\\.[0-9]+)?[kKmM]?)?$", "title": "bitrate", "type": "string" } ], "type": "array", "x-xi-aliases": [ "vb" ], "x-xi-default": "uncapped", "x-xi-milestone": "M5 (WP-122)", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "bit/s (k, M)" }, "video_codec": { "description": "Video codec (h264 and hevc need the gpl image). URL: `video_codec`, `vc`; arguments auto, h264, av1, vp9, hevc; default auto.", "examples": [ [ "av1" ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "video codec", "enum": [ "auto", "av1", "h264", "h265", "hevc", "vp9" ], "title": "codec", "type": "string" } ], "type": "array", "x-xi-aliases": [ "vc" ], "x-xi-default": "auto", "x-xi-milestone": "M5 (WP-122)", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "auto, h264, av1, vp9, hevc" }, "volume": { "description": "Change the audio level (-60 dB..+20 dB). URL: `volume`, `vol`; arguments factor or NdB; default 1.", "examples": [ [ "-6dB" ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "a factor (0.5) or decibels (-6dB)", "pattern": "^([0-9]+(\\.[0-9]+)?|[+\\-]?[0-9]+(\\.[0-9]+)?[dD][bB])?$", "title": "gain", "type": "string" } ], "type": "array", "x-xi-aliases": [ "vol" ], "x-xi-default": "1", "x-xi-milestone": "M5 (WP-123)", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "factor or NdB" }, "watermark": { "description": "Draw the watermark. URL: `watermark`, `wm`; arguments opacity:pos:x:y:scale; pos incl. `re` (tile), `ch` (chessboard, Pro); default off.", "examples": [ [ 0.5, "soea", 10, 10, 0.2 ] ], "maxItems": 5, "minItems": 1, "prefixItems": [ { "description": "opacity (0..1); 0 disables", "maximum": 1, "minimum": 0, "title": "opacity", "type": "number" }, { "description": "compass position, re (tile) or ch (chessboard)", "enum": [ "ce", "no", "so", "ea", "we", "noea", "nowe", "soea", "sowe", "re", "ch", null ], "title": "position", "type": [ "string", "null" ] }, { "description": "x offset", "title": "x_offset", "type": [ "number", "null" ] }, { "description": "y offset", "title": "y_offset", "type": [ "number", "null" ] }, { "description": "scale relative to the image", "exclusiveMinimum": 0, "title": "scale", "type": [ "number", "null" ] } ], "type": "array", "x-xi-aliases": [ "wm" ], "x-xi-default": "off", "x-xi-milestone": "M1 (`re` M1, `ch` M3 WP-77)", "x-xi-pro": false, "x-xi-scope": "pipeline", "x-xi-syntax": "opacity:pos:x:y:scale; pos incl. `re` (tile), `ch` (chessboard, Pro)" }, "watermark_rotate": { "description": "Watermark rotation, clockwise. URL: `watermark_rotate`, `wm_rot`, `wmr`; arguments degrees; default 0.", "examples": [ [ 45 ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "degrees", "title": "angle", "type": "number" } ], "type": "array", "x-xi-aliases": [ "wm_rot", "wmr" ], "x-xi-default": "0", "x-xi-milestone": "M3 (WP-77)", "x-xi-pro": true, "x-xi-scope": "pipeline", "x-xi-syntax": "degrees" }, "watermark_shadow": { "description": "Watermark shadow: its alpha blurred with sigma, in black. URL: `watermark_shadow`, `wmsh`; arguments sigma; default off.", "examples": [ [ 2 ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "shadow blur sigma", "maximum": 1000, "minimum": 0, "title": "sigma", "type": "number" } ], "type": "array", "x-xi-aliases": [ "wmsh" ], "x-xi-default": "off", "x-xi-milestone": "M3 (WP-77)", "x-xi-pro": true, "x-xi-scope": "pipeline", "x-xi-syntax": "sigma" }, "watermark_size": { "description": "Watermark size in pixels (fit, enlarging; used when the wm scale is 0). URL: `watermark_size`, `wms`; arguments w:h; default 0:0.", "examples": [ [ 100, 0 ] ], "maxItems": 2, "minItems": 1, "prefixItems": [ { "description": "width; 0 = auto", "maximum": 65536, "minimum": 0, "title": "width", "type": [ "integer", "null" ] }, { "description": "height; 0 = auto", "maximum": 65536, "minimum": 0, "title": "height", "type": [ "integer", "null" ] } ], "type": "array", "x-xi-aliases": [ "wms" ], "x-xi-default": "0:0", "x-xi-milestone": "M3 (WP-77)", "x-xi-pro": true, "x-xi-scope": "pipeline", "x-xi-syntax": "w:h" }, "watermark_text": { "description": "Text watermark (replaces watermark_url); markup is sanitised to a whitelist, font `sans 16` by default. URL: `watermark_text`, `wmt`; arguments base64url Pango markup; default —.", "examples": [ [ "SGVsbG8" ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "url-safe base64 of Pango markup", "pattern": "^[A-Za-z0-9_-]*=*$", "title": "text", "type": [ "string", "null" ] } ], "type": "array", "x-xi-aliases": [ "wmt" ], "x-xi-default": "—", "x-xi-milestone": "M3 (WP-78)", "x-xi-pro": true, "x-xi-scope": "pipeline", "x-xi-syntax": "base64url Pango markup" }, "watermark_url": { "description": "Watermark image source, fetched like a source (allowlist, SSRF policy, byte limit, origin cache). URL: `watermark_url`, `wmu`; arguments base64url URL; default config image.", "examples": [ [ "aHR0cHM6Ly9leGFtcGxlLmNvbS93LnBuZw" ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "url-safe base64 of the watermark source URL; empty = configured image", "pattern": "^[A-Za-z0-9_-]*=*$", "title": "url", "type": [ "string", "null" ] } ], "type": "array", "x-xi-aliases": [ "wmu" ], "x-xi-default": "config image", "x-xi-milestone": "M3 (WP-77)", "x-xi-pro": true, "x-xi-scope": "pipeline", "x-xi-syntax": "base64url URL" }, "waveform": { "description": "Render the audio as a width × height (default 1024×256) PNG or WebP picture. URL: `waveform`, `wf`; arguments enabled:color:background:split; default false:000000::false.", "examples": [ [ true, "2266cc", "ffffff", false ] ], "maxItems": 4, "minItems": 1, "prefixItems": [ { "description": "render a waveform picture", "title": "enabled", "type": [ "boolean", "null" ] }, { "description": "wave colour", "pattern": "^([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$", "title": "color", "type": [ "string", "null" ] }, { "description": "background colour; empty is transparent", "pattern": "^([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$", "title": "background", "type": [ "string", "null" ] }, { "description": "one band per channel", "title": "split_channels", "type": [ "boolean", "null" ] } ], "type": "array", "x-xi-aliases": [ "wf" ], "x-xi-default": "false:000000::false", "x-xi-milestone": "M5 (WP-123)", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "enabled:color:background:split" }, "width": { "description": "Output width (rounded down to even). URL: `width`, `w`; arguments px; default 0.", "examples": [ [ 640 ] ], "maxItems": 1, "minItems": 1, "prefixItems": [ { "description": "pixels", "maximum": 8192, "minimum": 0, "title": "width", "type": "integer" } ], "type": "array", "x-xi-aliases": [ "w" ], "x-xi-default": "0", "x-xi-milestone": "M5 (WP-122)", "x-xi-pro": false, "x-xi-scope": "request", "x-xi-syntax": "px" } }, "type": "object" }, "InfoClass": { "additionalProperties": false, "properties": { "class_id": { "description": "Class index in the classifier's output (the ImageNet-1k class id by default).", "format": "int64", "type": "integer" }, "confidence": { "description": "Class probability, 0-1.", "format": "double", "maximum": 1, "minimum": 0, "type": "number" }, "name": { "description": "Class name (ImageNet-1k: tabby cat, golden retriever, pizza, ...).", "type": "string" } }, "required": [ "class_id", "name", "confidence" ], "type": "object" }, "InfoContainer": { "additionalProperties": false, "properties": { "content": { "description": "What the image is to the document: composite (full-size flattened image), thumbnail (reduced copy), preview (first page), document (SVGZ: the whole document, decompressed), frame (MNG: the first image of the animation) or converted (WMF, EMF: the document converted to SVG).", "type": "string" }, "entry": { "description": "Where the image was found: the path inside the archive (mergedimage.png, QuickLook/Thumbnail.png, previews/preview.png, ...), gzip for SVGZ, header thumbnail for Paint.NET, first frame for MNG, JDAT (JDAT+IDAT, JDAT+JDAA with alpha) for JNG, xi-metafile2svg for WMF and EMF.", "type": "string" }, "format": { "description": "Container format: ora (OpenRaster), kra (Krita), procreate, sketch, svgz, pdn (Paint.NET), mng, jng, wmf or emf.", "type": "string" }, "mime_type": { "description": "Media type of the container, e.g. image/openraster.", "type": "string" } }, "required": [ "format", "mime_type", "entry", "content" ], "type": "object" }, "InfoCrop": { "additionalProperties": false, "properties": { "height": { "format": "double", "type": "number" }, "left": { "format": "double", "type": "number" }, "top": { "format": "double", "type": "number" }, "width": { "format": "double", "type": "number" } }, "required": [ "left", "top", "width", "height" ], "type": "object" }, "InfoDominant": { "additionalProperties": false, "properties": { "dark_muted": { "$ref": "#/components/schemas/InfoRGB" }, "dark_vibrant": { "$ref": "#/components/schemas/InfoRGB" }, "light_muted": { "$ref": "#/components/schemas/InfoRGB" }, "light_vibrant": { "$ref": "#/components/schemas/InfoRGB" }, "muted": { "$ref": "#/components/schemas/InfoRGB" }, "vibrant": { "$ref": "#/components/schemas/InfoRGB" } }, "type": "object" }, "InfoObject": { "additionalProperties": false, "properties": { "class_id": { "description": "0 for faces (the face model's only class), the COCO class index for objects.", "format": "int64", "type": "integer" }, "class_name": { "description": "face, or a COCO class name (person, car, dog, traffic light, ...).", "type": "string" }, "confidence": { "description": "Detection score, 0-1.", "format": "double", "maximum": 1, "minimum": 0, "type": "number" }, "height": { "description": "Box height, as a fraction of the image height.", "format": "double", "type": "number" }, "landmarks": { "description": "Face landmarks [x, y] as fractions of the image: right eye, left eye, nose tip, right and left mouth corners (faces only; an extension over imgproxy).", "items": { "items": { "format": "double", "type": "number" }, "maxItems": 2, "minItems": 2, "type": [ "array", "null" ] }, "type": [ "array", "null" ] }, "left": { "description": "Left edge of the box, as a fraction of the oriented image width.", "format": "double", "type": "number" }, "top": { "description": "Top edge of the box, as a fraction of the oriented image height.", "format": "double", "type": "number" }, "width": { "description": "Box width, as a fraction of the image width.", "format": "double", "type": "number" } }, "required": [ "class_id", "class_name", "confidence", "left", "top", "width", "height" ], "type": "object" }, "InfoRGB": { "additionalProperties": false, "properties": { "B": { "format": "int32", "minimum": 0, "type": "integer" }, "G": { "format": "int32", "minimum": 0, "type": "integer" }, "R": { "format": "int32", "minimum": 0, "type": "integer" } }, "required": [ "R", "G", "B" ], "type": "object" }, "InfoRGBA": { "additionalProperties": false, "properties": { "A": { "format": "int32", "minimum": 0, "type": "integer" }, "B": { "format": "int32", "minimum": 0, "type": "integer" }, "G": { "format": "int32", "minimum": 0, "type": "integer" }, "R": { "format": "int32", "minimum": 0, "type": "integer" } }, "required": [ "R", "G", "B", "A" ], "type": "object" }, "InfoResponse": { "additionalProperties": false, "description": "imgproxy-compatible /info body (docs/URL-DIALECTS.md §3.3). Each section is present exactly when its info option is on; a requested exif, iptc or xmp section is {} when the source has none.", "properties": { "alpha": { "description": "Whether the source has an alpha channel (info option alpha).", "type": "boolean" }, "average": { "$ref": "#/components/schemas/InfoRGBA", "description": "Average RGBA colour (info option average)." }, "bands": { "description": "Number of bands (channels), alpha included (info option bands).", "format": "int64", "type": "integer" }, "blurhash": { "description": "BlurHash string (info option blurhash).", "type": "string" }, "classification": { "description": "The top_k classes of the image classifier (ImageNet-1k by default), best first; absent when no classifier is available (the option is then listed in X-Xi-Ignored) (info option classify).", "items": { "$ref": "#/components/schemas/InfoClass" }, "type": [ "array", "null" ] }, "colorspace": { "description": "libvips interpretation name: srgb, b-w, rgb16, cmyk, ... (info option colorspace).", "type": "string" }, "container": { "$ref": "#/components/schemas/InfoContainer", "description": "xtandard-image extension (info option format): the source is a designer document (OpenRaster, Krita, Procreate, Sketch, SVGZ, Paint.NET) and format, dimensions and the other fields describe the image embedded in it; absent otherwise." }, "crop": { "$ref": "#/components/schemas/InfoCrop", "description": "Crop rectangle as fractions of the oriented image (info option crop)." }, "dominant_colors": { "$ref": "#/components/schemas/InfoDominant", "description": "Dominant RGB colours by class; missing classes are left out unless built (info option dominant_colors)." }, "exif": { "additionalProperties": { "type": "string" }, "description": "EXIF tags keyed by libexif title, with libexif's human-readable values; {} when the source has none (info option exif).", "type": "object" }, "format": { "description": "Source format in imgproxy's names: jpeg (UltraHDR too), png, webp, avif, heic, jxl, gif, tiff, bmp, ico, svg, pdf, psd, ... (info option format).", "type": "string" }, "gain_map": { "description": "xtandard-image extension: true when the source carries an HDR gain map (UltraHDR JPEG, ISO 21496-1 JPEG, AVIF or HEIC tmap item); its pixels are the SDR base, and preserve_hdr or gain_map:hdr render the HDR version for AVIF, JPEG XL and JPEG outputs; absent otherwise.", "type": "boolean" }, "hashsums": { "additionalProperties": { "type": "string" }, "description": "Hex digests of the source bytes by algorithm: md5, sha1, sha256, sha512 (info option calc_hashsums).", "type": "object" }, "hdr": { "description": "xtandard-image extension: true for scene-linear sources (OpenEXR, Radiance, PFM), which imgproxy does not read, and for sources with an HDR gain map; absent otherwise.", "type": "boolean" }, "height": { "description": "Height of one page or frame in pixels, EXIF orientation applied (info option dimensions).", "format": "int64", "type": "integer" }, "iptc": { "additionalProperties": {}, "description": "IPTC IIM datasets keyed by title, repeatable datasets as arrays; {} when the source has none (info option iptc).", "type": "object" }, "mime_type": { "description": "Source media type, e.g. image/jpeg; HEIC is image/heif (info option format).", "type": "string" }, "objects": { "description": "Detected faces and objects, best first within each model (faces first), with boxes as fractions of the oriented image; [] when none were found (info option detect_objects).", "items": { "$ref": "#/components/schemas/InfoObject" }, "type": [ "array", "null" ] }, "orientation": { "description": "EXIF orientation 1-8, 1 when absent (info option dimensions).", "format": "int64", "maximum": 8, "minimum": 1, "type": "integer" }, "pages_number": { "description": "Number of pages, or frames of an animation (info option pages_number).", "format": "int64", "minimum": 1, "type": "integer" }, "palette": { "description": "Up to the requested number of RGBA colours (info option palette).", "items": { "$ref": "#/components/schemas/InfoRGBA" }, "type": [ "array", "null" ] }, "perceptual_hash": { "description": "Perceptual hash as 16 lower-case hex digits (info option phash).", "type": "string" }, "photoshop": { "additionalProperties": {}, "description": "Photoshop image resources, e.g. resolution, when present (info option iptc).", "type": "object" }, "sample_format": { "description": "libvips band format name: uchar, ushort, float, ... (info option sample_format).", "type": "string" }, "size": { "description": "Source size in bytes (info option size).", "format": "int64", "type": "integer" }, "thumb_hash": { "description": "ThumbHash as upper-case hex (info option thumbhash).", "type": "string" }, "video_meta": { "additionalProperties": {}, "description": "Container metadata of a video source (info option video_meta): the container tags as strings (major_brand, creation_time, encoder, ...), like imgproxy, plus container (mov, matroska, avi), codec, duration (s), fps, bit_rate (bit/s), frames, width and height (coded size) and rotation (clockwise degrees) of the video stream thumbnails are taken from.", "type": "object" }, "video_streams": { "description": "Every stream of a video source in file order (info option video_meta), in imgproxy's shape.", "items": { "$ref": "#/components/schemas/InfoVideoStream" }, "type": [ "array", "null" ] }, "width": { "description": "Width of one page or frame in pixels, EXIF orientation applied (info option dimensions).", "format": "int64", "type": "integer" }, "xmp": { "additionalProperties": { "additionalProperties": {}, "type": "object" }, "description": "XMP properties grouped by namespace prefix; {} when the source has none (info option xmp).", "type": "object" } }, "type": "object" }, "InfoVideoStream": { "additionalProperties": false, "properties": { "bps": { "description": "Bit rate in bits per second, when known.", "format": "int64", "type": "integer" }, "channels": { "description": "xtandard-image extension: channel count of an audio stream.", "format": "int64", "type": "integer" }, "codec": { "description": "FFmpeg codec name: h264, hevc, vp9, av1, aac, ...", "type": "string" }, "duration": { "description": "Duration in seconds, when known.", "format": "double", "type": "number" }, "fps": { "description": "Average frame rate of a video stream.", "format": "double", "type": "number" }, "frequency": { "description": "Sample rate of an audio stream in Hz.", "format": "int64", "type": "integer" }, "height": { "description": "xtandard-image extension: coded height of a video stream.", "format": "int64", "type": "integer" }, "language": { "description": "ISO 639-2 language tag, when set.", "type": "string" }, "layout": { "description": "Channel layout of an audio stream: mono, stereo, 5.1(side), ...", "type": "string" }, "rotation": { "description": "xtandard-image extension: clockwise display rotation of a video stream (0, 90, 180, 270).", "format": "int64", "type": "integer" }, "type": { "description": "video, audio, subtitle, data or attachment.", "type": "string" }, "width": { "description": "xtandard-image extension: coded width of a video stream.", "format": "int64", "type": "integer" } }, "required": [ "type", "codec" ], "type": "object" }, "PlaygroundArg": { "additionalProperties": false, "properties": { "doc": { "description": "Description.", "type": "string" }, "enum": { "description": "Accepted values of an enum argument.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "max": { "description": "Upper bound of a numeric argument.", "format": "double", "type": "number" }, "min": { "description": "Lower bound of a numeric argument.", "format": "double", "type": "number" }, "name": { "description": "Argument name.", "type": "string" }, "optional": { "description": "May be left empty.", "type": "boolean" }, "pattern": { "description": "Regular expression for string arguments.", "type": "string" }, "type": { "description": "Argument type.", "enum": [ "string", "integer", "number", "boolean", "enum", "color", "base64", "direction" ], "type": "string" } }, "required": [ "name", "type" ], "type": "object" }, "PlaygroundCatalogue": { "additionalProperties": false, "properties": { "grammar": { "description": "The grammar the options belong to.", "enum": [ "imgproxy", "query", "imgix", "cloudinary", "imagekit", "cloudflare", "wsrv", "thumbor", "bunny", "awssih" ], "type": "string" }, "options": { "description": "Options, in documentation order.", "items": { "$ref": "#/components/schemas/PlaygroundOption" }, "type": [ "array", "null" ] } }, "required": [ "grammar", "options" ], "type": "object" }, "PlaygroundErrorResponse": { "additionalProperties": false, "properties": { "error": { "description": "Client-safe message.", "type": "string" } }, "required": [ "error" ], "type": "object" }, "PlaygroundForm": { "additionalProperties": false, "properties": { "args": { "description": "Leading positional arguments; trailing ones may be omitted.", "items": { "$ref": "#/components/schemas/PlaygroundArg" }, "type": [ "array", "null" ] }, "min_items": { "description": "Least number of arguments (0 means 1).", "format": "int64", "type": "integer" }, "rest": { "description": "A group of arguments repeated after args.", "items": { "$ref": "#/components/schemas/PlaygroundArg" }, "type": [ "array", "null" ] } }, "required": [ "args" ], "type": "object" }, "PlaygroundGallerySample": { "additionalProperties": false, "properties": { "allowed": { "description": "A configured http source (or dev mode) allows the URL.", "type": "boolean" }, "bytes": { "description": "File size when the list was made.", "format": "int64", "type": "integer" }, "format": { "description": "Input format the file exercises.", "type": "string" }, "licence": { "description": "SPDX licence of the file.", "type": "string" }, "name": { "description": "Description.", "type": "string" }, "notes": { "description": "What the file shows or the expected outcome.", "type": "string" }, "source": { "description": "Where the file comes from; the attribution for CC-BY files.", "type": "string" }, "tags": { "description": "Lower-case keywords: colour type, bit depth, alpha, animated, multi-page, hdr, icc, camera brand; \"large\" marks files over 20 MB and \"gap\" formats not decoded yet (expected 422).", "items": { "type": "string" }, "type": [ "array", "null" ] }, "url": { "description": "Public URL, fetched through an http source.", "type": "string" }, "variant": { "description": "Configuration within the format: colour type, bit depth, compression, animation, camera model (\"cmyk 16-bit\", \"Canon CR3 C-RAW\").", "type": "string" } }, "required": [ "format", "name", "url", "bytes", "licence", "source", "allowed" ], "type": "object" }, "PlaygroundListEntry": { "additionalProperties": false, "properties": { "dir": { "description": "A directory: list it with prefix=key.", "type": "boolean" }, "key": { "description": "Key relative to the source (xi://\u003csource\u003e/\u003ckey\u003e); directories end with /.", "type": "string" }, "name": { "description": "File or directory name.", "type": "string" }, "size": { "description": "File size in bytes.", "format": "int64", "type": "integer" } }, "required": [ "name", "key" ], "type": "object" }, "PlaygroundListResponse": { "additionalProperties": false, "properties": { "entries": { "description": "Directories first, then files, each sorted by name.", "items": { "$ref": "#/components/schemas/PlaygroundListEntry" }, "type": [ "array", "null" ] }, "prefix": { "description": "The directory listed, relative to the source; empty for its root.", "type": "string" }, "source": { "description": "Source name.", "type": "string" }, "truncated": { "description": "More than 500 entries: only the first 500 are listed.", "type": "boolean" } }, "required": [ "source", "prefix", "entries" ], "type": "object" }, "PlaygroundMediaAudio": { "additionalProperties": false, "properties": { "channels": { "description": "Channel count.", "format": "int64", "type": "integer" }, "codec": { "description": "FFmpeg codec name: aac, opus, mp3, flac, pcm_s16le, ...", "type": "string" }, "sample_rate": { "description": "Sample rate in Hz.", "format": "int64", "type": "integer" } }, "required": [ "codec" ], "type": "object" }, "PlaygroundMediaInfo": { "additionalProperties": false, "properties": { "audio": { "$ref": "#/components/schemas/PlaygroundMediaAudio", "description": "The audio stream; absent for silent files." }, "bit_rate": { "description": "Average bit rate in bits per second (size × 8 / duration).", "format": "int64", "type": "integer" }, "container": { "description": "FFmpeg demuxer that read the file (mov,mp4,m4a,3gp,3g2,mj2; matroska,webm; mp3; ogg; flac; wav).", "type": "string" }, "duration": { "description": "Duration in seconds; absent when unknown.", "format": "double", "type": "number" }, "size": { "description": "File size in bytes.", "format": "int64", "type": "integer" }, "video": { "$ref": "#/components/schemas/PlaygroundMediaVideo", "description": "The video stream; absent for audio files." } }, "required": [ "container", "size" ], "type": "object" }, "PlaygroundMediaVideo": { "additionalProperties": false, "properties": { "codec": { "description": "FFmpeg codec name: h264, hevc, av1, vp9, ...", "type": "string" }, "fps": { "description": "Average frame rate.", "format": "double", "type": "number" }, "height": { "description": "Coded height in pixels.", "format": "int64", "type": "integer" }, "rotation": { "description": "Display rotation, clockwise degrees.", "format": "int64", "type": "integer" }, "width": { "description": "Coded width in pixels.", "format": "int64", "type": "integer" } }, "required": [ "codec", "width", "height" ], "type": "object" }, "PlaygroundMeta": { "additionalProperties": false, "properties": { "catalogues": { "description": "Option catalogues (internal/apidoc), one per URL grammar.", "items": { "$ref": "#/components/schemas/PlaygroundCatalogue" }, "type": [ "array", "null" ] }, "classes": { "description": "Detection classes: face, the COCO class names and supercategories.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "detection": { "description": "The detection models are loaded: face and object gravity, detect_objects.", "type": "boolean" }, "formats": { "description": "Output formats the server encodes.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "gallery": { "description": "Public sample files per input format and variant (docs/research/format-gap.md), fetched through the http sources.", "items": { "$ref": "#/components/schemas/PlaygroundGallerySample" }, "type": [ "array", "null" ] }, "info_options": { "description": "imgproxy /info options (internal/apidoc, the ImgproxyInfoOptions schema) for the Info panel's builder.", "items": { "$ref": "#/components/schemas/PlaygroundOption" }, "type": [ "array", "null" ] }, "max_upload_bytes": { "description": "Largest upload in bytes (XI_LIMITS_MAX_SRC_BYTES).", "format": "int64", "type": "integer" }, "mounts": { "description": "Enabled dialect mounts, in configuration order.", "items": { "$ref": "#/components/schemas/PlaygroundMount" }, "type": [ "array", "null" ] }, "path_prefix": { "description": "XI_SERVER_PATH_PREFIX; every generated URL starts with it.", "type": "string" }, "pdf_passwords": { "description": "api/sign encrypts pdf_password for password-protected PDFs (XI_ENCRYPTION_KEYS is set); signed mounts only.", "type": "boolean" }, "presets": { "description": "Configured preset names.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "public": { "description": "XI_PLAYGROUND_PUBLIC: the playground is also served on the public listener.", "type": "boolean" }, "public_addr": { "description": "XI_SERVER_ADDR (the page derives a default public base URL from its port).", "type": "string" }, "query_method": { "description": "XI_SERVER_QUERY_METHOD: the query dialect's endpoints accept HTTP QUERY (RFC 10008), its parameters in the request content.", "type": "boolean" }, "recipes": { "description": "Ready-made sessions of the Examples tool (internal/playground/recipes.json): source, dialect and options, loaded into the builder with one click.", "items": { "$ref": "#/components/schemas/PlaygroundRecipe" }, "type": [ "array", "null" ] }, "samples": { "description": "Built-in sample images (repository fixtures), served as playground://samples/\u003cname\u003e to the playground only; they work offline.", "items": { "$ref": "#/components/schemas/PlaygroundSample" }, "type": [ "array", "null" ] }, "signing": { "$ref": "#/components/schemas/PlaygroundSigning", "description": "Signing mode; keys and salts are never included." }, "sources": { "description": "Named sources: name, type and the source strings each accepts (xi://\u003cname\u003e/\u003ckey\u003e), never their settings.", "items": { "$ref": "#/components/schemas/PlaygroundSource" }, "type": [ "array", "null" ] }, "uploads": { "description": "XI_PLAYGROUND_UPLOADS: api/upload accepts files (playground://uploads/\u003cid\u003e, 10 minutes).", "type": "boolean" }, "version": { "description": "Server build version.", "type": "string" }, "video": { "description": "Video sources are decoded (FFmpeg, full image).", "type": "boolean" }, "video_options": { "description": "imgproxy-style /video options (internal/apidoc, the ImgproxyVideoOptions schema): video transformations, audio and waveforms.", "items": { "$ref": "#/components/schemas/PlaygroundOption" }, "type": [ "array", "null" ] }, "video_transform": { "$ref": "#/components/schemas/PlaygroundVideoTransform", "description": "Video transformations (/video, /q/video and the dialects' video URLs) this server runs: what this build can write and the output limits. Absent when XI_VIDEO_TRANSFORM_ENABLED is off or XI_ROLE=image." }, "watermark": { "description": "A default watermark image is configured (XI_PROCESSING_WATERMARK_SOURCE; the source itself is never included): imgproxy wm without wmu or wmt draws it.", "type": "boolean" } }, "required": [ "version", "path_prefix", "public_addr", "public", "signing", "mounts", "catalogues", "info_options", "video_options", "presets", "sources", "formats", "samples", "gallery", "uploads", "max_upload_bytes", "detection", "video", "classes", "query_method", "pdf_passwords", "watermark", "recipes" ], "type": "object" }, "PlaygroundMount": { "additionalProperties": false, "properties": { "arguments_separator": { "description": "imgproxy argument separator (XI_DIALECTS_IMGPROXY_ARGUMENTS_SEPARATOR).", "type": "string" }, "dialect": { "description": "Dialect name.", "type": "string" }, "example": { "description": "Example path and query after the prefix (free-form grammar).", "type": "string" }, "grammar": { "description": "URL grammar the page builds with the catalogue of the same name; path is free-form.", "enum": [ "imgproxy", "query", "imgix", "cloudinary", "imagekit", "cloudflare", "wsrv", "thumbor", "bunny", "awssih", "path" ], "type": "string" }, "hosts": { "description": "Host bindings.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "id": { "description": "Mount name; the mount field of a sign request.", "type": "string" }, "keyed": { "description": "The server holds a key for the scheme; false returns unsigned URLs.", "type": "boolean" }, "prefix": { "description": "Path prefix; empty for host-only mounts.", "type": "string" }, "prefixes": { "description": "Every path prefix of the mount, prefix first, when it has more than one (simple providers: native prefixes and /simple/\u003cname\u003e/).", "items": { "type": "string" }, "type": [ "array", "null" ] }, "scheme": { "description": "Signature the sign endpoint computes for this mount.", "enum": [ "imgproxy", "xi_sig", "thumbor", "imgix", "none" ], "type": "string" }, "source": { "description": "Named source relative keys resolve against.", "type": "string" }, "unsigned_policy": { "description": "Effective unsigned policy.", "enum": [ "allow", "restricted", "deny" ], "type": "string" } }, "required": [ "id", "dialect", "unsigned_policy", "scheme", "keyed", "grammar" ], "type": "object" }, "PlaygroundOption": { "additionalProperties": false, "properties": { "aliases": { "description": "Accepted short names.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "default": { "description": "Value used when the option is absent, as imgproxy documents it (info options).", "type": "string" }, "doc": { "description": "One-line description.", "type": "string" }, "example": { "description": "A valid argument string.", "type": "string" }, "forms": { "description": "Accepted argument shapes; most options have one.", "items": { "$ref": "#/components/schemas/PlaygroundForm" }, "type": [ "array", "null" ] }, "group": { "description": "Builder category; report, hashes and security are Info panel groups, time and audio video builder groups.", "enum": [ "size", "gravity", "format", "color", "effects", "watermark", "metadata", "frames", "detection", "delivery", "presets", "other", "report", "hashes", "security", "time", "audio" ], "type": "string" }, "milestone": { "description": "Milestone that implements the option.", "type": "string" }, "name": { "description": "Canonical name.", "type": "string" }, "security": { "description": "Needs XI_SECURITY_ALLOW_SECURITY_OPTIONS.", "type": "boolean" } }, "required": [ "name", "forms" ], "type": "object" }, "PlaygroundProbeRequest": { "additionalProperties": false, "properties": { "source": { "description": "Source string (as in a URL: https://…, xi://\u003csource\u003e/\u003ckey\u003e, playground://…), resolved and fetched like a request's source.", "maxLength": 8192, "minLength": 1, "type": "string" } }, "required": [ "source" ], "type": "object" }, "PlaygroundRecipe": { "additionalProperties": false, "properties": { "category": { "description": "Card group.", "enum": [ "watermark", "video", "showcase" ], "type": "string" }, "description": { "description": "What the recipe shows.", "type": "string" }, "dialect": { "description": "Dialect of the mount the recipe is built on (its first mount).", "type": "string" }, "ext": { "description": "imgproxy source extension (the output container of a video recipe).", "type": "string" }, "id": { "description": "Stable identifier.", "type": "string" }, "info": { "description": "Info panel options ([name, value…]); the recipe opens the Info (source) tab.", "items": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "type": [ "array", "null" ] }, "needs": { "description": "Server features the recipe needs: watermark (a default watermark image), detection (the models), video (FFmpeg: video sources and mp4/webm output), video_transform (video transformations, XI_VIDEO_TRANSFORM_ENABLED), h264 and hevc (the gpl image's H.264 and HEVC encoders, video_transform.codecs), video_presets (the demo's video presets web and preview, video_transform.presets).", "items": { "enum": [ "watermark", "detection", "video", "video_transform", "h264", "hevc", "video_presets" ], "type": "string" }, "type": [ "array", "null" ] }, "pipelines": { "description": "Builder entries per chained pipeline: [name, value…] (catalogue names; base64 arguments plain).", "items": { "items": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "type": [ "array", "null" ] }, "type": [ "array", "null" ] }, "raw": { "$ref": "#/components/schemas/PlaygroundRecipeRaw", "description": "Path and query written by hand ({src} is the source, {key} its key on the mount's source); the builder is bypassed." }, "source": { "description": "Source string: xi://local/\u003cfixture\u003e or a public gallery URL.", "type": "string" }, "tags": { "description": "Lower-case keywords for the filter.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "title": { "description": "Card title.", "type": "string" }, "url": { "description": "Path and query after the mount prefix (and the imgproxy signature segment), unsigned.", "type": "string" }, "video": { "description": "A video transformation: built on /video (imgproxy) or /q/video (query) from the video option catalogue.", "type": "boolean" } }, "required": [ "id", "title", "description", "category", "dialect", "source", "pipelines", "url", "tags" ], "type": "object" }, "PlaygroundRecipeRaw": { "additionalProperties": false, "properties": { "path": { "description": "Path after the mount prefix; {src} is the source, {key} its key on the mount's source.", "type": "string" }, "query": { "description": "Query without ?; {src} is the source, {key} its key on the mount's source.", "type": "string" } }, "required": [ "path" ], "type": "object" }, "PlaygroundSample": { "additionalProperties": false, "properties": { "full": { "description": "Needs the full image (FFmpeg or the detection models).", "type": "boolean" }, "kind": { "description": "Gallery group.", "enum": [ "photo", "alpha", "animated", "raw", "document", "video", "audio", "vector", "detection" ], "type": "string" }, "label": { "description": "Description.", "type": "string" }, "name": { "description": "File name (playground://samples/\u003cname\u003e).", "type": "string" }, "source": { "description": "Source string (playground://samples/\u003cname\u003e).", "type": "string" } }, "required": [ "name", "label", "kind", "source" ], "type": "object" }, "PlaygroundSignRequest": { "additionalProperties": false, "properties": { "mount": { "description": "Mount ID from api/meta (the dialect name for its primary mount).", "type": "string" }, "path": { "description": "Escaped path after the mount prefix, starting with /; without the signature segment for imgproxy and thumbor.", "maxLength": 8192, "minLength": 1, "type": "string" }, "pdf_password": { "description": "Plain-text password of a password-protected PDF source: the server encrypts it (XI_ENCRYPTION_KEYS) into a pdf_password option (imgproxy mounts: a pdp segment first in the path; the query mount: a pdf_password parameter) and signs the result. Needs a signed mount; never logged or echoed.", "maxLength": 1024, "type": "string" }, "prefix": { "description": "One of the mount's prefixes; empty means its first prefix.", "maxLength": 512, "type": "string" }, "query": { "description": "Raw query without ?; an existing xi_sig is replaced.", "maxLength": 8192, "type": "string" } }, "required": [ "mount", "path" ], "type": "object" }, "PlaygroundSignResponse": { "additionalProperties": false, "properties": { "scheme": { "description": "The mount's signing scheme.", "enum": [ "imgproxy", "xi_sig", "thumbor", "imgix", "none" ], "type": "string" }, "signed": { "description": "A signature was computed; false when the server has no key for the mount.", "type": "boolean" }, "url": { "description": "Path and query on the public listener (prepend the public base URL).", "type": "string" } }, "required": [ "url", "signed", "scheme" ], "type": "object" }, "PlaygroundSigning": { "additionalProperties": false, "properties": { "mode": { "description": "off: no XI_SIGNING_KEYS; optional: keys set, unsigned URLs fall under the unsigned policy; required: XI_SIGNING_REQUIRED.", "enum": [ "off", "optional", "required" ], "type": "string" }, "unsigned_policy": { "description": "XI_SECURITY_UNSIGNED_POLICY.", "enum": [ "allow", "restricted", "deny" ], "type": "string" } }, "required": [ "mode", "unsigned_policy" ], "type": "object" }, "PlaygroundSource": { "additionalProperties": false, "properties": { "listable": { "description": "api/sources/\u003cname\u003e/list browses this source (fs sources).", "type": "boolean" }, "name": { "description": "Source name.", "type": "string" }, "prefix": { "description": "What the source picker pre-fills when this source is picked (the first syntax up to …).", "type": "string" }, "syntax": { "description": "Source strings this source accepts, the named form first; … is the part to fill in (xi://web/https://…, https://…, local:///…). Configured hosts, buckets and base URLs are never shown.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "type": { "description": "Source type (http, s3, gcs, azure, fs, ftp, sftp).", "type": "string" } }, "required": [ "name", "type", "syntax", "prefix" ], "type": "object" }, "PlaygroundTranslateAlternate": { "additionalProperties": false, "properties": { "prefix": { "description": "The mount prefix.", "type": "string" }, "url": { "description": "Path and query on the public listener, signed like url.", "type": "string" } }, "required": [ "prefix", "url" ], "type": "object" }, "PlaygroundTranslateRequest": { "additionalProperties": false, "properties": { "mount": { "description": "Mount ID from api/meta; with path and query, the URL to translate.", "type": "string" }, "path": { "description": "Escaped path after the mount prefix, without a signature segment.", "maxLength": 8192, "type": "string" }, "query": { "description": "Raw query without ?.", "maxLength": 8192, "type": "string" }, "request": { "additionalProperties": {}, "description": "A canonical transform.Request (as in the translate response), instead of a URL.", "type": "object" } }, "type": "object" }, "PlaygroundTranslateResponse": { "additionalProperties": false, "properties": { "canonical": { "description": "The canonical transform.Request the URL parses into." }, "targets": { "description": "The same transform in every dialect, in a fixed order.", "items": { "$ref": "#/components/schemas/PlaygroundTranslateTarget" }, "type": [ "array", "null" ] } }, "required": [ "canonical", "targets" ], "type": "object" }, "PlaygroundTranslateTarget": { "additionalProperties": false, "properties": { "alternates": { "description": "The same URL on the mount's other prefixes (mounts with several prefixes).", "items": { "$ref": "#/components/schemas/PlaygroundTranslateAlternate" }, "type": [ "array", "null" ] }, "approximated": { "description": "Canonical fields this dialect expresses with a different value.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "dialect": { "description": "Dialect name (query is the imgproxy options in query form).", "type": "string" }, "error": { "description": "Why the transform cannot be written in this dialect at all.", "type": "string" }, "label": { "description": "Human-readable dialect name.", "type": "string" }, "mount": { "description": "Mount ID serving this dialect here; empty when it is not mounted (the URL uses the default prefix).", "type": "string" }, "path": { "description": "Escaped path after the prefix, unsigned.", "type": "string" }, "query": { "description": "Raw query, unsigned.", "type": "string" }, "signed": { "description": "URL carries a signature.", "type": "boolean" }, "unsupported": { "description": "Canonical fields this dialect cannot express (lost in translation).", "items": { "type": "string" }, "type": [ "array", "null" ] }, "url": { "description": "Path and query on the public listener (prepend the base URL), signed when this server holds the mount's key.", "type": "string" } }, "required": [ "dialect", "label" ], "type": "object" }, "PlaygroundUpload": { "additionalProperties": false, "properties": { "content_type": { "description": "Content type sniffed from the bytes.", "type": "string" }, "expires": { "description": "When the upload is dropped.", "format": "date-time", "type": "string" }, "size": { "description": "Bytes stored.", "format": "int64", "type": "integer" }, "source": { "description": "Source string for URLs (playground://uploads/\u003cid\u003e).", "type": "string" } }, "required": [ "source", "size", "content_type", "expires" ], "type": "object" }, "PlaygroundVideoTransform": { "additionalProperties": false, "properties": { "audio_effects": { "description": "Audio volume, loudnorm and fades.", "type": "boolean" }, "codecs": { "description": "Encoders of this build: vp9, av1, h264, hevc (video), aac, opus, mp3, flac, pcm (audio), and waveform when waveform pictures can be drawn.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "containers": { "description": "Output containers this build writes (mp4, webm, m4a, mp3, opus, ogg, flac, wav; png and webp are waveform pictures; m3u8 and mpd are HLS and DASH streams).", "items": { "type": "string" }, "type": [ "array", "null" ] }, "max_fps": { "description": "XI_VIDEO_TRANSFORM_MAX_FPS.", "format": "double", "type": "number" }, "max_output_duration": { "description": "XI_VIDEO_TRANSFORM_MAX_OUTPUT_DURATION in seconds.", "format": "double", "type": "number" }, "max_output_pixels": { "description": "XI_VIDEO_TRANSFORM_MAX_OUTPUT_PIXELS.", "format": "int64", "type": "integer" }, "mp4_video": { "description": "Video codec of an mp4 output with video_codec auto: h264 (gpl image) or av1 (full image).", "type": "string" }, "overlays": { "description": "Image and text overlays (wm, wmu, wmt with overlay_window and overlay_fade).", "type": "boolean" }, "presets": { "description": "Video preset names (XI_VIDEO_TRANSFORM_PRESETS; their options are not shown): pr:\u003cname\u003e in /video, preset=\u003cname\u003e in /q/video, t_\u003cname\u003e on Cloudinary videos, n-\u003cname\u003e on ImageKit videos.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "probe": { "description": "api/probe (a source) and api/probe/result (a result body) describe media files: container, duration, codecs, frame rate, sample rate and channels.", "type": "boolean" }, "timecode": { "description": "Timecode overlays (timecode, FFmpeg drawtext).", "type": "boolean" }, "unsigned_policy": { "description": "XI_VIDEO_TRANSFORM_UNSIGNED_POLICY: deny refuses unsigned video URLs (403) whatever the mount's policy; restricted admits only what their video presets make of them.", "enum": [ "allow", "restricted", "deny" ], "type": "string" } }, "required": [ "unsigned_policy", "codecs", "containers" ], "type": "object" }, "QueryContent": { "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "items": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "type": "array" } ] }, "description": "HTTP QUERY content of the query dialect as JSON: one member per parameter, in document order (later members override earlier ones, like later keys of a query string). Strings are used as they are, numbers as written, booleans as true/false, arrays joined with \",\"; null skips the member. Objects, nested arrays and duplicate names are 400. The canonical query (signed by xi_sig) writes each member as key=value, keys and values percent-encoded except letters, digits and -._~:/,@!$'()* (UTF-8, upper-case hex), joined with \u0026.", "examples": [ { "crop": [ 10, 20, 300, 200 ], "strip_metadata": true, "url": "https://example.com/a.jpg", "w": 300 } ], "properties": { "o": { "description": "imgproxy option path.", "type": "string" }, "sign": { "description": "imaginary signature.", "type": "string" }, "url": { "description": "Source URL or xi://\u003csource\u003e/\u003ckey\u003e.", "type": "string" }, "xi_sig": { "description": "xi signature over the path after the mount, ? and the canonical query without xi_sig.", "type": "string" } }, "required": [ "url" ], "type": "object" } } }, "externalDocs": { "description": "Documentation", "url": "https://github.com/xantiagoma/xtandard-image/blob/main/docs/OPENAPI.md" }, "info": { "description": "Self-hosted image processing proxy. Image URLs follow URL dialects (imgproxy is the default, see https://github.com/xantiagoma/xtandard-image/blob/main/docs/URL-DIALECTS.md); /info reports source metadata. Operations tagged admin are served only on the admin listener (XI_ADMIN_ADDR), never on the public one. The image and /info operations document a path grammar: the processing options and the source contain \"/\", so generated HTTP clients are not expected to call them; their x-xi-* extensions are the contract for URL builders.", "license": { "identifier": "MIT", "name": "MIT" }, "title": "xtandard-image", "version": "dev" }, "openapi": "3.1.0", "paths": { "/_playground/": { "get": { "description": "The playground UI: plain HTML, CSS and JavaScript embedded in the binary, served with Content-Security-Policy default-src 'self', X-Frame-Options DENY and Cache-Control no-store. 404 unless XI_PLAYGROUND_ENABLED.", "operationId": "getPlayground", "responses": { "200": { "content": { "text/html": { "schema": { "description": "HTML page.", "type": "string" } } }, "description": "The page." }, "404": { "description": "The playground is disabled." } }, "servers": [ { "description": "Admin listener (XI_ADMIN_ADDR).", "url": "http://127.0.0.1:9090" } ], "summary": "Playground page", "tags": [ "playground" ], "x-xi-config": "XI_PLAYGROUND_ENABLED; also on the public listener with XI_PLAYGROUND_PUBLIC; path XI_PLAYGROUND_PATH", "x-xi-listener": "admin" } }, "/_playground/api/meta": { "get": { "description": "Enabled dialect mounts with their signing scheme and grammar, the option catalogues (the imgproxy catalogue behind ImgproxyProcessingOptions and the query keys), preset names, named sources (name and type only), the signing mode and the output formats. Never contains key material. Cache-Control no-store.", "operationId": "getPlaygroundMeta", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaygroundMeta" } } }, "description": "Playground metadata." }, "404": { "description": "The playground is disabled." } }, "servers": [ { "description": "Admin listener (XI_ADMIN_ADDR).", "url": "http://127.0.0.1:9090" } ], "summary": "What the playground can build", "tags": [ "playground" ], "x-xi-config": "XI_PLAYGROUND_ENABLED; also on the public listener with XI_PLAYGROUND_PUBLIC; path XI_PLAYGROUND_PATH", "x-xi-listener": "admin" } }, "/_playground/api/probe": { "post": { "description": "Resolves and fetches a source like a request's (allowlists, the SSRF-safe fetcher, XI_VIDEO_TRANSFORM_MAX_INPUT_BYTES; playground:// samples and uploads resolve) and reads its container and stream headers with FFmpeg: container, duration, codecs, size, frame rate, sample rate and channels. Unlike /info it reads audio files. Only with video transformations on (XI_VIDEO_TRANSFORM_ENABLED); two probes at a time, more answer 429. Cross-origin requests are rejected.", "operationId": "postPlaygroundProbe", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaygroundProbeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaygroundMediaInfo" } } }, "description": "The media file's container, duration, average bit rate and streams." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaygroundErrorResponse" } } }, "description": "Bad Request." }, "403": { "description": "Cross-origin request rejected (http.CrossOriginProtection), or a source the allowlists refuse." }, "404": { "description": "The playground is disabled, or video transformations are off (no prober), or the source does not exist." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaygroundErrorResponse" } } }, "description": "Request Entity Too Large." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaygroundErrorResponse" } } }, "description": "Unprocessable Entity." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaygroundErrorResponse" } } }, "description": "Too Many Requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaygroundErrorResponse" } } }, "description": "Internal Server Error." } }, "servers": [ { "description": "Admin listener (XI_ADMIN_ADDR).", "url": "http://127.0.0.1:9090" } ], "summary": "Describe a media source (video mode)", "tags": [ "playground" ], "x-xi-config": "XI_PLAYGROUND_ENABLED; also on the public listener with XI_PLAYGROUND_PUBLIC; path XI_PLAYGROUND_PATH", "x-xi-listener": "admin" } }, "/_playground/api/probe/result": { "post": { "description": "Reads the container and stream headers of the request body (a result the page fetched, at most XI_VIDEO_TRANSFORM_MAX_OUTPUT_BYTES) with FFmpeg, for the Source vs result table. Only with video transformations on; two probes at a time, more answer 429. Cross-origin requests are rejected.", "operationId": "postPlaygroundProbeResult", "requestBody": { "content": { "application/octet-stream": { "schema": { "contentEncoding": "binary", "type": "string" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaygroundMediaInfo" } } }, "description": "The media file's container, duration, average bit rate and streams." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaygroundErrorResponse" } } }, "description": "Bad Request." }, "403": { "description": "Cross-origin request rejected (http.CrossOriginProtection), or a source the allowlists refuse." }, "404": { "description": "The playground is disabled, or video transformations are off (no prober), or the source does not exist." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaygroundErrorResponse" } } }, "description": "Request Entity Too Large." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaygroundErrorResponse" } } }, "description": "Unprocessable Entity." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaygroundErrorResponse" } } }, "description": "Too Many Requests." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaygroundErrorResponse" } } }, "description": "Internal Server Error." } }, "servers": [ { "description": "Admin listener (XI_ADMIN_ADDR).", "url": "http://127.0.0.1:9090" } ], "summary": "Describe a media body (video mode)", "tags": [ "playground" ], "x-xi-config": "XI_PLAYGROUND_ENABLED; also on the public listener with XI_PLAYGROUND_PUBLIC; path XI_PLAYGROUND_PATH", "x-xi-listener": "admin" } }, "/_playground/api/render": { "get": { "description": "Runs the public listener's handler on u (a path and query on the public listener) and returns its response unchanged plus Server-Timing, so the page reads the result and its headers from its own origin. Accept and client hints are forwarded; cookies and credentials are not. Every public-listener check applies.", "operationId": "getPlaygroundRender", "parameters": [ { "description": "Path and query on the public listener, starting with a single /.", "example": "/insecure/rs:fit:300:0/plain/https://example.com/a.jpg", "in": "query", "name": "u", "required": true, "schema": { "maxLength": 16384, "type": "string" } } ], "responses": { "200": { "content": { "image/*": { "schema": { "contentEncoding": "binary", "type": "string" } } }, "description": "The processed image; the format follows `format`, the source extension or Accept negotiation.", "headers": { "Server-Timing": { "description": "Time the public handler took to the first header write.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "406": { "$ref": "#/components/responses/Error406" }, "414": { "$ref": "#/components/responses/Error414" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "501": { "$ref": "#/components/responses/Error501" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" }, "504": { "$ref": "#/components/responses/Error504" } }, "servers": [ { "description": "Admin listener (XI_ADMIN_ADDR).", "url": "http://127.0.0.1:9090" } ], "summary": "Render a public URL in-process", "tags": [ "playground" ], "x-xi-config": "XI_PLAYGROUND_ENABLED; also on the public listener with XI_PLAYGROUND_PUBLIC; path XI_PLAYGROUND_PATH", "x-xi-listener": "admin" } }, "/_playground/api/sign": { "post": { "description": "Builds the URL of a path (and query) on a mount and signs it with the server's key for that mount's scheme (imgproxy path signature, xi_sig or thumbor), so keys never reach the browser. Without a key the URL is returned unsigned (imgproxy insecure/, thumbor unsafe/). Anyone who can call this endpoint can sign URLs: keep the playground private. Cross-origin requests are rejected; the body is JSON of at most 32 KiB.", "operationId": "postPlaygroundSign", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaygroundSignRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaygroundSignResponse" } } }, "description": "The URL, signed with the server's key for the mount when it holds one." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaygroundErrorResponse" } } }, "description": "Bad Request." }, "403": { "description": "Cross-origin request rejected (http.CrossOriginProtection)." }, "404": { "description": "The playground is disabled." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaygroundErrorResponse" } } }, "description": "Request Entity Too Large." }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaygroundErrorResponse" } } }, "description": "Unsupported Media Type." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaygroundErrorResponse" } } }, "description": "Internal Server Error." } }, "servers": [ { "description": "Admin listener (XI_ADMIN_ADDR).", "url": "http://127.0.0.1:9090" } ], "summary": "Sign a URL with the server's keys", "tags": [ "playground" ], "x-xi-config": "XI_PLAYGROUND_ENABLED; also on the public listener with XI_PLAYGROUND_PUBLIC; path XI_PLAYGROUND_PATH", "x-xi-listener": "admin" } }, "/_playground/api/sources/{name}/list": { "get": { "description": "Lists one directory of a named fs source (inside its root and prefix jail, through os.Root): directories first, then files, at most 500 entries, dot files skipped. Other source types and unknown names are 404.", "operationId": "getPlaygroundSourceList", "parameters": [ { "description": "Named source (type fs).", "example": "local", "in": "path", "name": "name", "required": true, "schema": { "type": "string" } }, { "description": "Directory relative to the source; empty for its root. No . or .. segments.", "example": "photos/2026", "in": "query", "name": "prefix", "schema": { "maxLength": 8192, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaygroundListResponse" } } }, "description": "One directory of the source." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaygroundErrorResponse" } } }, "description": "Bad Request." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaygroundErrorResponse" } } }, "description": "Not Found." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaygroundErrorResponse" } } }, "description": "Internal Server Error." } }, "servers": [ { "description": "Admin listener (XI_ADMIN_ADDR).", "url": "http://127.0.0.1:9090" } ], "summary": "Browse an fs source", "tags": [ "playground" ], "x-xi-config": "XI_PLAYGROUND_ENABLED; also on the public listener with XI_PLAYGROUND_PUBLIC; path XI_PLAYGROUND_PATH", "x-xi-listener": "admin" } }, "/_playground/api/translate": { "post": { "description": "Parses a URL of a mount (as for api/sign, without a signature) with that dialect's parser, or takes a canonical transform.Request, and writes the transform in imgproxy (path and query form), imgix, Cloudinary, ImageKit, Cloudflare, wsrv, thumbor, Bunny and AWS SIH. Each URL is parsed back with its dialect's parser and compared with the canonical request: unsupported lists the fields the dialect cannot express, approximated those it writes with a different value. URLs of mounted dialects are signed like api/sign; the others use the dialect's default prefix. Cross-origin requests are rejected.", "operationId": "postPlaygroundTranslate", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaygroundTranslateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaygroundTranslateResponse" } } }, "description": "The canonical request and the same transform in every dialect." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaygroundErrorResponse" } } }, "description": "Bad Request." }, "403": { "description": "Cross-origin request rejected (http.CrossOriginProtection)." }, "404": { "description": "The playground is disabled." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaygroundErrorResponse" } } }, "description": "Request Entity Too Large." }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaygroundErrorResponse" } } }, "description": "Unsupported Media Type." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaygroundErrorResponse" } } }, "description": "Internal Server Error." } }, "servers": [ { "description": "Admin listener (XI_ADMIN_ADDR).", "url": "http://127.0.0.1:9090" } ], "summary": "Translate a URL into every dialect", "tags": [ "playground" ], "x-xi-config": "XI_PLAYGROUND_ENABLED; also on the public listener with XI_PLAYGROUND_PUBLIC; path XI_PLAYGROUND_PATH", "x-xi-listener": "admin" } }, "/_playground/api/upload": { "post": { "description": "Stores the raw request body (at most XI_LIMITS_MAX_SRC_BYTES) in memory for 10 minutes and returns its source, playground://uploads/\u003cid\u003e. The source resolves only for requests made through api/render; the store keeps at most 64 files or 256 MiB and drops the oldest first. Needs XI_PLAYGROUND_UPLOADS (on by default with the playground).", "operationId": "postPlaygroundUpload", "requestBody": { "content": { "application/octet-stream": { "schema": { "contentEncoding": "binary", "type": "string" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaygroundUpload" } } }, "description": "The stored file and its playground:// source." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaygroundErrorResponse" } } }, "description": "Bad Request." }, "403": { "description": "Cross-origin request rejected (http.CrossOriginProtection)." }, "404": { "description": "The playground or its uploads are disabled (XI_PLAYGROUND_UPLOADS)." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaygroundErrorResponse" } } }, "description": "Request Entity Too Large." } }, "servers": [ { "description": "Admin listener (XI_ADMIN_ADDR).", "url": "http://127.0.0.1:9090" } ], "summary": "Upload a file for the playground", "tags": [ "playground" ], "x-xi-config": "XI_PLAYGROUND_ENABLED; also on the public listener with XI_PLAYGROUND_PUBLIC; path XI_PLAYGROUND_PATH", "x-xi-listener": "admin" } }, "/_playground/assets/{version}/{name}": { "get": { "description": "The ES modules (app.js imports the others with relative URLs) and style.css under a content-hash version, with Cache-Control immutable; another version is a 404.", "operationId": "getPlaygroundAsset", "parameters": [ { "description": "Content hash of the assets (from the page).", "example": "0123456789ab", "in": "path", "name": "version", "required": true, "schema": { "type": "string" } }, { "description": "Asset file name: an ES module or the stylesheet (app.js, style.css, ...).", "in": "path", "name": "name", "required": true, "schema": { "pattern": "^[a-z0-9-]+\\.(js|css)$", "type": "string" } } ], "responses": { "200": { "content": { "text/css": { "schema": { "description": "Stylesheet.", "type": "string" } }, "text/javascript": { "schema": { "description": "ES module.", "type": "string" } } }, "description": "The asset." }, "404": { "description": "Unknown asset or stale version, or the playground is disabled." } }, "servers": [ { "description": "Admin listener (XI_ADMIN_ADDR).", "url": "http://127.0.0.1:9090" } ], "summary": "Playground scripts and stylesheet", "tags": [ "playground" ], "x-xi-config": "XI_PLAYGROUND_ENABLED; also on the public listener with XI_PLAYGROUND_PUBLIC; path XI_PLAYGROUND_PATH", "x-xi-listener": "admin" } }, "/config.schema.json": { "get": { "description": "JSON Schema (draft 2020-12) of the YAML/JSON/TOML config file, with a strong ETag; always on, admin listener only (ADR 0007 decision 6). Its $id is the published GitHub Pages copy (externalDocs); this route serves the running binary's version.", "externalDocs": { "description": "Published copy (the schema's $id)", "url": "https://xantiagoma.github.io/xtandard-image/schema/v1/config.schema.json" }, "operationId": "getConfigSchema", "responses": { "200": { "content": { "application/schema+json": { "schema": { "description": "JSON Schema document.", "type": "object" } } }, "description": "The config schema.", "headers": { "ETag": { "description": "Strong entity tag.", "schema": { "type": "string" } } } }, "304": { "description": "Not modified: If-None-Match matched the ETag." } }, "servers": [ { "description": "Admin listener (XI_ADMIN_ADDR).", "url": "http://127.0.0.1:9090" } ], "summary": "Config file JSON Schema", "tags": [ "admin" ], "x-xi-listener": "admin" } }, "/debug/pprof/": { "get": { "description": "net/http/pprof index, only with XI_ADMIN_PPROF=true (404 otherwise).", "operationId": "getPprofIndex", "responses": { "200": { "content": { "text/html": { "schema": { "description": "HTML page.", "type": "string" } } }, "description": "Index page." }, "404": { "description": "pprof is disabled." } }, "servers": [ { "description": "Admin listener (XI_ADMIN_ADDR).", "url": "http://127.0.0.1:9090" } ], "summary": "pprof index", "tags": [ "admin" ], "x-xi-listener": "admin" } }, "/debug/pprof/symbol": { "post": { "description": "Resolves program counters to function names, only with XI_ADMIN_PPROF=true.", "operationId": "postPprofSymbol", "requestBody": { "content": { "text/plain": { "schema": { "description": "Program counters joined by +.", "type": "string" } } } }, "responses": { "200": { "content": { "text/plain": { "schema": { "description": "One symbol per line.", "type": "string" } } }, "description": "Symbols." }, "404": { "description": "pprof is disabled." } }, "servers": [ { "description": "Admin listener (XI_ADMIN_ADDR).", "url": "http://127.0.0.1:9090" } ], "summary": "pprof symbol lookup", "tags": [ "admin" ], "x-xi-listener": "admin" } }, "/debug/pprof/{profile}": { "get": { "description": "net/http/pprof endpoints, only with XI_ADMIN_PPROF=true (404 otherwise): cmdline, profile (CPU, ?seconds=), symbol, trace (?seconds=) and every named profile (goroutine, goroutineleak, heap, allocs, block, mutex, threadcreate).", "operationId": "getPprofProfile", "parameters": [ { "description": "Endpoint or profile name.", "in": "path", "name": "profile", "required": true, "schema": { "examples": [ "heap", "goroutine", "goroutineleak", "profile", "trace", "cmdline", "symbol" ], "type": "string" } } ], "responses": { "200": { "content": { "application/octet-stream": { "schema": { "contentEncoding": "binary", "type": "string" } }, "text/plain": { "schema": { "description": "Text form (?debug=1).", "type": "string" } } }, "description": "Profile data." }, "404": { "description": "pprof is disabled or the profile does not exist." } }, "servers": [ { "description": "Admin listener (XI_ADMIN_ADDR).", "url": "http://127.0.0.1:9090" } ], "summary": "pprof profiles", "tags": [ "admin" ], "x-xi-listener": "admin" } }, "/docs": { "get": { "description": "Scalar API reference over /openapi.json when XI_ADMIN_DOCS=true. The page loads a pinned Scalar build from cdn.jsdelivr.net with Subresource Integrity under a strict Content-Security-Policy; nothing is bundled in the binary.", "operationId": "getDocs", "responses": { "200": { "content": { "text/html": { "schema": { "description": "HTML page.", "type": "string" } } }, "description": "The Scalar page." }, "404": { "content": { "text/plain": { "example": "", "schema": { "description": "Plain-text hint.", "type": "string" } } }, "description": "XI_ADMIN_DOCS is off; the body points at /openapi.json." } }, "servers": [ { "description": "Admin listener (XI_ADMIN_ADDR).", "url": "http://127.0.0.1:9090" } ], "summary": "API reference UI", "tags": [ "admin" ], "x-xi-listener": "admin" } }, "/healthz": { "get": { "description": "200 while the process can serve HTTP; makes no libvips calls. Served on both listeners.", "operationId": "getHealthz", "responses": { "200": { "content": { "text/plain": { "example": "ok\n", "schema": { "description": "Always ok.", "pattern": "^ok\\n$", "type": "string" } } }, "description": "Alive." } }, "servers": [ { "description": "Public listener.", "url": "http://localhost:8080" }, { "description": "Admin listener.", "url": "http://127.0.0.1:9090" } ], "summary": "Liveness", "tags": [ "health" ], "x-xi-listener": "public+admin" } }, "/imagekit/{path}": { "get": { "description": "ImageKit URL under its mount (XI_DIALECTS_IMAGEKIT_ENABLED, prefix /imagekit/ or host-bound): transformations in a tr:… path segment or the tr query parameter.", "externalDocs": { "url": "https://github.com/xantiagoma/xtandard-image/blob/main/docs/URL-DIALECTS.md#7-imagekit" }, "operationId": "getImagekitImage", "parameters": [ { "description": "[tr:\u003ctransformations\u003e/]\u003csource path\u003e, relative to the mount's source.", "example": "tr:w-300,h-200/photos/a.jpg", "in": "path", "name": "path", "required": true, "schema": { "type": "string" } }, { "description": "Transformations, e.g. w-300,h-200:rt-90 (chained with :).", "in": "query", "name": "tr", "schema": { "type": "string" } }, { "description": "Signature: hex HMAC-SHA1 of the URL relative to the endpoint and ik-t.", "in": "query", "name": "ik-s", "schema": { "type": "string" } }, { "description": "Signature expiry, unix seconds.", "in": "query", "name": "ik-t", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "image/*": { "schema": { "contentEncoding": "binary", "type": "string" } } }, "description": "The processed image; the format follows `format`, the source extension or Accept negotiation.", "headers": { "Cache-Control": { "description": "XI_CACHE_HEADERS_* policy, or the URL's expires.", "schema": { "type": "string" } }, "ETag": { "description": "Strong entity tag of the result.", "schema": { "type": "string" } }, "Vary": { "description": "Accept and the client hints that decided the result.", "schema": { "type": "string" } } } }, "304": { "description": "Not modified: If-None-Match matched the ETag." }, "400": { "$ref": "#/components/responses/Error400" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "406": { "$ref": "#/components/responses/Error406" }, "414": { "$ref": "#/components/responses/Error414" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "501": { "$ref": "#/components/responses/Error501" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" }, "504": { "$ref": "#/components/responses/Error504" } }, "summary": "Process an image (ImageKit dialect)", "tags": [ "image" ], "x-xi-dialect": "imagekit", "x-xi-listener": "public" } }, "/imgix/{path}": { "get": { "description": "imgix Rendering API URL under its mount (XI_DIALECTS_IMGIX_ENABLED, prefix /imgix/ or host-bound). Parameters apply by name, the last occurrence wins; any parameter may be base64url-encoded under its name plus 64 (txt64, mark64, ...). Unknown and unsupported parameters are ignored (400 with XI_DIALECTS_STRICT).", "externalDocs": { "url": "https://github.com/xantiagoma/xtandard-image/blob/main/docs/URL-DIALECTS.md#5-imgix" }, "operationId": "getImgixImage", "parameters": [ { "description": "Object key on the mount's source, or a percent-encoded http(s) URL (web proxy source).", "example": "photos/a.jpg", "in": "path", "name": "path", "required": true, "schema": { "type": "string" } }, { "description": "Width: pixels, or a fraction of the source below 1.", "in": "query", "name": "w", "schema": { "type": "string" } }, { "description": "Height: pixels, or a fraction of the source below 1.", "in": "query", "name": "h", "schema": { "type": "string" } }, { "description": "Resize mode (default clip once w or h is set).", "in": "query", "name": "fit", "schema": { "type": "string" } }, { "description": "With fit=crop/min: top, bottom, left, right, faces, focalpoint, entropy, edges or object classes, comma-separated.", "in": "query", "name": "crop", "schema": { "type": "string" } }, { "description": "Aspect ratio w:h (with fit=crop).", "in": "query", "name": "ar", "schema": { "type": "string" } }, { "description": "Device pixel ratio (0 \u003c dpr \u003c= 10).", "in": "query", "name": "dpr", "schema": { "type": "string" } }, { "description": "Maximum width.", "in": "query", "name": "max-w", "schema": { "type": "string" } }, { "description": "Maximum height.", "in": "query", "name": "max-h", "schema": { "type": "string" } }, { "description": "Minimum width.", "in": "query", "name": "min-w", "schema": { "type": "string" } }, { "description": "Minimum height.", "in": "query", "name": "min-h", "schema": { "type": "string" } }, { "description": "Source crop x,y,w,h before resizing (pixels, or fractions below 1).", "in": "query", "name": "rect", "schema": { "type": "string" } }, { "description": "Focal point x, 0..1 (crop=focalpoint).", "in": "query", "name": "fp-x", "schema": { "type": "string" } }, { "description": "Focal point y, 0..1 (crop=focalpoint).", "in": "query", "name": "fp-y", "schema": { "type": "string" } }, { "description": "With fit=fill/fillmax: how the extra space is filled.", "in": "query", "name": "fill", "schema": { "type": "string" } }, { "description": "Fill colour for fit=fill.", "in": "query", "name": "fill-color", "schema": { "type": "string" } }, { "description": "Padding around the face for fit=facearea.", "in": "query", "name": "facepad", "schema": { "type": "string" } }, { "description": "1-based face for fit=facearea.", "in": "query", "name": "faceindex", "schema": { "type": "string" } }, { "description": "Output format; json answers image info.", "in": "query", "name": "fm", "schema": { "type": "string" } }, { "description": "format (negotiate from Accept) and/or compress (quality 45, strip metadata), comma-separated.", "in": "query", "name": "auto", "schema": { "type": "string" } }, { "description": "Quality 0..100.", "in": "query", "name": "q", "schema": { "type": "string" } }, { "description": "Lossless encoding.", "in": "query", "name": "lossless", "schema": { "type": "string" } }, { "description": "Progressive JPEG.", "in": "query", "name": "jpg-progressive", "schema": { "type": "string" } }, { "description": "Chroma subsampling.", "in": "query", "name": "chromasub", "schema": { "type": "string" } }, { "description": "Colour space.", "in": "query", "name": "cs", "schema": { "type": "string" } }, { "description": "Output resolution metadata.", "in": "query", "name": "dpi", "schema": { "type": "string" } }, { "description": "Download as an attachment with this file name.", "in": "query", "name": "dl", "schema": { "type": "string" } }, { "description": "Client hints to honour: Width, DPR, Save-Data.", "in": "query", "name": "ch", "schema": { "type": "string" } }, { "description": "EXIF orientation override.", "in": "query", "name": "orient", "schema": { "type": "string" } }, { "description": "Counter-clockwise rotation, 0..359 degrees.", "in": "query", "name": "rot", "schema": { "type": "string" } }, { "description": "Mirror.", "in": "query", "name": "flip", "schema": { "type": "string" } }, { "description": "Brightness -100..100.", "in": "query", "name": "bri", "schema": { "type": "string" } }, { "description": "Contrast -100..100.", "in": "query", "name": "con", "schema": { "type": "string" } }, { "description": "Exposure -100..100.", "in": "query", "name": "exp", "schema": { "type": "string" } }, { "description": "Gamma -100..100.", "in": "query", "name": "gam", "schema": { "type": "string" } }, { "description": "Saturation -100..100.", "in": "query", "name": "sat", "schema": { "type": "string" } }, { "description": "Hue shift in degrees.", "in": "query", "name": "hue", "schema": { "type": "string" } }, { "description": "Sharpen 0..100.", "in": "query", "name": "sharp", "schema": { "type": "string" } }, { "description": "Unsharp mask amount -100..100.", "in": "query", "name": "usm", "schema": { "type": "string" } }, { "description": "Unsharp mask radius (default 2.5).", "in": "query", "name": "usmrad", "schema": { "type": "string" } }, { "description": "Blur 0..2000.", "in": "query", "name": "blur", "schema": { "type": "string" } }, { "description": "Pixelate 0..100.", "in": "query", "name": "px", "schema": { "type": "string" } }, { "description": "Sepia 0..100.", "in": "query", "name": "sepia", "schema": { "type": "string" } }, { "description": "Monochrome tint (alpha = intensity).", "in": "query", "name": "monochrome", "schema": { "type": "string" } }, { "description": "Two colours: shadow,highlight.", "in": "query", "name": "duotone", "schema": { "type": "string" } }, { "description": "Duotone intensity 0..100.", "in": "query", "name": "duotone-alpha", "schema": { "type": "string" } }, { "description": "Invert colours.", "in": "query", "name": "invert", "schema": { "type": "string" } }, { "description": "Blur detected faces 0..100.", "in": "query", "name": "face-blur", "schema": { "type": "string" } }, { "description": "Pixelate detected faces 0..100.", "in": "query", "name": "face-pixel", "schema": { "type": "string" } }, { "description": "Background colour.", "in": "query", "name": "bg", "schema": { "type": "string" } }, { "description": "Padding on every side.", "in": "query", "name": "pad", "schema": { "type": "string" } }, { "description": "Border width,color.", "in": "query", "name": "border", "schema": { "type": "string" } }, { "description": "Corner radius r or tl,tr,br,bl.", "in": "query", "name": "border-radius", "schema": { "type": "string" } }, { "description": "Trim borders.", "in": "query", "name": "trim", "schema": { "type": "string" } }, { "description": "Trim colour (trim=color).", "in": "query", "name": "trim-color", "schema": { "type": "string" } }, { "description": "Trim tolerance (trim=color).", "in": "query", "name": "trim-tol", "schema": { "type": "string" } }, { "description": "Trim mean difference (trim=auto, default 11).", "in": "query", "name": "trim-md", "schema": { "type": "string" } }, { "description": "Mask shape.", "in": "query", "name": "mask", "schema": { "type": "string" } }, { "description": "Background outside an ellipse mask.", "in": "query", "name": "mask-bg", "schema": { "type": "string" } }, { "description": "Corner radius for mask=corners.", "in": "query", "name": "corner-radius", "schema": { "type": "string" } }, { "description": "1-based page of a PDF.", "in": "query", "name": "page", "schema": { "type": "string" } }, { "description": "1-based frame of an animation.", "in": "query", "name": "frame", "schema": { "type": "string" } }, { "description": "Watermark image: http(s) URL or a path on the mount's source.", "in": "query", "name": "mark", "schema": { "type": "string" } }, { "description": "Watermark alignment: top, middle, bottom, left, center, right.", "in": "query", "name": "mark-align", "schema": { "type": "string" } }, { "description": "Watermark opacity 0..100.", "in": "query", "name": "mark-alpha", "schema": { "type": "string" } }, { "description": "Watermark padding (default 5).", "in": "query", "name": "mark-pad", "schema": { "type": "string" } }, { "description": "Watermark size as a percentage of the image.", "in": "query", "name": "mark-scale", "schema": { "type": "string" } }, { "description": "Watermark width.", "in": "query", "name": "mark-w", "schema": { "type": "string" } }, { "description": "Watermark height.", "in": "query", "name": "mark-h", "schema": { "type": "string" } }, { "description": "Watermark x from the left edge.", "in": "query", "name": "mark-x", "schema": { "type": "string" } }, { "description": "Watermark y from the top edge.", "in": "query", "name": "mark-y", "schema": { "type": "string" } }, { "description": "Repeat the watermark.", "in": "query", "name": "mark-tile", "schema": { "type": "string" } }, { "description": "Watermark rotation, counter-clockwise degrees.", "in": "query", "name": "mark-rot", "schema": { "type": "string" } }, { "description": "http(s) URL prefix for mark paths.", "in": "query", "name": "mark-base", "schema": { "type": "string" } }, { "description": "Text watermark (plain text).", "in": "query", "name": "txt", "schema": { "type": "string" } }, { "description": "Font family and style, comma-separated.", "in": "query", "name": "txt-font", "schema": { "type": "string" } }, { "description": "Text size (default 12).", "in": "query", "name": "txt-size", "schema": { "type": "string" } }, { "description": "Text colour.", "in": "query", "name": "txt-color", "schema": { "type": "string" } }, { "description": "Text alignment: top, middle, bottom, left, center, right.", "in": "query", "name": "txt-align", "schema": { "type": "string" } }, { "description": "Text padding (default 10).", "in": "query", "name": "txt-pad", "schema": { "type": "string" } }, { "description": "Text shadow 0..10.", "in": "query", "name": "txt-shad", "schema": { "type": "string" } }, { "description": "Text wrap width.", "in": "query", "name": "txt-width", "schema": { "type": "string" } }, { "description": "Text x from the left edge.", "in": "query", "name": "txt-x", "schema": { "type": "string" } }, { "description": "Text y from the top edge.", "in": "query", "name": "txt-y", "schema": { "type": "string" } }, { "description": "Expiry, unix seconds; 404 once passed (checked after the signature).", "in": "query", "name": "expires", "schema": { "type": "string" } }, { "description": "Signature: hex MD5 of the mount's token, the path and ? plus the query without s.", "in": "query", "name": "s", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "image/*": { "schema": { "contentEncoding": "binary", "type": "string" } } }, "description": "The processed image; the format follows `format`, the source extension or Accept negotiation.", "headers": { "Cache-Control": { "description": "XI_CACHE_HEADERS_* policy, or the URL's expires.", "schema": { "type": "string" } }, "ETag": { "description": "Strong entity tag of the result.", "schema": { "type": "string" } }, "Vary": { "description": "Accept and the client hints that decided the result.", "schema": { "type": "string" } } } }, "304": { "description": "Not modified: If-None-Match matched the ETag." }, "400": { "$ref": "#/components/responses/Error400" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "406": { "$ref": "#/components/responses/Error406" }, "414": { "$ref": "#/components/responses/Error414" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "501": { "$ref": "#/components/responses/Error501" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" }, "504": { "$ref": "#/components/responses/Error504" } }, "summary": "Process an image (imgix dialect)", "tags": [ "image" ], "x-xi-dialect": "imgix", "x-xi-listener": "public" } }, "/info/{signature}/{options}/{source}": { "get": { "description": "Fetches the source and reports its metadata without processing it. {options} is zero or more info options separated by / (s:1/f:1/d:1/bh:4:3), typed by the ImgproxyInfoOptions schema; the signature covers the path after it, as for image URLs. Grammar: x-xi-path-grammar.", "externalDocs": { "url": "https://github.com/xantiagoma/xtandard-image/blob/main/docs/URL-DIALECTS.md#33-info-options" }, "operationId": "getImgproxyInfo", "parameters": [ { "description": "URL signature, or any value (conventionally unsafe) when signing is off.", "example": "unsafe", "in": "path", "name": "signature", "required": true, "schema": { "type": "string" } }, { "description": "Info options joined by /, each name:arg:arg (ImgproxyInfoOptions).", "example": "s:1/f:1/d:1", "in": "path", "name": "options", "required": true, "schema": { "type": "string" }, "x-xi-options-schema": { "$ref": "#/components/schemas/ImgproxyInfoOptions" } }, { "description": "The source: plain/\u003cpercent-encoded URL\u003e[@ext], \u003curl-safe base64 URL\u003e[.ext] (may be split with /) or enc/\u003cAES-CBC token\u003e[.ext]. Schemes: http(s), s3, gs, abs, local, ftp, sftp, xi://\u003csource\u003e/.", "example": "plain/https://example.com/a.jpg@webp", "in": "path", "name": "source", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InfoResponse" } } }, "description": "Source metadata.", "headers": { "ETag": { "description": "Strong entity tag.", "schema": { "type": "string" } } } }, "304": { "description": "Not modified: If-None-Match matched the ETag." }, "400": { "$ref": "#/components/responses/Error400" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "406": { "$ref": "#/components/responses/Error406" }, "414": { "$ref": "#/components/responses/Error414" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "501": { "$ref": "#/components/responses/Error501" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" }, "504": { "$ref": "#/components/responses/Error504" } }, "summary": "Source metadata (imgproxy /info)", "tags": [ "info" ], "x-xi-dialect": "imgproxy", "x-xi-info-options": { "$ref": "#/components/schemas/ImgproxyInfoOptions" }, "x-xi-listener": "public", "x-xi-path-grammar": "/%signature/%options.../plain/%source_url[@%extension]\n/%signature/%options.../%base64url_source_url[.%extension] (may be split with \"/\")\n/%signature/%options.../enc/%aes_cbc_source[.%extension] (may be split with \"/\")\n/info/%signature/%info_options.../{plain/…|%base64…|enc/…}\n/video/%signature/%video_options.../{plain/…[@%container]|%base64…|enc/…}\n\noption = name \":\" arg *(\":\" arg) ; separator configurable (XI_DIALECTS_IMGPROXY_ARGUMENTS_SEPARATOR)\npipeline = option *(\"/\" option)\npipelines = pipeline *(\"/-/\" pipeline) ; chained pipelines\nbool = \"1\" | \"t\" | \"true\" | \"0\" | \"f\" | \"false\"", "x-xi-signing": { "description": "HMAC-SHA256(key, salt ‖ path after the signature, starting with /), url-safe base64 without padding, optionally truncated to XI_SIGNING_SIZE bytes; any value (conventionally unsafe) when signing is off.", "docs": "https://docs.imgproxy.net/usage/signing_url", "scheme": "imgproxy" } } }, "/metrics": { "get": { "description": "client_golang exposition of the private registry (docs/ARCHITECTURE.md §13); OpenMetrics when negotiated.", "operationId": "getMetrics", "responses": { "200": { "content": { "application/openmetrics-text": { "schema": { "description": "OpenMetrics text format.", "type": "string" } }, "text/plain": { "schema": { "description": "Prometheus text format.", "type": "string" } } }, "description": "Metrics." } }, "servers": [ { "description": "Admin listener (XI_ADMIN_ADDR).", "url": "http://127.0.0.1:9090" } ], "summary": "Prometheus metrics", "tags": [ "admin" ], "x-xi-listener": "admin" } }, "/openapi.json": { "get": { "description": "The embedded document with a strong ETag; always on, admin listener only.", "operationId": "getOpenAPI", "responses": { "200": { "content": { "application/json": { "schema": { "description": "OpenAPI 3.1 document.", "type": "object" } } }, "description": "The OpenAPI 3.1 document.", "headers": { "ETag": { "description": "Strong entity tag.", "schema": { "type": "string" } } } }, "304": { "description": "Not modified: If-None-Match matched the ETag." } }, "servers": [ { "description": "Admin listener (XI_ADMIN_ADDR).", "url": "http://127.0.0.1:9090" } ], "summary": "This OpenAPI document", "tags": [ "admin" ], "x-xi-listener": "admin" } }, "/q": { "get": { "description": "Native query dialect, mounted at /q/ when XI_DIALECTS_QUERY_ENABLED=true. Keys apply in query order through the imgproxy option parser, so later keys override earlier ones. The same request may be sent with the HTTP QUERY method (RFC 10008; XI_SERVER_QUERY_METHOD, on by default), its parameters in the content instead of the URL: OpenAPI 3.1 has no QUERY operation, so x-xi-query-method describes it.", "externalDocs": { "url": "https://github.com/xantiagoma/xtandard-image/blob/main/docs/URL-DIALECTS.md#4-query-dialect-native--imaginary" }, "operationId": "getQueryImage", "parameters": [ { "description": "Source URL or xi://\u003csource\u003e/\u003ckey\u003e (required).", "example": "https://example.com/a.jpg", "in": "query", "name": "url", "required": true, "schema": { "type": "string" } }, { "description": "Width in pixels.", "in": "query", "name": "width", "schema": { "type": "string" } }, { "description": "Alias of width.", "in": "query", "name": "w", "schema": { "type": "string" } }, { "description": "Height in pixels.", "in": "query", "name": "height", "schema": { "type": "string" } }, { "description": "Alias of height.", "in": "query", "name": "h", "schema": { "type": "string" } }, { "description": "fit, contain, inside, fill, cover, fill-down, force, stretch, outside or auto.", "in": "query", "name": "fit", "schema": { "type": "string" } }, { "description": "Compass word, smart, entropy or fp:x:y.", "in": "query", "name": "gravity", "schema": { "type": "string" } }, { "description": "Alias of gravity.", "in": "query", "name": "g", "schema": { "type": "string" } }, { "description": "w,h or w,h,x,y.", "in": "query", "name": "crop", "schema": { "type": "string" } }, { "description": "Device pixel ratio.", "in": "query", "name": "dpr", "schema": { "type": "string" } }, { "description": "Allow upscaling (bool).", "in": "query", "name": "enlarge", "schema": { "type": "string" } }, { "description": "Output format.", "in": "query", "name": "format", "schema": { "type": "string" } }, { "description": "Alias of format.", "in": "query", "name": "f", "schema": { "type": "string" } }, { "description": "0..100.", "in": "query", "name": "quality", "schema": { "type": "string" } }, { "description": "Alias of quality.", "in": "query", "name": "q", "schema": { "type": "string" } }, { "description": "Lossless encoding (bool).", "in": "query", "name": "lossless", "schema": { "type": "string" } }, { "description": "Progressive/interlaced encoding (bool).", "in": "query", "name": "progressive", "schema": { "type": "string" } }, { "description": "Gaussian sigma.", "in": "query", "name": "blur", "schema": { "type": "string" } }, { "description": "Sharpen sigma.", "in": "query", "name": "sharpen", "schema": { "type": "string" } }, { "description": "Block size.", "in": "query", "name": "pixelate", "schema": { "type": "string" } }, { "description": "Multiple of 90.", "in": "query", "name": "rotate", "schema": { "type": "string" } }, { "description": "Alias of rotate.", "in": "query", "name": "rot", "schema": { "type": "string" } }, { "description": "h, v or hv.", "in": "query", "name": "flip", "schema": { "type": "string" } }, { "description": "Background: hex or r,g,b.", "in": "query", "name": "bg", "schema": { "type": "string" } }, { "description": "Strip metadata (bool).", "in": "query", "name": "strip", "schema": { "type": "string" } }, { "description": "Trim threshold (and colour, ...).", "in": "query", "name": "trim", "schema": { "type": "string" } }, { "description": "Padding, CSS shorthand with , or :.", "in": "query", "name": "pad", "schema": { "type": "string" } }, { "description": "Preset names.", "in": "query", "name": "preset", "schema": { "type": "string" } }, { "description": "First page.", "in": "query", "name": "page", "schema": { "type": "string" } }, { "description": "Number of pages or frames to load.", "in": "query", "name": "pages", "schema": { "type": "string" } }, { "description": "Second of a video source to take the frame from.", "in": "query", "name": "video_thumbnail_second", "schema": { "type": "string" } }, { "description": "Alias of video_thumbnail_second.", "in": "query", "name": "vts", "schema": { "type": "string" } }, { "description": "Take the frame from the keyframe before the second (bool).", "in": "query", "name": "video_thumbnail_keyframes", "schema": { "type": "string" } }, { "description": "Alias of video_thumbnail_keyframes.", "in": "query", "name": "vtk", "schema": { "type": "string" } }, { "description": "Cache buster.", "in": "query", "name": "cb", "schema": { "type": "string" } }, { "description": "Content-Disposition file name.", "in": "query", "name": "filename", "schema": { "type": "string" } }, { "description": "Download as attachment (bool).", "in": "query", "name": "attachment", "schema": { "type": "string" } }, { "description": "Unix expiry.", "in": "query", "name": "expires", "schema": { "type": "string" } }, { "description": "Encrypted password of a password-protected PDF (the enc/ token format); signed URLs only.", "in": "query", "name": "pdf_password", "schema": { "type": "string" } }, { "description": "Alias of pdf_password.", "in": "query", "name": "pdp", "schema": { "type": "string" } }, { "description": "An imgproxy option path (rs:fill:300:200/g:sm), typed by ImgproxyProcessingOptions; makes the dialect complete.", "in": "query", "name": "o", "schema": { "type": "string" }, "x-xi-options-schema": { "$ref": "#/components/schemas/ImgproxyProcessingOptions" } }, { "description": "imaginary signature over the path and the sorted query.", "in": "query", "name": "sign", "schema": { "type": "string" } }, { "description": "xi signature (imgproxy keys) over the path and the query.", "in": "query", "name": "xi_sig", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "image/*": { "schema": { "contentEncoding": "binary", "type": "string" } } }, "description": "The processed image; the format follows `format`, the source extension or Accept negotiation.", "headers": { "Cache-Control": { "description": "XI_CACHE_HEADERS_* policy, or the URL's expires.", "schema": { "type": "string" } }, "ETag": { "description": "Strong entity tag of the result.", "schema": { "type": "string" } }, "Vary": { "description": "Accept and the client hints that decided the result.", "schema": { "type": "string" } } } }, "304": { "description": "Not modified: If-None-Match matched the ETag." }, "400": { "$ref": "#/components/responses/Error400" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "406": { "$ref": "#/components/responses/Error406" }, "414": { "$ref": "#/components/responses/Error414" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "501": { "$ref": "#/components/responses/Error501" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" }, "504": { "$ref": "#/components/responses/Error504" } }, "summary": "Process an image (query dialect)", "tags": [ "image" ], "x-xi-dialect": "query", "x-xi-listener": "public", "x-xi-query-method": { "config": "XI_SERVER_QUERY_METHOD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryContent" } }, "application/x-www-form-urlencoded": { "schema": { "description": "Exactly the query string of the equivalent GET URL (same keys, order and escaping).", "example": "url=https%3A%2F%2Fexample.com%2Fa.jpg\u0026w=300\u0026f=webp", "type": "string" } } }, "description": "The parameters of the GET operation travel in the request content; the URL has no query (a query is 400). Signing (xi_sig or sign as a parameter in the content, over the same message as the GET URL), the unsigned policy, limits, conditional requests and the result cache entry are those of the equivalent GET request.", "docs": "https://github.com/xantiagoma/xtandard-image/blob/main/docs/URL-DIALECTS.md#44-http-query", "errors": { "400": "Malformed content, or a URL with a query.", "405": "XI_SERVER_QUERY_METHOD=false, or an endpoint of another dialect (Allow lists the methods).", "413": "Content over XI_SERVER_QUERY_MAX_BODY_BYTES.", "415": "Missing or unsupported Content-Type, a charset other than UTF-8, or a Content-Encoding." }, "method": "QUERY", "response_headers": { "Accept-Query": "The media types above, as a Structured Field list; also on GET, HEAD and 405 responses of these endpoints.", "Location": "On 2xx: the equivalent GET URL when it fits XI_SERVER_QUERY_LOCATION_MAX_LENGTH and carries no pdf_password.", "Vary": "Adds Content-Type." }, "rfc": "https://www.rfc-editor.org/rfc/rfc10008" } } }, "/q/video": { "get": { "description": "The /video options as query keys (aliases too), in query order, mounted at /q/ when XI_DIALECTS_QUERY_ENABLED=true; fit, gravity, crop and flip also take the native spellings. The same request may be sent with the HTTP QUERY method (RFC 10008; XI_SERVER_QUERY_METHOD, on by default), its parameters in the content instead of the URL: OpenAPI 3.1 has no QUERY operation, so x-xi-query-method describes it.", "externalDocs": { "url": "https://github.com/xantiagoma/xtandard-image/blob/main/docs/URL-DIALECTS.md#4-query-dialect-native--imaginary" }, "operationId": "getQueryVideo", "parameters": [ { "description": "Source URL or xi://\u003csource\u003e/\u003ckey\u003e.", "example": "https://example.com/clip.mp4", "in": "query", "name": "url", "required": true, "schema": { "type": "string" } }, { "description": "Start the output at this time of the source (exact, from the keyframe before it). Arguments joined by , or : (seconds).", "in": "query", "name": "start", "schema": { "type": "string" } }, { "description": "End the output at this time of the source (exclusive with duration). Arguments joined by , or : (seconds).", "in": "query", "name": "end", "schema": { "type": "string" } }, { "description": "Length of the output from start (exclusive with end). Arguments joined by , or : (seconds).", "in": "query", "name": "duration", "schema": { "type": "string" } }, { "description": "Resize like imgproxy: fit (scale-down, or contain with enlarge; extend pads), fill and fill-down (cover, cropped by gravity), force (stretch). Arguments joined by , or : (type:w:h:enlarge:extend).", "in": "query", "name": "resize", "schema": { "type": "string" } }, { "description": "Resize without the type. Arguments joined by , or : (w:h:enlarge:extend).", "in": "query", "name": "size", "schema": { "type": "string" } }, { "description": "Resizing type (auto is not available for video). Arguments joined by , or : (fit, fill, fill-down, force).", "in": "query", "name": "resizing_type", "schema": { "type": "string" } }, { "description": "Output width (rounded down to even). Arguments joined by , or : (px).", "in": "query", "name": "width", "schema": { "type": "string" } }, { "description": "Output height (rounded down to even). Arguments joined by , or : (px).", "in": "query", "name": "height", "schema": { "type": "string" } }, { "description": "Let fit enlarge a smaller source. Arguments joined by , or : (bool).", "in": "query", "name": "enlarge", "schema": { "type": "string" } }, { "description": "Pad a fit to the whole box with the background colour. Arguments joined by , or : (bool).", "in": "query", "name": "extend", "schema": { "type": "string" } }, { "description": "Anchor of fill crops, pads and crops (a compass point; the pixel offsets move crops). Arguments joined by , or : (type:x:y).", "in": "query", "name": "gravity", "schema": { "type": "string" } }, { "description": "Crop a rectangle (pixels) of the rotated frame before the resize. Arguments joined by , or : (w:h:gravity).", "in": "query", "name": "crop", "schema": { "type": "string" } }, { "description": "Rotate clockwise after the display matrix. Arguments joined by , or : (multiple of 90).", "in": "query", "name": "rotate", "schema": { "type": "string" } }, { "description": "Mirror after the rotation. Arguments joined by , or : (h:v).", "in": "query", "name": "flip", "schema": { "type": "string" } }, { "description": "Colour of the bars of extend. Arguments joined by , or : (hex).", "in": "query", "name": "background", "schema": { "type": "string" } }, { "description": "Output frame rate (capped by XI_VIDEO_TRANSFORM_MAX_FPS). Arguments joined by , or : (rate).", "in": "query", "name": "fps", "schema": { "type": "string" } }, { "description": "Output container (the source extension sets it too); png and webp are waveform pictures, m3u8 and mpd streams (WP-126). Arguments joined by , or : (mp4, webm, m4a, mp3, opus, ogg, flac, wav, png, webp, m3u8, mpd).", "in": "query", "name": "format", "schema": { "type": "string" } }, { "description": "Video codec (h264 and hevc need the gpl image). Arguments joined by , or : (auto, h264, av1, vp9, hevc).", "in": "query", "name": "video_codec", "schema": { "type": "string" } }, { "description": "Audio codec (must suit the container). Arguments joined by , or : (auto, aac, opus, mp3, flac, pcm).", "in": "query", "name": "audio_codec", "schema": { "type": "string" } }, { "description": "Video quality, mapped onto the codec's CRF scale. Arguments joined by , or : (1..100).", "in": "query", "name": "quality", "schema": { "type": "string" } }, { "description": "Constant rate factor (wins over quality). Arguments joined by , or : (0..63).", "in": "query", "name": "crf", "schema": { "type": "string" } }, { "description": "Cap the video bit rate (50k..200M). Arguments joined by , or : (bit/s (k, M)).", "in": "query", "name": "video_bitrate", "schema": { "type": "string" } }, { "description": "Time between keyframes (GOP length, 0.1..60 s). Arguments joined by , or : (seconds).", "in": "query", "name": "keyframe_interval", "schema": { "type": "string" } }, { "description": "Drop the audio stream. Arguments joined by , or : (bool).", "in": "query", "name": "mute", "schema": { "type": "string" } }, { "description": "Audio bit rate (8k..512k; ignored by flac and wav). Arguments joined by , or : (bit/s (k)).", "in": "query", "name": "audio_bitrate", "schema": { "type": "string" } }, { "description": "Output sample rate (the codec must support it: Opus 8/12/16/24/48 kHz). Arguments joined by , or : (Hz).", "in": "query", "name": "sample_rate", "schema": { "type": "string" } }, { "description": "Downmix to mono or stereo. Arguments joined by , or : (1 or 2).", "in": "query", "name": "audio_channels", "schema": { "type": "string" } }, { "description": "Change the audio level (-60 dB..+20 dB). Arguments joined by , or : (factor or NdB).", "in": "query", "name": "volume", "schema": { "type": "string" } }, { "description": "EBU R128 loudness normalisation (single-pass loudnorm). Arguments joined by , or : (enabled:I:TP:LRA).", "in": "query", "name": "loudnorm", "schema": { "type": "string" } }, { "description": "Fade in from black and silence, and out to them (seconds). Arguments joined by , or : (in:out).", "in": "query", "name": "fade", "schema": { "type": "string" } }, { "description": "Render the audio as a width × height (default 1024×256) PNG or WebP picture. Arguments joined by , or : (enabled:color:background:split).", "in": "query", "name": "waveform", "schema": { "type": "string" } }, { "description": "Show the watermark overlay (wm, wmu, wmt) from start to end seconds of the output. Arguments joined by , or : (start:end).", "in": "query", "name": "overlay_window", "schema": { "type": "string" } }, { "description": "Fade the watermark overlay in and out (seconds, within its window). Arguments joined by , or : (in:out).", "in": "query", "name": "overlay_fade", "schema": { "type": "string" } }, { "description": "Deliver an HLS or DASH stream (as the m3u8 or mpd extension does) with these renditions (at most 8; none: the configured ladder). Rungs above the source are dropped. Arguments joined by , or : (protocol:height…).", "in": "query", "name": "stream", "schema": { "type": "string" } }, { "description": "Length of a stream's segments (1..30 s). Arguments joined by , or : (seconds).", "in": "query", "name": "segment_duration", "schema": { "type": "string" } }, { "description": "Container of a stream's segments: fmp4 (CMAF, HLS 7 and DASH) or ts (MPEG-TS for older HLS players: HLS only, H.264 and AAC muxed in each segment; images with libx264 only). Arguments joined by , or : (format).", "in": "query", "name": "segment_format", "schema": { "type": "string" } }, { "description": "Draw the output's running time (FFmpeg drawtext with a fixed expansion). Arguments joined by , or : (format:position:x:y:size:color:opacity).", "in": "query", "name": "timecode", "schema": { "type": "string" } }, { "description": "Expand video presets (XI_VIDEO_TRANSFORM_PRESETS) in place. Arguments joined by , or : (names…).", "in": "query", "name": "preset", "schema": { "type": "string" } }, { "description": "A /video option path (rs:fill:640:360/vd:5).", "in": "query", "name": "o", "schema": { "type": "string" }, "x-xi-options-schema": { "$ref": "#/components/schemas/ImgproxyVideoOptions" } }, { "description": "Signature over \"/video\" + the query (sign.XIMessage).", "in": "query", "name": "xi_sig", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "audio/*": { "schema": { "contentEncoding": "binary", "type": "string" } }, "image/png": { "schema": { "contentEncoding": "binary", "type": "string" } }, "image/webp": { "schema": { "contentEncoding": "binary", "type": "string" } }, "video/*": { "schema": { "contentEncoding": "binary", "type": "string" } } }, "description": "The transcoded file: video/mp4, video/webm, audio/mp4, audio/mpeg, audio/ogg, audio/flac, audio/wav, or image/png and image/webp for a waveform picture.", "headers": { "Accept-Ranges": { "description": "bytes", "schema": { "type": "string" } }, "Cache-Control": { "description": "XI_CACHE_HEADERS_* policy, or the URL's expires.", "schema": { "type": "string" } }, "ETag": { "description": "Strong entity tag (also the If-Range validator).", "schema": { "type": "string" } } } }, "206": { "description": "Partial content: the Range of the file (multipart/byteranges for several ranges)." }, "304": { "description": "Not modified: If-None-Match matched the ETag." }, "400": { "$ref": "#/components/responses/Error400" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "406": { "$ref": "#/components/responses/Error406" }, "414": { "$ref": "#/components/responses/Error414" }, "416": { "description": "Range not satisfiable." }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "501": { "$ref": "#/components/responses/Error501" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" }, "504": { "$ref": "#/components/responses/Error504" } }, "summary": "Transform a video (query dialect)", "tags": [ "video" ], "x-xi-dialect": "query", "x-xi-listener": "public", "x-xi-query-method": { "config": "XI_SERVER_QUERY_METHOD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryContent" } }, "application/x-www-form-urlencoded": { "schema": { "description": "Exactly the query string of the equivalent GET URL (same keys, order and escaping).", "example": "url=https%3A%2F%2Fexample.com%2Fa.jpg\u0026w=300\u0026f=webp", "type": "string" } } }, "description": "The parameters of the GET operation travel in the request content; the URL has no query (a query is 400). Signing (xi_sig or sign as a parameter in the content, over the same message as the GET URL), the unsigned policy, limits, conditional requests and the result cache entry are those of the equivalent GET request.", "docs": "https://github.com/xantiagoma/xtandard-image/blob/main/docs/URL-DIALECTS.md#44-http-query", "errors": { "400": "Malformed content, or a URL with a query.", "405": "XI_SERVER_QUERY_METHOD=false, or an endpoint of another dialect (Allow lists the methods).", "413": "Content over XI_SERVER_QUERY_MAX_BODY_BYTES.", "415": "Missing or unsupported Content-Type, a charset other than UTF-8, or a Content-Encoding." }, "method": "QUERY", "response_headers": { "Accept-Query": "The media types above, as a Structured Field list; also on GET, HEAD and 405 responses of these endpoints.", "Location": "On 2xx: the equivalent GET URL when it fits XI_SERVER_QUERY_LOCATION_MAX_LENGTH and carries no pdf_password.", "Vary": "Adds Content-Type." }, "rfc": "https://www.rfc-editor.org/rfc/rfc10008" } } }, "/q/{endpoint}": { "get": { "description": "imaginary's GET API under the query dialect mount. POST uploads and the file parameter are not supported. The same request may be sent with the HTTP QUERY method (RFC 10008; XI_SERVER_QUERY_METHOD, on by default), its parameters in the content instead of the URL: OpenAPI 3.1 has no QUERY operation, so x-xi-query-method describes it.", "externalDocs": { "url": "https://github.com/xantiagoma/xtandard-image/blob/main/docs/URL-DIALECTS.md#4-query-dialect-native--imaginary" }, "operationId": "getImaginaryImage", "parameters": [ { "description": "imaginary operation.", "in": "path", "name": "endpoint", "required": true, "schema": { "enum": [ "resize", "enlarge", "extract", "crop", "smartcrop", "rotate", "autorotate", "flip", "flop", "thumbnail", "zoom", "convert", "fit", "blur", "watermark", "watermarkimage", "info", "pipeline" ], "type": "string" } }, { "description": "Source URL or xi://\u003csource\u003e/\u003ckey\u003e.", "in": "query", "name": "url", "required": true, "schema": { "type": "string" } }, { "description": "imaginary parameter width (URL-DIALECTS §4).", "in": "query", "name": "width", "schema": { "type": "string" } }, { "description": "imaginary parameter height (URL-DIALECTS §4).", "in": "query", "name": "height", "schema": { "type": "string" } }, { "description": "imaginary parameter areawidth (URL-DIALECTS §4).", "in": "query", "name": "areawidth", "schema": { "type": "string" } }, { "description": "imaginary parameter areaheight (URL-DIALECTS §4).", "in": "query", "name": "areaheight", "schema": { "type": "string" } }, { "description": "imaginary parameter quality (URL-DIALECTS §4).", "in": "query", "name": "quality", "schema": { "type": "string" } }, { "description": "imaginary parameter compression (URL-DIALECTS §4).", "in": "query", "name": "compression", "schema": { "type": "string" } }, { "description": "imaginary parameter type (URL-DIALECTS §4).", "in": "query", "name": "type", "schema": { "type": "string" } }, { "description": "imaginary parameter force (URL-DIALECTS §4).", "in": "query", "name": "force", "schema": { "type": "string" } }, { "description": "imaginary parameter rotate (URL-DIALECTS §4).", "in": "query", "name": "rotate", "schema": { "type": "string" } }, { "description": "imaginary parameter embed (URL-DIALECTS §4).", "in": "query", "name": "embed", "schema": { "type": "string" } }, { "description": "imaginary parameter norotation (URL-DIALECTS §4).", "in": "query", "name": "norotation", "schema": { "type": "string" } }, { "description": "imaginary parameter noprofile (URL-DIALECTS §4).", "in": "query", "name": "noprofile", "schema": { "type": "string" } }, { "description": "imaginary parameter stripmeta (URL-DIALECTS §4).", "in": "query", "name": "stripmeta", "schema": { "type": "string" } }, { "description": "imaginary parameter flip (URL-DIALECTS §4).", "in": "query", "name": "flip", "schema": { "type": "string" } }, { "description": "imaginary parameter flop (URL-DIALECTS §4).", "in": "query", "name": "flop", "schema": { "type": "string" } }, { "description": "imaginary parameter extend (URL-DIALECTS §4).", "in": "query", "name": "extend", "schema": { "type": "string" } }, { "description": "imaginary parameter background (URL-DIALECTS §4).", "in": "query", "name": "background", "schema": { "type": "string" } }, { "description": "imaginary parameter gravity (URL-DIALECTS §4).", "in": "query", "name": "gravity", "schema": { "type": "string" } }, { "description": "imaginary parameter top (URL-DIALECTS §4).", "in": "query", "name": "top", "schema": { "type": "string" } }, { "description": "imaginary parameter left (URL-DIALECTS §4).", "in": "query", "name": "left", "schema": { "type": "string" } }, { "description": "imaginary parameter factor (URL-DIALECTS §4).", "in": "query", "name": "factor", "schema": { "type": "string" } }, { "description": "imaginary parameter dpi (URL-DIALECTS §4).", "in": "query", "name": "dpi", "schema": { "type": "string" } }, { "description": "imaginary parameter interlace (URL-DIALECTS §4).", "in": "query", "name": "interlace", "schema": { "type": "string" } }, { "description": "imaginary parameter aspectratio (URL-DIALECTS §4).", "in": "query", "name": "aspectratio", "schema": { "type": "string" } }, { "description": "imaginary parameter palette (URL-DIALECTS §4).", "in": "query", "name": "palette", "schema": { "type": "string" } }, { "description": "imaginary parameter sigma (URL-DIALECTS §4).", "in": "query", "name": "sigma", "schema": { "type": "string" } }, { "description": "imaginary parameter minampl (URL-DIALECTS §4).", "in": "query", "name": "minampl", "schema": { "type": "string" } }, { "description": "imaginary parameter text (URL-DIALECTS §4).", "in": "query", "name": "text", "schema": { "type": "string" } }, { "description": "imaginary parameter font (URL-DIALECTS §4).", "in": "query", "name": "font", "schema": { "type": "string" } }, { "description": "imaginary parameter textwidth (URL-DIALECTS §4).", "in": "query", "name": "textwidth", "schema": { "type": "string" } }, { "description": "imaginary parameter opacity (URL-DIALECTS §4).", "in": "query", "name": "opacity", "schema": { "type": "string" } }, { "description": "imaginary parameter margin (URL-DIALECTS §4).", "in": "query", "name": "margin", "schema": { "type": "string" } }, { "description": "imaginary parameter color (URL-DIALECTS §4).", "in": "query", "name": "color", "schema": { "type": "string" } }, { "description": "imaginary parameter noreplicate (URL-DIALECTS §4).", "in": "query", "name": "noreplicate", "schema": { "type": "string" } }, { "description": "imaginary parameter image (URL-DIALECTS §4).", "in": "query", "name": "image", "schema": { "type": "string" } }, { "description": "imaginary parameter nocrop (URL-DIALECTS §4).", "in": "query", "name": "nocrop", "schema": { "type": "string" } }, { "description": "imaginary parameter colorspace (URL-DIALECTS §4).", "in": "query", "name": "colorspace", "schema": { "type": "string" } }, { "description": "imaginary parameter operations (URL-DIALECTS §4).", "in": "query", "name": "operations", "schema": { "type": "string" } }, { "description": "imaginary parameter sign (URL-DIALECTS §4).", "in": "query", "name": "sign", "schema": { "type": "string" } }, { "description": "imaginary parameter xi_sig (URL-DIALECTS §4).", "in": "query", "name": "xi_sig", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "image/*": { "schema": { "contentEncoding": "binary", "type": "string" } } }, "description": "The processed image; the format follows `format`, the source extension or Accept negotiation.", "headers": { "Cache-Control": { "description": "XI_CACHE_HEADERS_* policy, or the URL's expires.", "schema": { "type": "string" } }, "ETag": { "description": "Strong entity tag of the result.", "schema": { "type": "string" } }, "Vary": { "description": "Accept and the client hints that decided the result.", "schema": { "type": "string" } } } }, "304": { "description": "Not modified: If-None-Match matched the ETag." }, "400": { "$ref": "#/components/responses/Error400" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "406": { "$ref": "#/components/responses/Error406" }, "414": { "$ref": "#/components/responses/Error414" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "501": { "$ref": "#/components/responses/Error501" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" }, "504": { "$ref": "#/components/responses/Error504" } }, "summary": "Process an image (imaginary endpoints, query dialect)", "tags": [ "image" ], "x-xi-dialect": "query", "x-xi-listener": "public", "x-xi-query-method": { "config": "XI_SERVER_QUERY_METHOD", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryContent" } }, "application/x-www-form-urlencoded": { "schema": { "description": "Exactly the query string of the equivalent GET URL (same keys, order and escaping).", "example": "url=https%3A%2F%2Fexample.com%2Fa.jpg\u0026w=300\u0026f=webp", "type": "string" } } }, "description": "The parameters of the GET operation travel in the request content; the URL has no query (a query is 400). Signing (xi_sig or sign as a parameter in the content, over the same message as the GET URL), the unsigned policy, limits, conditional requests and the result cache entry are those of the equivalent GET request.", "docs": "https://github.com/xantiagoma/xtandard-image/blob/main/docs/URL-DIALECTS.md#44-http-query", "errors": { "400": "Malformed content, or a URL with a query.", "405": "XI_SERVER_QUERY_METHOD=false, or an endpoint of another dialect (Allow lists the methods).", "413": "Content over XI_SERVER_QUERY_MAX_BODY_BYTES.", "415": "Missing or unsupported Content-Type, a charset other than UTF-8, or a Content-Encoding." }, "method": "QUERY", "response_headers": { "Accept-Query": "The media types above, as a Structured Field list; also on GET, HEAD and 405 responses of these endpoints.", "Location": "On 2xx: the equivalent GET URL when it fits XI_SERVER_QUERY_LOCATION_MAX_LENGTH and carries no pdf_password.", "Vary": "Adds Content-Type." }, "rfc": "https://www.rfc-editor.org/rfc/rfc10008" } } }, "/readyz": { "get": { "description": "200 when ready for traffic; 503 while starting or draining (load balancers deregister), and busy while the processing queue is at least XI_SERVER_READY_QUEUE_THRESHOLD % full (off by default). Served on both listeners.", "operationId": "getReadyz", "responses": { "200": { "content": { "text/plain": { "example": "ready\n", "schema": { "description": "The state name.", "pattern": "^ready\\n$", "type": "string" } } }, "description": "Ready." }, "503": { "content": { "text/plain": { "example": "draining\n", "schema": { "description": "The state name, or busy.", "pattern": "^(starting|draining|busy)\\n$", "type": "string" } } }, "description": "Starting, draining or busy." } }, "servers": [ { "description": "Public listener.", "url": "http://localhost:8080" }, { "description": "Admin listener.", "url": "http://127.0.0.1:9090" } ], "summary": "Readiness", "tags": [ "health" ], "x-xi-listener": "public+admin" } }, "/video/{signature}/{options}/{source}": { "get": { "description": "Trims, resizes, crops, rotates and transcodes a video into MP4 or WebM, its audio into M4A, MP3, Opus, Ogg, FLAC or WAV, or draws its audio as a PNG or WebP waveform. {options} is zero or more video options separated by / (rs:fill:640:360/vs:1/vd:5), typed by the ImgproxyVideoOptions schema; the source extension (@webm) picks the container. The signature covers \"/video\" + the path after it, so image signatures are not valid here. Needs XI_VIDEO_TRANSFORM_ENABLED (404 otherwise, and on XI_ROLE=image); unsigned requests are 403 unless XI_VIDEO_TRANSFORM_UNSIGNED_POLICY=allow. Supports Range.", "externalDocs": { "url": "https://github.com/xantiagoma/xtandard-image/blob/main/docs/URL-DIALECTS.md#38-video-transformations-wp-122-wp-123" }, "operationId": "getImgproxyVideo", "parameters": [ { "description": "URL signature, or any value (conventionally unsafe) when signing is off.", "example": "unsafe", "in": "path", "name": "signature", "required": true, "schema": { "type": "string" } }, { "description": "Video options joined by /, each name:arg:arg (ImgproxyVideoOptions).", "example": "rs:fit:640:0/vd:5", "in": "path", "name": "options", "required": true, "schema": { "type": "string" }, "x-xi-options-schema": { "$ref": "#/components/schemas/ImgproxyVideoOptions" } }, { "description": "The source: plain/\u003cpercent-encoded URL\u003e[@ext], \u003curl-safe base64 URL\u003e[.ext] (may be split with /) or enc/\u003cAES-CBC token\u003e[.ext]. Schemes: http(s), s3, gs, abs, local, ftp, sftp, xi://\u003csource\u003e/.", "example": "plain/https://example.com/a.jpg@webp", "in": "path", "name": "source", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "audio/*": { "schema": { "contentEncoding": "binary", "type": "string" } }, "image/png": { "schema": { "contentEncoding": "binary", "type": "string" } }, "image/webp": { "schema": { "contentEncoding": "binary", "type": "string" } }, "video/*": { "schema": { "contentEncoding": "binary", "type": "string" } } }, "description": "The transcoded file: video/mp4, video/webm, audio/mp4, audio/mpeg, audio/ogg, audio/flac, audio/wav, or image/png and image/webp for a waveform picture.", "headers": { "Accept-Ranges": { "description": "bytes", "schema": { "type": "string" } }, "Cache-Control": { "description": "XI_CACHE_HEADERS_* policy, or the URL's expires.", "schema": { "type": "string" } }, "ETag": { "description": "Strong entity tag (also the If-Range validator).", "schema": { "type": "string" } } } }, "206": { "description": "Partial content: the Range of the file (multipart/byteranges for several ranges)." }, "304": { "description": "Not modified: If-None-Match matched the ETag." }, "400": { "$ref": "#/components/responses/Error400" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "406": { "$ref": "#/components/responses/Error406" }, "414": { "$ref": "#/components/responses/Error414" }, "416": { "description": "Range not satisfiable." }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "501": { "$ref": "#/components/responses/Error501" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" }, "504": { "$ref": "#/components/responses/Error504" } }, "summary": "Transform a video or its audio (imgproxy-style /video, WP-122, WP-123)", "tags": [ "video" ], "x-xi-dialect": "imgproxy", "x-xi-listener": "public", "x-xi-path-grammar": "/%signature/%options.../plain/%source_url[@%extension]\n/%signature/%options.../%base64url_source_url[.%extension] (may be split with \"/\")\n/%signature/%options.../enc/%aes_cbc_source[.%extension] (may be split with \"/\")\n/info/%signature/%info_options.../{plain/…|%base64…|enc/…}\n/video/%signature/%video_options.../{plain/…[@%container]|%base64…|enc/…}\n\noption = name \":\" arg *(\":\" arg) ; separator configurable (XI_DIALECTS_IMGPROXY_ARGUMENTS_SEPARATOR)\npipeline = option *(\"/\" option)\npipelines = pipeline *(\"/-/\" pipeline) ; chained pipelines\nbool = \"1\" | \"t\" | \"true\" | \"0\" | \"f\" | \"false\"", "x-xi-signing": { "description": "HMAC-SHA256(key, salt ‖ \"/video\" ‖ path after the signature), url-safe base64 without padding, optionally truncated to XI_SIGNING_SIZE bytes; any value (conventionally unsafe) when signing is off.", "docs": "https://github.com/xantiagoma/xtandard-image/blob/main/docs/URL-DIALECTS.md#38-video-transformations-wp-122-wp-123", "scheme": "imgproxy" }, "x-xi-video-options": { "$ref": "#/components/schemas/ImgproxyVideoOptions" } } }, "/{signature}/{processingOptions}/{source}": { "get": { "description": "imgproxy URL: {processingOptions} is zero or more options separated by / (rs:fill:300:400:0/g:sm), with /-/ chaining pipelines, typed by the ImgproxyProcessingOptions schema (x-xi-processing-options). Grammar: x-xi-path-grammar; the mount prefix is configurable (XI_DIALECTS_IMGPROXY_PREFIX).", "externalDocs": { "url": "https://github.com/xantiagoma/xtandard-image/blob/main/docs/URL-DIALECTS.md#3-imgproxy-canonical" }, "operationId": "getImgproxyImage", "parameters": [ { "description": "URL signature, or any value (conventionally unsafe) when signing is off.", "example": "unsafe", "in": "path", "name": "signature", "required": true, "schema": { "type": "string" } }, { "description": "Processing options joined by /, each name:arg:arg (ImgproxyProcessingOptions).", "example": "rs:fill:300:400:0/g:sm", "in": "path", "name": "processingOptions", "required": true, "schema": { "type": "string" }, "x-xi-options-schema": { "$ref": "#/components/schemas/ImgproxyProcessingOptions" } }, { "description": "The source: plain/\u003cpercent-encoded URL\u003e[@ext], \u003curl-safe base64 URL\u003e[.ext] (may be split with /) or enc/\u003cAES-CBC token\u003e[.ext]. Schemes: http(s), s3, gs, abs, local, ftp, sftp, xi://\u003csource\u003e/.", "example": "plain/https://example.com/a.jpg@webp", "in": "path", "name": "source", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "image/*": { "schema": { "contentEncoding": "binary", "type": "string" } } }, "description": "The processed image; the format follows `format`, the source extension or Accept negotiation.", "headers": { "Cache-Control": { "description": "XI_CACHE_HEADERS_* policy, or the URL's expires.", "schema": { "type": "string" } }, "ETag": { "description": "Strong entity tag of the result.", "schema": { "type": "string" } }, "Vary": { "description": "Accept and the client hints that decided the result.", "schema": { "type": "string" } } } }, "304": { "description": "Not modified: If-None-Match matched the ETag." }, "400": { "$ref": "#/components/responses/Error400" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "406": { "$ref": "#/components/responses/Error406" }, "414": { "$ref": "#/components/responses/Error414" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "501": { "$ref": "#/components/responses/Error501" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" }, "504": { "$ref": "#/components/responses/Error504" } }, "summary": "Process an image (imgproxy dialect, the default)", "tags": [ "image" ], "x-xi-dialect": "imgproxy", "x-xi-listener": "public", "x-xi-path-grammar": "/%signature/%options.../plain/%source_url[@%extension]\n/%signature/%options.../%base64url_source_url[.%extension] (may be split with \"/\")\n/%signature/%options.../enc/%aes_cbc_source[.%extension] (may be split with \"/\")\n/info/%signature/%info_options.../{plain/…|%base64…|enc/…}\n/video/%signature/%video_options.../{plain/…[@%container]|%base64…|enc/…}\n\noption = name \":\" arg *(\":\" arg) ; separator configurable (XI_DIALECTS_IMGPROXY_ARGUMENTS_SEPARATOR)\npipeline = option *(\"/\" option)\npipelines = pipeline *(\"/-/\" pipeline) ; chained pipelines\nbool = \"1\" | \"t\" | \"true\" | \"0\" | \"f\" | \"false\"", "x-xi-processing-options": { "$ref": "#/components/schemas/ImgproxyProcessingOptions" }, "x-xi-signing": { "description": "HMAC-SHA256(key, salt ‖ path after the signature, starting with /), url-safe base64 without padding, optionally truncated to XI_SIGNING_SIZE bytes; any value (conventionally unsafe) when signing is off.", "docs": "https://docs.imgproxy.net/usage/signing_url", "scheme": "imgproxy" } } } }, "security": [ {} ], "servers": [ { "description": "Public listener (XI_SERVER_ADDR).", "url": "http://localhost:8080" }, { "description": "Admin listener (XI_ADMIN_ADDR): admin-tagged operations only.", "url": "http://127.0.0.1:9090" } ], "tags": [ { "description": "Image processing, one operation per URL dialect grammar.", "externalDocs": { "url": "https://github.com/xantiagoma/xtandard-image/blob/main/docs/URL-DIALECTS.md" }, "name": "image" }, { "description": "Source metadata (imgproxy /info).", "name": "info" }, { "description": "Liveness and readiness, on both listeners.", "name": "health" }, { "description": "Admin listener only: metrics, documents, profiling.", "name": "admin" }, { "description": "Playground UI and its JSON API (XI_PLAYGROUND_ENABLED, off by default): admin listener, and the public listener only with XI_PLAYGROUND_PUBLIC. Paths are under XI_PLAYGROUND_PATH (default /_playground).", "name": "playground" } ], "x-xi-dialects": [ { "docs": "https://github.com/xantiagoma/xtandard-image/blob/main/docs/URL-DIALECTS.md#3-imgproxy-canonical", "name": "imgproxy", "prefix": "/", "status": "served" }, { "docs": "https://github.com/xantiagoma/xtandard-image/blob/main/docs/URL-DIALECTS.md#4-query-dialect-native--imaginary", "name": "query", "prefix": "/q/", "status": "served" }, { "docs": "https://github.com/xantiagoma/xtandard-image/blob/main/docs/URL-DIALECTS.md#7-imagekit", "name": "imagekit", "prefix": "/imagekit/", "status": "served" }, { "docs": "https://github.com/xantiagoma/xtandard-image/blob/main/docs/URL-DIALECTS.md#5-imgix", "name": "imgix", "prefix": "/imgix/", "status": "served" }, { "docs": "https://github.com/xantiagoma/xtandard-image/blob/main/docs/URL-DIALECTS.md#6-cloudinary", "name": "cloudinary", "prefix": "/cloudinary/", "status": "served" }, { "docs": "https://github.com/xantiagoma/xtandard-image/blob/main/docs/URL-DIALECTS.md#8-cloudflare-images-cdn-cgiimage", "name": "cloudflare", "prefix": "/cdn-cgi/image/", "status": "served" }, { "docs": "https://github.com/xantiagoma/xtandard-image/blob/main/docs/URL-DIALECTS.md#81-cloudflare-images-delivery-cdn-cgiimagedelivery-imagedeliverynet", "name": "cloudflare_images", "prefix": "/cdn-cgi/imagedelivery/", "status": "served" }, { "docs": "https://github.com/xantiagoma/xtandard-image/blob/main/docs/URL-DIALECTS.md#9-bunny-optimizer", "name": "bunny", "prefix": "/bunny/", "status": "served" }, { "docs": "https://github.com/xantiagoma/xtandard-image/blob/main/docs/URL-DIALECTS.md#10-thumbor", "name": "thumbor", "prefix": "/thumbor/", "status": "served" }, { "docs": "https://github.com/xantiagoma/xtandard-image/blob/main/docs/URL-DIALECTS.md#11-weserv--wsrvnl", "name": "wsrv", "prefix": "/wsrv/", "status": "served" }, { "docs": "https://github.com/xantiagoma/xtandard-image/blob/main/docs/URL-DIALECTS.md#13-aws-serverless-image-handler-dynamic-image-transformation-for-amazon-cloudfront", "name": "awssih", "prefix": "/sih/", "status": "served" }, { "docs": "https://github.com/xantiagoma/xtandard-image/blob/main/docs/URL-DIALECTS.md#12-unpic-long-tail-simple-micro-dialects", "name": "simple", "prefix": "provider-native prefixes", "status": "served" } ] }