Image Format
Converter API

Overview

Professional-grade image format converter supporting over 18 input formats including camera RAW files (CR2, NEF, ARW), vector formats (SVG, EPS, AI, PDF), modern formats (HEIC, WebP, AVIF), and legacy formats. Features automatic format detection using magic bytes, intelligent color space conversion, and optimized output settings for each target format.

Authentication

All API requests require authentication using these headers:

X-API-Key: your_api_key
X-API-Secret: your_api_secret

Get API Keys

Follow these steps to obtain your API credentials:

Endpoints

Health Check

Returns the status of the image converter service and available dependencies.

Success Response (200)

{
  "status": "ok",
  "database": true,
  "supported_categories": ["raw", "vector", "raster"],
  "missing_dependencies": [],
  "max_file_size_mb": 50
}

Get Supported Formats

Retrieve all supported input/output formats and the conversion matrix.

Success Response (200)

{
  "input_formats": {
    "raw": ["cr2", "cr3", "nef", "arw", "raf", "dng", "rw2", "orf", "srw", "pef", "mrw", "mos", "erf", "3fr", "nrw", "rwl", "kdc"],
    "vector": ["svg", "eps", "ai", "pdf", "ps", "wmf", "emf"],
    "raster": ["jpg", "jpeg", "png", "gif", "bmp", "tiff", "tif", "webp", "heic", "heif", "jxl", "avif", "jp2", "j2k", "ico", "psd", "tga", "exr", "hdr", "dds", "pcx", "ppm", "pgm", "pbm", "pnm", "xbm", "xpm", "jif", "jfif"]
  },
  "output_formats": {
    "common": ["png", "jpg", "jpeg", "webp", "gif", "bmp"],
    "professional": ["tiff", "tif"],
    "specialized": ["ico", "jp2", "j2k"]
  },
  "features": {
    "automatic_detection": true,
    "magic_bytes": true,
    "format_optimization": true,
    "color_space_conversion": true,
    "transparency_handling": true,
    "quality_control": true
  }
}

Detect Image Format

Detect image format without conversion. Upload the file as multipart/form-data.

Request Parameters

• file: File, Image file to detect

Success Response (200)

{
  "filename": "example.jpg",
  "category": "raster",
  "format": "jpg",
  "size_bytes": 123456
}

Convert Image

Convert image to the target format. Upload the file as multipart/form-data.

Request Parameters

• file: File, Image file to convert
• target_format: string, Target format (png, jpg, webp, etc.)

Success Response (200)

Returns the converted image file directly in the response body.

cURL Example

curl -X POST "https://odivora.com/api/v1/img_converter/convert" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -F "file=@/path/to/image.jpg" \
  -F "target_format=png" \
  --output converted.png

Python SDK Example

Complete Python client with format detection, conversion, and a user guide.

#!/usr/bin/env python3
"""
Image Format Converter API Client
Replace 'Your_API_Key_Here' and 'Your_API_Secret_Here' with your credentials.
"""

import requests
import os
from pathlib import Path

# Configuration
BASE_URL = "https://odivora.com/api/v1"
API_KEY = "your_api_key_here"  # Replace with your actual API key
API_SECRET = "your_api_secret_here"  # Replace with your actual API secret
TIMEOUT = 60  # seconds

headers = {
    "X-API-Key": API_KEY,
    "X-API-Secret": API_SECRET
}

# Supported format categories from UI (20 formats total)
FORMAT_CATEGORIES = {
    'common': {
        'name': 'Common Formats',
        'description': 'Standard image formats for everyday use',
        'formats': {
            'png': 'PNG - Lossless compression',
            'jpg': 'JPEG / JPG - Compressed photos',
            'jpeg': 'JPEG - Alternative name',
            'webp': 'WEBP - Modern web format',
            'gif': 'GIF - Animated support',
            'bmp': 'BMP - Uncompressed bitmap'
        }
    },
    'professional': {
        'name': 'Professional Formats',
        'description': 'High-quality formats for professional work',
        'formats': {
            'tiff': 'TIFF - High quality archival',
            'tif': 'TIF - Alternative TIFF format'
        }
    },
    'specialized': {
        'name': 'Specialized & Extended Formats',
        'description': 'Specialized formats for specific use cases',
        'formats': {
            'ico': 'ICO - Windows icons',
            'jp2': 'JPEG2000 (JP2) - Advanced compression',
            'j2k': 'JPEG2000 (J2K) - Alternative',
            'heic': 'HEIC - Apple format',
            'tga': 'TGA - Graphics format',
            'dds': 'DDS - DirectDraw Surface',
            'pcx': 'PCX - Legacy format',
            'ppm': 'PNM (PPM) - Portable pixmap',
            'xbm': 'XBM - X11 bitmap',
            'hdr': 'HDR - High Dynamic Range',
            'pgm': 'PNM (PGM) - Grayscale',
            'pbm': 'PNM (PBM) - Black & White'
        }
    }
}

def detect_image_format(image_path):
    """Detect the format of an image file"""
    try:
        with open(image_path, "rb") as f:
            files = {"file": (Path(image_path).name, f, "application/octet-stream")}
            response = requests.post(f"{BASE_URL}/api/v1/img_converter/detect", headers=headers, files=files)
            
            print(f"Detect Status Code: {response.status_code}")
            print(f"Detect Response: {response.text}")
            
            if response.status_code == 200:
                return response.json()
            else:
                print(f"Detection failed: {response.text}")
                return None
    except Exception as e:
        print(f"Detection exception: {str(e)}")
        return None

def convert_image(image_path, target_format):
    """Convert an image to target format"""
    try:
        with open(image_path, "rb") as f:
            files = {"file": (Path(image_path).name, f, "application/octet-stream")}
            data = {"target_format": target_format}
            response = requests.post(f"{BASE_URL}/api/v1/img_converter/convert", headers=headers, files=files, data=data)
            
            print(f"Convert Status Code: {response.status_code}")
            print(f"Convert Response Headers: {dict(response.headers)}")
            
            if response.status_code == 200:
                # Save converted image to the same folder with timestamp
                import datetime
                timestamp = datetime.datetime.now().strftime("%Y%m%d_%H%M%S")
                original_name = Path(image_path).stem
                output_path = os.path.join(Path(image_path).parent, f"{original_name}_converted_{timestamp}.{target_format}")
                
                with open(output_path, "wb") as output_file:
                    output_file.write(response.content)
                
                print(f"Converted image saved to: {output_path}")
                return output_path
            else:
                print(f"Conversion failed: {response.text}")
                return None
    except Exception as e:
        print(f"Conversion exception: {str(e)}")
        return None

def list_supported_formats():
    """List all supported formats by category with descriptions"""
    print("=== Supported Format Categories ===")
    for category, info in FORMAT_CATEGORIES.items():
        print(f"\n{category.upper()} - {info['name']}")
        print(f"Description: {info['description']}")
        print(f"Formats ({len(info['formats'])}):")
        for fmt, description in info['formats'].items():
            print(f"  - {fmt.upper()}: {description}")
    print(f"\nTotal supported formats: {sum(len(info['formats']) for info in FORMAT_CATEGORIES.values())}")

# Example usage - User Guide
if __name__ == "__main__":
    # Path to the image file - replace with your actual paths
    image_path = r"C:\Users\Solomon\Downloads\API test\image1.png"  # replace with your actual paths
    
    print(f"Image Format Converter API - User Guide")
    print(f"=====================================")
    print(f"Testing with: {image_path}")
    
    # Step 1: Show all available categories and formats
    print(f"\nSTEP 1: Available Categories and Formats")
    list_supported_formats()
    
    # Step 2: Detect current image format
    print(f"\nSTEP 2: Detecting current image format")
    detection = detect_image_format(image_path)
    if detection:
        print(f"Detected format: {detection}")
    else:
        print("Detection failed")
    
    # STEP 3: CHOOSE YOUR CONVERSION
    print(f"\nSTEP 3: Choose Your Conversion")
    print("="*50)
    
    # OPTION 1: Professional Format - TIFF (High Quality)
    print("OPTION 1: Professional Format")
    print("Category: Professional Formats")
    print("Format: TIFF - High quality archival")
    # Uncomment below to use this option:
    # converted_file = convert_image(image_path, "tiff")
    # if converted_file:
    #     print(f"Successfully converted to: {converted_file}")
    
    # OPTION 2: Common Format - WebP (Modern Web Format)
    print("\nOPTION 2: Common Format")
    print("Category: Common Formats")
    print("Format: WEBP - Modern web format")
    # Uncomment below to use this option:
    converted_file = convert_image(image_path, "webp")
    if converted_file:
        print(f"Successfully converted to: {converted_file}")
    else:
        print("Conversion failed")
    
    # OPTION 3: Specialized Format - HEIC (Apple Format)
    print("\nOPTION 3: Specialized Format")
    print("Category: Specialized & Extended Formats")
    print("Format: HEIC - Apple format")
    # Uncomment below to use this option:
    # converted_file = convert_image(image_path, "heic")
    # if converted_file:
    #     print(f"Successfully converted to: {converted_file}")
    
    print(f"\n=== Guide Complete ===")
    print("To use a different conversion, uncomment the desired option above")

cURL Examples

Quick copy-paste cURL commands for every endpoint.

curl -X GET "https://odivora.com/api/v1/img_converter/health" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

curl -X POST "https://odivora.com/api/v1/img_converter/detect" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -F "file=@/path/to/image.jpg"

curl -X POST "https://odivora.com/api/v1/img_converter/convert" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -F "file=@/path/to/image.jpg" \
  -F "target_format=png" \
  --output converted.png

Supported Formats

Error Codes

Limitations