{"openapi":"3.1.0","info":{"title":"ZR Image Toolkit REST API","description":"Enterprise API suite for image format conversion, intelligent compression, multi-stage pipelines, asynchronous batch queues, vector rendering, audio processing, and secure signed asset delivery.","version":"1.0.0","contact":{"name":"ZR Image Toolkit Architecture Team"}},"servers":[{"url":"https:\/\/tool.uio.la\/api\/v1","description":"Current API v1 Environment"}],"paths":{"\/convert":{"post":{"summary":"Convert Image Format","description":"Converts an uploaded image to a target format (JPEG, PNG, WebP, AVIF, GIF, BMP, TIFF) with configurable quality and strip-metadata options.","tags":["Core Transformations"],"security":[{"bearerAuth":["convert:write"]}],"requestBody":{"required":true,"content":{"multipart\/form-data":{"schema":{"type":"object","required":["image","format"],"properties":{"image":{"type":"string","format":"binary","description":"Source image file (Max 50MB)"},"format":{"type":"string","enum":["jpeg","png","webp","avif","gif","bmp","tiff"],"description":"Desired output format"},"quality":{"type":"integer","minimum":1,"maximum":100,"default":85,"description":"Compression quality level (1-100)"},"strip_metadata":{"type":"boolean","default":false,"description":"Whether to scrub EXIF and camera metadata"}}}}}},"responses":{"200":{"description":"Image successfully converted","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ProcessSuccessResponse"}}}},"422":{"description":"Validation error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ValidationErrorResponse"}}}}}}},"\/compress":{"post":{"summary":"Smart Image Compression","description":"Reduces file size using perceptive optimization algorithms across Lossless, Balanced, Aggressive, or Extreme compression presets.","tags":["Core Transformations"],"security":[{"bearerAuth":["compress:write"]}],"requestBody":{"required":true,"content":{"multipart\/form-data":{"schema":{"type":"object","required":["image","level"],"properties":{"image":{"type":"string","format":"binary","description":"Source image to compress"},"level":{"type":"string","enum":["lossless","balanced","aggressive","extreme"],"default":"balanced","description":"Compression intensity preset"}}}}}},"responses":{"200":{"description":"Image successfully compressed","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ProcessSuccessResponse"}}}}}}},"\/process":{"post":{"summary":"Execute Transformation Manifest","description":"Executes an ordered pipeline of transformations (resizing, cropping, rotation, watermarking, filters, adjustments) on an image.","tags":["Core Transformations"],"security":[{"bearerAuth":["process:write"]}],"requestBody":{"required":true,"content":{"multipart\/form-data":{"schema":{"type":"object","required":["image","manifest"],"properties":{"image":{"type":"string","format":"binary","description":"Target image file"},"manifest":{"type":"string","description":"JSON string of ordered operations: [{\"action\": \"resize\", \"params\": {\"width\": 800}}]"}}}}}},"responses":{"200":{"description":"Pipeline completed successfully","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ProcessSuccessResponse"}}}}}}},"\/smart-crop":{"post":{"summary":"Smart Crop by Visual Prominence","description":"Calculates the focal region and crops image based on edge gradient energy and center bias for any standard aspect ratio.","tags":["Visual Intelligence & Web Kits"],"security":[{"bearerAuth":["process:write"]}],"requestBody":{"required":true,"content":{"multipart\/form-data":{"schema":{"type":"object","required":["image","aspect_ratio"],"properties":{"image":{"type":"string","format":"binary","description":"Source image file"},"aspect_ratio":{"type":"string","enum":["1:1","16:9","4:5","9:16","4:3","3:2","21:9"],"default":"1:1"},"width":{"type":"integer","example":800},"height":{"type":"integer","example":800}}}}}},"responses":{"200":{"description":"Smart crop calculated and image resized"}}}},"\/responsive-kit":{"post":{"summary":"Generate Responsive Image Kit","description":"Creates multi-breakpoint responsive image variants in AVIF, WebP, and JPEG, packaged in a ZIP archive with HTML5 picture snippet.","tags":["Visual Intelligence & Web Kits"],"security":[{"bearerAuth":["process:write"]}],"requestBody":{"required":true,"content":{"multipart\/form-data":{"schema":{"type":"object","required":["image"],"properties":{"image":{"type":"string","format":"binary","description":"Master high-resolution image"},"alt_text":{"type":"string","default":"Responsive visual asset"},"quality":{"type":"integer","default":85}}}}}},"responses":{"200":{"description":"Variants created, zipped, and HTML snippet returned"}}}},"\/background-remove":{"post":{"summary":"Remove Image Background (E-Commerce Studio)","description":"Isolates product subjects by automatically detecting dominant studio background or chroma key color, outputting transparent PNG\/WebP with edge feathering.","tags":["Visual Intelligence & Web Kits"],"security":[{"bearerAuth":["process:write"]}],"requestBody":{"required":true,"content":{"multipart\/form-data":{"schema":{"type":"object","required":["image"],"properties":{"image":{"type":"string","format":"binary","description":"Source photo with solid or studio background"},"mode":{"type":"string","enum":["auto","color"],"default":"auto"},"color":{"type":"string","example":"#ffffff","description":"Chroma key hex color to remove"},"tolerance":{"type":"integer","default":25,"description":"Color distance tolerance threshold (1-100)"},"feather":{"type":"integer","default":5,"description":"Edge anti-aliasing feathering width (0-30)"},"format":{"type":"string","enum":["png","webp"],"default":"png"}}}}}},"responses":{"200":{"description":"Background cleared, returns transparent image asset and clearance metrics"}}}},"\/preset":{"post":{"summary":"Apply Social\/E-Commerce Preset","description":"Transforms an image according to standardized dimensions for Shopify, Amazon, Instagram, Facebook, LinkedIn, or Twitter.","tags":["Core Transformations"],"security":[{"bearerAuth":["preset:write"]}],"requestBody":{"required":true,"content":{"multipart\/form-data":{"schema":{"type":"object","required":["image","preset"],"properties":{"image":{"type":"string","format":"binary","description":"Source image"},"preset":{"type":"string","example":"instagram_post_square","description":"Preset identifier"}}}}}},"responses":{"200":{"description":"Preset successfully applied","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ProcessSuccessResponse"}}}}}}},"\/batch":{"post":{"summary":"Create Asynchronous Batch Job","description":"Dispatches a high-throughput queue job to process multiple images in parallel with optional HMAC webhook dispatch upon completion.","tags":["Batch Processing"],"security":[{"bearerAuth":["batch:write"]}],"requestBody":{"required":true,"content":{"multipart\/form-data":{"schema":{"type":"object","required":["images"],"properties":{"images[]":{"type":"array","items":{"type":"string","format":"binary"},"description":"Collection of image files to process"},"recipe_id":{"type":"integer","description":"Optional recipe ID to apply to each item"},"operations":{"type":"string","description":"Optional JSON encoded operations pipeline"},"webhook_url":{"type":"string","format":"uri","description":"URL to receive signed HMAC webhook payload upon job completion"}}}}}},"responses":{"200":{"description":"Batch job queued","content":{"application\/json":{"schema":{"type":"object","properties":{"batch_id":{"type":"string"},"total_items":{"type":"integer"},"status":{"type":"string"}}}}}}}}},"\/batch\/{batch}":{"get":{"summary":"Get Batch Job Status","description":"Queries progress, total processed items, failure counts, and ZIP readiness for an async batch job.","tags":["Batch Processing"],"security":[{"bearerAuth":["batch:read"]}],"parameters":[{"name":"batch","in":"path","required":true,"schema":{"type":"string"},"description":"Batch UUID"}],"responses":{"200":{"description":"Batch progress details"}}}},"\/batch\/{batch}\/download":{"get":{"summary":"Download Batch ZIP Archive","description":"Streams the finalized ZIP archive containing all processed assets in the batch job.","tags":["Batch Processing"],"security":[{"bearerAuth":["batch:read"]}],"parameters":[{"name":"batch","in":"path","required":true,"schema":{"type":"string"},"description":"Batch UUID"}],"responses":{"200":{"description":"ZIP archive download stream","content":{"application\/zip":{"schema":{"type":"string","format":"binary"}}}}}}},"\/recipes":{"get":{"summary":"List Transformation Recipes","description":"Retrieves user-created and default system pipeline recipes.","tags":["Custom Recipes"],"security":[{"bearerAuth":["recipes:read"]}],"responses":{"200":{"description":"Array of transformation recipes"}}}},"\/audio\/convert":{"post":{"summary":"Audio Convert & Normalize","description":"Processes audio tracks or extracts audio from video files with EBU R128 normalization and multi-codec support (MP3, WAV, AAC, OGG, FLAC, M4A).","tags":["Multimedia & Audio"],"security":[{"bearerAuth":["media:write"]}],"requestBody":{"required":true,"content":{"multipart\/form-data":{"schema":{"type":"object","required":["file","format"],"properties":{"file":{"type":"string","format":"binary","description":"Audio or video source file"},"format":{"type":"string","enum":["mp3","wav","aac","ogg","flac","m4a"]},"bitrate":{"type":"string","default":"192k"},"normalize":{"type":"boolean","default":true}}}}}},"responses":{"200":{"description":"Audio converted successfully"}}}},"\/documents\/pdf-to-images":{"post":{"summary":"Extract PDF Pages to Images","description":"Renders vector and raster pages from a PDF document to PNG\/JPEG images at selectable DPI (72, 150, 300) packed in a ZIP archive.","tags":["Document & Vector Studio"],"security":[{"bearerAuth":["documents:write"]}],"requestBody":{"required":true,"content":{"multipart\/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"},"dpi":{"type":"integer","default":150},"format":{"type":"string","enum":["png","jpeg"],"default":"png"}}}}}},"responses":{"200":{"description":"Pages extracted and zipped"}}}},"\/documents\/images-to-pdf":{"post":{"summary":"Compile Multiple Images into PDF","description":"Stitches multiple uploaded images into a standard PDF 1.4 document with automatic page dimensioning.","tags":["Document & Vector Studio"],"security":[{"bearerAuth":["documents:write"]}],"requestBody":{"required":true,"content":{"multipart\/form-data":{"schema":{"type":"object","required":["images"],"properties":{"images[]":{"type":"array","items":{"type":"string","format":"binary"}}}}}}},"responses":{"200":{"description":"PDF compiled successfully"}}}},"\/documents\/svg-render":{"post":{"summary":"Rasterize SVG Vector File","description":"Safely sanitizes SVG against XXE\/script attacks and renders it at native or 2x-8x resolution to PNG, JPEG, or WebP.","tags":["Document & Vector Studio"],"security":[{"bearerAuth":["documents:write"]}],"requestBody":{"required":true,"content":{"multipart\/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"},"format":{"type":"string","enum":["png","jpeg","webp"],"default":"png"},"zoom":{"type":"number","default":2}}}}}},"responses":{"200":{"description":"SVG rendered successfully"}}}},"\/video\/convert":{"post":{"summary":"Convert video","tags":["Multimedia & Audio"],"security":[{"bearerAuth":["media:write"]}],"responses":{"202":{"description":"Processing task accepted"}}}},"\/metadata\/analyze":{"post":{"summary":"Analyze image metadata","tags":["Metadata"],"security":[{"bearerAuth":["metadata:write"]}],"responses":{"200":{"description":"Metadata extracted"}}}},"\/palette\/extract":{"post":{"summary":"Extract a color palette","tags":["Palette"],"security":[{"bearerAuth":["palette:write"]}],"responses":{"200":{"description":"Palette extracted"}}}},"\/favicons\/generate":{"post":{"summary":"Generate a favicon package","tags":["Favicons"],"security":[{"bearerAuth":["favicons:write"]}],"responses":{"200":{"description":"Favicon package generated"}}}},"\/tasks\/{task}":{"get":{"summary":"Read a processing task","tags":["Tasks"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Task status and result"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"Sanctum PAT","description":"Personal API token generated in the Developer Settings portal. Header: Authorization: Bearer <token>"}},"schemas":{"ProcessSuccessResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"output_id":{"type":"string","example":"output_6702a..."},"url":{"type":"string","example":"\/storage\/outputs\/banner.webp"},"file_name":{"type":"string","example":"banner.webp"},"width":{"type":"integer","example":1920},"height":{"type":"integer","example":1080},"file_size":{"type":"integer","example":145020},"mime_type":{"type":"string","example":"image\/webp"},"metrics":{"type":"object","properties":{"duration_ms":{"type":"number","example":45.2},"bytes_saved":{"type":"integer","example":89200},"compression_ratio":{"type":"number","example":38}}}}},"ValidationErrorResponse":{"type":"object","properties":{"message":{"type":"string","example":"The given data was invalid."},"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}}}