Tools Metadata
Analyze uploaded files and extract technical metadata, returning structured information without modifying the original file content.
Raw JSON
What You Can Control With Metadata Action
With the Metadata action, you can control how file metadata is extracted and returned as structured data for inspection or automation.
- Extracting technical file metadata
- Reading format and file-type information
- Inspecting size and structural attributes
- Returning metadata as structured JSON output
- Analyzing files without generating new outputs
- Using metadata for validation or automation logic
Tools Endpoint Capabilities
The Tools endpoint provides image analysis and utility tools that return structured results (not transformed image files). Use single to run exactly one tool, or multitask to run multiple tools per image in one request.
metadata
Returns structured metadata for each image and can optionally include raw EXIF payload when includeRawExif='true' is provided.
dimensions
Returns image dimension properties in a structured format, enabling validation rules and consistent sizing logic in automated workflows.
quality
Estimates quality signals using a configurable sampling size (qualitySample) to support automated checks and consistent media intake.
efficiency
Estimates delivery efficiency using optional target parameters (efficiencyFormat, efficiencyQuality) to guide optimization decisions.
colors
Extracts color information and supports palette sizing controls (paletteSize) for consistent palette reporting across images.
palette
Returns a controlled-size palette representation using paletteSize clamping rules to keep results stable and predictable.
detect-format
Detects the input image format to support validation, conditional logic, and safe automation in upload pipelines.
orientation
Reports orientation-related signals so systems can normalize display logic without relying on inconsistent client-side handling.
similarity
Computes similarity signals between images and supports batch modes (pairs/tofirst) with a threshold for classification control.
hash
Generates hashes for deduplication and integrity workflows, supporting phash plus cryptographic options (md5, sha1, sha256).
transparency
Analyzes alpha/transparency behavior using a sampling control (transparencySample) to support correct rendering decisions downstream.
multitask
Runs multiple tools on each uploaded image in a single request, returning structured per-image results while respecting all platform limits and constraints.
Why Developers Use the Tools Endpoint
Structured Results for Validation Pipelines
The Tools endpoint returns structured, machine-readable JSON outputs designed for inspection, validation, and decision-making workflows. These results allow developers to validate uploads, enforce media rules, and drive conditional logic without generating output files or performing visual transformations.
Two Clear Execution Modes: Single vs Multitask
Use action=single to run exactly one tool (strictly enforced), or action=multitask to run multiple tools in one call. This keeps integrations predictable and reduces API call overhead.
Built-in Controls for Consistent Measurements
Tool parameters such as qualitySample, paletteSize, hashType, and similarity thresholds are explicitly validated, and where applicable, constrained to documented safe ranges. This ensures tool results remain predictable and comparable across requests and environments, while still allowing controlled configurability per tool.
Batch Similarity Support for Deduplication
Similarity analysis supports batch comparison workflows, including pairwise comparison modes within documented file-count and upload constraints. This enables reliable detection of duplicate and near-duplicate media while ensuring performance and resource usage remain bounded and enforced by platform limits.
Production Guards: Limits, Concurrency, and Clear Errors
The endpoint is protected by standard platform gates such as concurrency controls and structured errors, making it safe to use in automation and high-volume pipelines.
Designed for Automation, Not UI Guesswork
Parameters are explicit and documented (tools list parsing, required fields, and defaults), which reduces integration ambiguity and keeps behavior reliable across versions.
Safe Output Handling and Request Tracking
Responses return per-image tool results in a structured JSON format and may include a request_id when available. This allows developers to trace, log, and correlate tool executions across systems without exposing internal infrastructure or execution details.
Use Cases Powered By Tools Endpoint
Upload Validation & Rules
Use the Tools endpoint to inspect uploaded images before acceptance or storage. Tools outputs can be used to verify format, dimensions, orientation, metadata presence, color properties, transparency usage, and similarity signals. This allows systems to automatically accept, reject, or flag uploads based on defined media rules without generating output files or modifying the original image.
Media Library Deduplication
Use similarity and hash analysis tools to compare newly uploaded images against existing media in batch workflows. The Tools endpoint enables detection of exact duplicates and near-duplicates within enforced file-count and upload limits, allowing libraries to prevent redundant storage, consolidate assets, or flag potential duplicates before images are added to long-term storage.
CMS & Moderation Pipelines
Integrate the Tools endpoint into CMS ingestion or moderation flows to analyze images as they enter the system. Tool outputs can be used to evaluate technical compliance—such as orientation, resolution, transparency usage, metadata consistency, and similarity patterns—supporting automated moderation decisions or routing content for manual review without exposing internal processing systems.
E-Commerce Catalog Integrity
Use the Tools endpoint to analyze product images for catalog consistency and quality assurance. Tool results can be applied to enforce dimension standards, detect incorrect formats, identify transparency usage, compare product images for duplication, and ensure visual consistency across listings, helping maintain clean and reliable catalogs without altering the source files.
Automated QA & Reporting
Use the Tools endpoint to generate structured inspection data for automated QA checks and reporting pipelines. Tool outputs can be logged, aggregated, and audited to monitor image compliance, detect anomalies, track duplication trends, and validate media standards over time, providing reliable technical insights without performing transformations or producing derived assets.
Frequently Asked Questions
Tools Endpoint FAQ
wwww
wwww