🔥 imgbb-api

Upload images to imgbb, store the url locally with LMDB, and automatically rotate API keys to handle rate limits and quota exhaustion.

Features

• API Key Rotator — automatically rotates imgbb API keys to avoid rate limits and handle quota exhaustion
• Proxy-Ready — X-Actual-Url header for upstream proxy setups

Tech Stack

Category	Tool
Runtime	Node.js + Express
Storage	LMDB (embedded key-value)
Validation	Zod

API Endpoints

Method	Path	Description
GET	/	API info and version
GET	/health	Health check
POST	/files/upload	Upload image via imgbb and cache locally
GET	/files/:path	Retrieve stored image by path/slug

Upload Image

POST /files/upload
Content-Type: multipart/form-data

Field: image (file, required)
Field: slug (string, required) — unique identifier for this image

Success Response (201):

{
  "success": true,
  "message": "Image uploaded successfully",
  "data": {
    "id": "abc123",
    "title": "my-image.jpg",
    "url": "https://i.imgbb.com/abc123.jpg",
    "url_viewer": "https://ibb.co/abc123",
    "display_url": "https://i.imgbb.com/abc123.jpg",
    "width": 1920,
    "height": 1080,
    "size": 204800,
    "time": 1712000000,
    "expiration": 0,
    "image": {
      "filename": "my-image.jpg",
      "name": "my-image.jpg",
      "mime": "image/jpeg",
      "extension": "jpg",
      "url": "https://i.imgbb.com/abc123.jpg"
    },
    "thumb": { ... },
    "medium": { ... },
    "delete_url": "https://api.imgbb.com/1/delete/abc123/your_api_key"
  }
}

Retrieve Image

GET /files/:path

Returns the cached image metadata. Sets X-Actual-Url header with the original imgbb URL (useful for proxy setups).

Quick Start

Prerequisites

• Node.js 18+
• npm / yarn / pnpm
• imgbb API key — get one free

Installation

git clone https://github.com/LackFos/imgbb-api.git
cd imgbb-api
npm install

Configuration

Create a .env file (copy from .env.example):

PORT=3000
NODE_ENV=development
IMGBB_API_KEYS=api_key1,api_key2(optional),...

Running

## Development (hot reload with ts-node)
npm run dev

## Production (build first)
npm run build && npm start