POST
https://spideriq.ai
/
api
/
v1
/
media
/
images
/
upload
Upload Image (Validated)
curl --request POST \
  --url https://spideriq.ai/api/v1/media/images/upload \
  --header 'Authorization: Bearer <token>'

​
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.
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

ParameterTypeRequiredDescription
filefileYesImage file to upload
folderstringNoFolder 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

FieldTypeDescription
successbooleanWhether upload succeeded
file_idstringUnique file identifier (path in bucket)
bucketstringClient’s bucket name
keystringFull key/path in bucket
urlstringPublic URL to access the file
sizeintegerFile size in bytes
content_typestringMIME type (auto-detected from magic bytes)
detected_formatstringDetected image format (JPEG, PNG, WebP, etc.)
original_filenamestringOriginal filename as submitted
corrected_filenamestringFilename with correct extension
format_correctedbooleanWhether 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

When accepting company logos from users, use this endpoint to ensure only valid images are stored.
Validate user-uploaded profile pictures before storing them.
Ensure product catalog images are valid and have correct file extensions for browser compatibility.
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
ValidationStrict - rejects non-imagesPermissive - accepts any file
Auto-correctionYes - fixes extensionsNo - uses provided extension
Format detectionReturns detected_formatNo format info
Use caseImages onlyAny file type
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.)