POST/api/v1/media/images/upload

Upload Image (Validated)

The dedicated image upload endpoint validates content using magic byte detection and auto-corrects filename extensions when they don't match the actual image format.

info

v2.28.8 Feature: This endpoint provides stricter validation than the general file upload endpoints. Use this when you need guaranteed image validation.

Key Features

✨

Magic Byte Detection

Detects actual format from file signature (first 16 bytes), not just the filename

🔄

Auto-Correction

Fixes filename extension if mismatched (e.g., PNG saved as .jpg)

🛡️

Strict Validation

Returns 400 Bad Request if content is not a valid image

ℹ️

Format Info

Returns detected format, corrected filename, and correction status

Supported Formats

• JPEG - Joint Photographic Experts Group
• PNG - Portable Network Graphics
• WebP - Google's modern image format
• GIF - Graphics Interchange Format
• BMP - Bitmap Image File
• ICO - Icon format
• TIFF - Tagged Image File Format
• AVIF - AV1 Image File Format
• HEIC - High Efficiency Image Container
• SVG - Scalable Vector Graphics

Request

Upload as multipart/form-data:

curl -X POST "https://spideriq.ai/api/v1/media/images/upload" \
  -H "Authorization: Bearer $CLIENT_TOKEN" \
  -F "file=@company-logo.png" \
  -F "folder=logos"

Parameters

Parameter	Type	Required	Description
file	file	Yes	Image file to upload
folder	string	No	Folder path (e.g., logos, images/products)

Response

Success Response

{
  "success": true,
  "file_id": "logos/20260119_143052_logo.png",
  "bucket": "client-cli-abc123",
  "key": "logos/20260119_143052_logo.png",
  "url": "https://media.spideriq.ai/client-cli-abc123/logos/20260119_143052_logo.png",
  "size": 102400,
  "content_type": "image/png",
  "detected_format": "PNG",
  "original_filename": "logo.jpg",
  "corrected_filename": "logo.png",
  "format_corrected": true
}

Response Fields

Field	Type	Description
success	boolean	Whether upload succeeded
file_id	string	Unique file identifier (path in bucket)
bucket	string	Client's bucket name
key	string	Full key/path in bucket
url	string	Public URL to access the file
size	integer	File size in bytes
content_type	string	MIME type (auto-detected from magic bytes)
detected_format	string	Detected image format (JPEG, PNG, WebP, etc.)
original_filename	string	Original filename as submitted
corrected_filename	string	Filename with correct extension
format_corrected	boolean	Whether filename was auto-corrected

Error Response (Invalid Image)

{
  "success": false,
  "error": "Invalid image format",
  "detail": "Content does not match any supported image format (JPEG, PNG, WebP, GIF, BMP, ICO, TIFF, AVIF, HEIC, SVG)"
}

Examples

Upload PNG with Wrong Extension

When a PNG file is uploaded with a .jpg extension:

curl -X POST "https://spideriq.ai/api/v1/media/images/upload" \
  -H "Authorization: Bearer $CLIENT_TOKEN" \
  -F "file=@real_png_file.jpg" \
  -F "folder=test"

Response:

{
  "success": true,
  "content_type": "image/png",
  "detected_format": "PNG",
  "original_filename": "real_png_file.jpg",
  "corrected_filename": "real_png_file.png",
  "format_corrected": true
}

Upload Non-Image File

Attempting to upload a PDF as an image:

curl -X POST "https://spideriq.ai/api/v1/media/images/upload" \
  -H "Authorization: Bearer $CLIENT_TOKEN" \
  -F "file=@document.pdf"

Response (400 Bad Request):

{
  "success": false,
  "error": "Invalid image format",
  "detail": "Content does not match any supported image format"
}

Use Cases

Logo Uploads

When accepting company logos from users, use this endpoint to ensure only valid images are stored.

User Avatars

Validate user-uploaded profile pictures before storing them.

Product Images

Ensure product catalog images are valid and have correct file extensions for browser compatibility.

Social Media Imports

When importing images from social media (Instagram, Facebook), formats may be misidentified. This endpoint auto-corrects them.

Comparison with General Upload

Feature	/media/images/upload	/media/files/upload
Validation	Strict - rejects non-images	Permissive - accepts any file
Auto-correction	Yes - fixes extensions	No - uses provided extension
Format detection	Returns detected_format	No format info
Use case	Images only	Any file type

tip

When to use which:

• Use /media/images/upload when you specifically need image validation
• Use /media/files/upload for general file uploads (PDFs, documents, etc.)