ImageDB

Image Chunking Middleware for Golem DB

Getting Started API Demo GitHub

Store Large Images on Golem DB

A middleware that splits large images into safe-sized chunks, stores them on Golem DB, and serves them back as a single file. Perfect for NFT images, app assets, and media storage.

Get Started Try Demo

Why ImageDB?

Built for developers who need reliable image storage on Golem DB

Large File Support

Upload images up to 25MB. Files are automatically chunked into 64KB pieces that fit Golem DB limits.

Data Integrity

SHA-256 checksums ensure your images are retrieved exactly as uploaded, with full integrity verification.

Idempotent Uploads

Resume failed uploads and prevent duplicates with built-in idempotency keys and session management.

TTL Management

Set custom expiration times for your images. Default 7-day TTL for free tier, extendable with wallet mode.

Rate Limiting

Built-in quota management with 100MB storage and 10 uploads per day on the free tier.

Simple API

RESTful API with straightforward endpoints. Upload with POST, retrieve with GET, monitor with status endpoints.

Getting Started

Get up and running in minutes

1. Run with Docker

docker run -p 3000:3000 moonplkr/imagesdb:latest

2. Upload an Image

curl -X POST http://localhost:3000/media \
  -F "file=@image.png" \
  -H "Idempotency-Key: unique-key-123"

3. Retrieve Your Image

curl http://localhost:3000/media/YOUR_MEDIA_ID \
  -o retrieved-image.png

JavaScript SDK

Download our lightweight JavaScript SDK for easy integration

Download SDK (2KB) 
import ImageDB from './imagedb-sdk.js';

const client = new ImageDB('http://localhost:3000');

// Upload image
const result = await client.upload(file, {
  idempotencyKey: 'unique-key',
  ttlDays: 30
});

console.log('Media ID:', result.media_id);

// Retrieve image
const imageBlob = await client.get(result.media_id);
const imageUrl = URL.createObjectURL(imageBlob);

Response Format

{
  "media_id": "6bc95b27-1a5d-46e7-96e7-8edde7de5c70",
  "message": "Upload successful"
}

API Reference

Complete API documentation

POST /media

Upload an image file to the service

Headers

  • Idempotency-Key (optional) - Unique key for upload session
  • BTL-Days (optional) - Time to live in days (default: 7)

Form Data

  • file - Image file (PNG/JPEG, max 25MB)

Response

HTTP 200 OK
Content-Type: application/json

{
  "media_id": "uuid-string",
  "message": "Upload successful"
}
GET /media/{media_id}

Retrieve an uploaded image by its media ID

Response

HTTP 200 OK
Content-Type: image/png|image/jpeg
Content-Length: file-size
Content-Disposition: inline; filename="original-name.png"

[Binary image data]
GET /quota

Check current quota usage

Response

{
  "used_bytes": 1048576,
  "max_bytes": 104857600,
  "uploads_today": 3,
  "max_uploads_per_day": 10,
  "usage_percentage": "1.00"
}
GET /status/{idempotency_key}

Check upload session status

Response

{
  "media_id": "uuid-string",
  "completed": true,
  "chunks_received": 15,
  "total_chunks": 15
}

Try the Demo

Upload an image and see the chunking in action