Image Handling

Okasie automatically mirrors and optimizes images from your servers to ensure fast loading and consistent display across the platform.

How It Works

When you submit a listing with image URLs:

Validation - We verify each URL is accessible
Download - Images are downloaded from your server
Optimization - Images are resized and compressed
CDN Hosting - Optimized images are served from our CDN
Caching - Original URLs are cached for future updates

Your Server → Okasie API → Image Processing → Supabase Storage → CDN

Submitting Images

Single Listing

Include images in the images array when upserting:

await fetch(`https://www.okasie.be/api/external/v1/listings/${ref}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Volkswagen Golf 2020',
    price: 24500,
    images: [
      'https://your-server.com/cars/vw-golf-front.jpg',
      'https://your-server.com/cars/vw-golf-side.jpg',
      'https://your-server.com/cars/vw-golf-interior.jpg',
      'https://your-server.com/cars/vw-golf-dashboard.jpg'
    ],
    // ... other fields
  })
});

Bulk Upsert

Same format for bulk operations:

const items = [
  {
    externalReference: 'VW-001',
    title: 'Volkswagen Golf',
    images: [
      'https://your-server.com/cars/vw-golf-1.jpg',
      'https://your-server.com/cars/vw-golf-2.jpg'
    ]
  },
  {
    externalReference: 'BMW-001',
    title: 'BMW 3 Series',
    images: [
      'https://your-server.com/cars/bmw-3-1.jpg',
      'https://your-server.com/cars/bmw-3-2.jpg'
    ]
  }
];

Image Requirements

Requirement	Specification
Formats	JPEG, PNG, WebP
Minimum size	800 x 600 pixels
Maximum size	20 MB per image
Maximum count	50 images per listing
URL accessibility	Must be publicly accessible

Images behind authentication or requiring cookies will fail to download. Ensure your image URLs are publicly accessible.

Image Processing

Automatic Optimization

Okasie automatically:

Resizes to multiple dimensions (thumbnail, preview, full)
Compresses using modern codecs (WebP, AVIF)
Strips metadata for privacy
Generates placeholders for lazy loading

Generated Sizes

Size	Dimensions	Use Case
Thumbnail	150 x 100	Search results grid
Preview	400 x 300	Listing cards
Gallery	800 x 600	Detail page gallery
Full	Original (max 2000px)	Lightbox view

Image Order

The first image in your array becomes the primary/cover image:

images: [
  'https://example.com/cover.jpg',     // Primary image
  'https://example.com/angle-1.jpg',   // Gallery image 2
  'https://example.com/angle-2.jpg',   // Gallery image 3
  'https://example.com/interior.jpg',  // Gallery image 4
]

Use your best exterior shot as the first image - it’s displayed in search results and listing previews.

Updating Images

Full Replacement

Send the complete new image array to replace all images:

// Old: ['img1.jpg', 'img2.jpg', 'img3.jpg']
// New: ['new1.jpg', 'new2.jpg']

await upsertListing(ref, {
  images: ['new1.jpg', 'new2.jpg']
});
// Result: Only new1.jpg and new2.jpg

Adding Images

Include all existing images plus new ones:

// Existing: ['img1.jpg', 'img2.jpg']
// Add: ['img3.jpg', 'img4.jpg']

await upsertListing(ref, {
  images: ['img1.jpg', 'img2.jpg', 'img3.jpg', 'img4.jpg']
});

Reordering Images

Simply send the images in the new desired order:

// Move img3 to front
await upsertListing(ref, {
  images: ['img3.jpg', 'img1.jpg', 'img2.jpg']
});

Caching Behavior

URL-Based Caching

Okasie caches images by URL. If you update an image on your server without changing the URL, add a cache-busting parameter:

// Force re-download with timestamp
images: [
  `https://your-server.com/car.jpg?v=${Date.now()}`
]

CDN Cache Duration

Cache Type	Duration
Browser	1 year
CDN Edge	30 days
API response	Real-time

Error Handling

Common Image Errors

Error	Cause	Solution
`IMAGE_FETCH_FAILED`	URL not accessible	Check URL accessibility
`IMAGE_TOO_LARGE`	Exceeds 20 MB	Compress before upload
`IMAGE_INVALID_FORMAT`	Unsupported format	Convert to JPEG/PNG/WebP
`IMAGE_TOO_SMALL`	Below 800x600	Use higher resolution

Partial Success

Image processing doesn’t block listing creation. If some images fail:

{
  "data": {
    "listingId": "abc-123",
    "status": "active",
    "imagesProcessed": 8,
    "imagesFailed": 2,
    "failedImages": [
      {
        "url": "https://example.com/broken.jpg",
        "error": "IMAGE_FETCH_FAILED"
      }
    ]
  }
}

Best Practices

Consistent Naming

Use consistent, descriptive filenames that help with debugging

HTTPS Only

Always use HTTPS URLs for security

Stable URLs

Keep image URLs stable; avoid temporary signed URLs

Pre-optimize

Compress images before sending to reduce processing time

CDN URLs

After processing, images are available at:

https://[supabase-storage-url]/listings/[listing-id]/[image-hash].webp

The images array in listing responses contains these CDN URLs, not your original URLs.

Getting Started

Guides

Image Handling

Image Handling

How It Works

Submitting Images

Single Listing

Bulk Upsert

Image Requirements

Image Processing

Automatic Optimization

Generated Sizes

Image Order

Updating Images

Full Replacement

Adding Images

Reordering Images

Caching Behavior

URL-Based Caching

CDN Cache Duration

Error Handling

Common Image Errors

Partial Success

Best Practices

Consistent Naming

HTTPS Only

Stable URLs

Pre-optimize

CDN URLs

​Image Handling

​How It Works

​Submitting Images

​Single Listing

​Bulk Upsert

​Image Requirements

​Image Processing

​Automatic Optimization

​Generated Sizes

​Image Order

​Updating Images

​Full Replacement

​Adding Images

​Reordering Images

​Caching Behavior

​URL-Based Caching

​CDN Cache Duration

​Error Handling

​Common Image Errors

​Partial Success

​Best Practices

Consistent Naming

HTTPS Only

Stable URLs

Pre-optimize

​CDN URLs

Image Handling

How It Works

Submitting Images

Single Listing

Bulk Upsert

Image Requirements

Image Processing

Automatic Optimization

Generated Sizes

Image Order

Updating Images

Full Replacement

Adding Images

Reordering Images

Caching Behavior

URL-Based Caching

CDN Cache Duration

Error Handling

Common Image Errors

Partial Success

Best Practices

CDN URLs