# Lummi API Documentation ## Overview Lummi REST API offers tools for searching, retrieving, and customizing images, with features like filters, metadata, and advanced image effects. **Base URL:** `https://api.lummi.ai/v1` ## Authentication The API uses Bearer Token authentication. Include your API key in the `Authorization` header of each request: ``` Authorization: Bearer YOUR_API_KEY ``` ## Rate Limiting - **Default Limit**: 10 requests per minute - **Approved Applications**: 100 requests per minute If the limit is exceeded, the API returns a `429 Too Many Requests` response. For higher limits, submit your application for review at [https://www.lummi.ai/portal/developer](https://www.lummi.ai/portal/developer). ## Attribution Guidelines **REQUIRED**: You must include both image attribution and author attribution for each image displayed. ### Image Attribution Provide a clickable link to the original source using the `attributionUrl` property from the image object. ### Author Attribution Attribute the original author using the `attributionUrl` from the author object. ### Example Implementation ```html
{image.name}

Photo by {author.name} on Lummi

``` ## Dynamic Image Transformations Every image includes a `url` property that can be customized with query parameters. ### Resizing Parameters - `w` (width): Sets output width in pixels - `h` (height): Sets output height in pixels When both are provided, the image fits within those dimensions while preserving aspect ratio. ### Format Conversion - Remove `auto` parameter and add `fm` parameter - Supported formats: `jpg`, `png`, `avif`, `webp` ### Examples ```javascript const imageUrl = new URL(image.url); // Original size imageUrl.searchParams.delete("w"); imageUrl.searchParams.delete("h"); // Resize to width 400px imageUrl.searchParams.set("w", "400"); imageUrl.searchParams.delete("h"); // Convert to PNG format imageUrl.searchParams.delete("auto"); imageUrl.searchParams.set("fm", "png"); // Combined transformations imageUrl.searchParams.set("fm", "avif"); imageUrl.searchParams.set("w", "400"); imageUrl.searchParams.set("h", "300"); ``` ## API Endpoints ### List Images `GET /images` List images with optional filters. **Query Parameters:** - `imageType`: `photo`, `illustration`, `3d` - `orientation`: `square`, `horizontal`, `vertical` - `color`: Color in HEX format (e.g., `#00ff00`) - `categories`: Comma-separated category IDs - `luminance`: `dark`, `neutral`, `bright` - `numberOfPeople`: Number with optional operators (`gt`, `gte`, `lt`, `lte`) - `free`: Boolean (default: `false`) - `orderBy`: `featuredScore`, `trendScore`, `createdAt` (default: `featuredScore`) - `orderDirection`: `asc`, `desc` (default: `desc`) - `page`: Page number (min: 1) - `perPage`: Page size (min: 1, max: 20) ### Random Images `GET /images/random` Get random images with optional filters. **Query Parameters:** - `limit`: Number of images to return (min: 1, max: 20) - Same filter parameters as `/images` endpoint ### Search Images `GET /images/search` Search images by query string. **Query Parameters:** - `query`: Search term (required, min: 1 character) - Same filter and pagination parameters as `/images` endpoint ### Random Search Results `GET /images/search/random` Get random images from search results. **Query Parameters:** - `query`: Search term (required) - `limit`: Number of images to return (min: 1, max: 20) - Same filter parameters as `/images` endpoint ### Get Specific Image `GET /images/{id}` Retrieve a specific image by its UUID. ### Download Image `POST /images/{id}/download` Download an image with optional effects and resolution settings. **Request Body:** ```json { "effects": { /* ImageEffects object */ }, "resolution": "original", // original, small, medium, large, xlarge, ultra "format": "png" // png, jpg } ``` **Note:** `large`, `xlarge`, and `ultra` resolutions are Pro features. ### Similar Images `GET /images/{id}/similar` Find images similar to a specific image. **Query Parameters:** - Same filter and pagination parameters as `/images` endpoint ### Random Similar Images `GET /images/{id}/similar/random` Get random images similar to a specific image. **Query Parameters:** - `limit`: Number of images to return (min: 1, max: 20) - Same filter parameters as `/images` endpoint ### Collection Images `GET /collections/{id}/images` List images in a specific collection. **Path Parameters:** - `id`: Collection ID (7-character alphanumeric string) **Query Parameters:** - Same filter and pagination parameters as `/images` endpoint ### Random Collection Images `GET /collections/{id}/images/random` Get random images from a collection. **Query Parameters:** - `limit`: Number of images to return (min: 1, max: 20) - Same filter parameters as `/images` endpoint ### List Categories `GET /categories` Retrieve all available image categories. ### Generate Profile Background (Enterprise) `POST /images/generator/profile` Generate background images for user profiles. This is an Enterprise feature. **Request Body:** ```json { "about": "Profile description (job title, location, interests, etc.)", "prompt": "Optional prompt to customize generation", "count": 3, // Number of images (1-3, default: 1) "aspectRatioHint": "16:9", // Preferred aspect ratio "style": "URL or predefined option", "person": { "image": "URL to person's image" } } ``` ## New Features & Capabilities (2025) ### Create Similar (Pro Feature) Lummi has introduced a "Create Similar" feature that allows you to generate new versions of existing images while maintaining the original style. This feature: - Uses Stable Diffusion Style API to extract stylistic elements (colors, textures, composition) - Allows optional text prompts to customize variations (e.g., "smile", "looking away", "cat") - Supports aspect ratio customization - Generates up to 3 variations per request - Works with photos, illustrations, and 3D images **Note:** This feature may be available through the API for Pro users, though specific endpoints are not yet documented in the public API reference. ### Video Generation (Beta - Pro Feature) Lummi is testing video generation capabilities that can: - Convert static images into short dynamic clips - Currently works with homepage photos only - 3D images and illustrations support coming soon - Higher resolution outputs planned for future releases - Available for Pro users in beta ### Styles Feature A new "Styles" feature provides nine unique style transformations: - Pixel art - Comic style - Sketch style - And 6 additional style options ### Enhanced Image Effects Recent updates include: - **Auto-Reframe**: Improved reframing that applies consistently across similar images - **Background Removal**: Now available in Webflow and Figma plugins - **Quick Edits**: Adjust brightness, contrast, and saturation before downloading ### Daily Curated Collections - Fresh inspiration from daily curated collections - Mix of photos, illustrations, and 3D designs - Some images transition to Pro status, encouraging timely downloads ## Response Format ### Image Object Structure ```json { "id": "123e4567-e89b-12d3-a456-426614174000", "name": "string", "slug": "cool-cat", "description": "string", "detailedDescription": "string", "vibeDescription": "string", "url": "https://assets.lummi.ai/assets/abc123", "attributionUrl": "https://www.lummi.ai/photo/abc", "author": { "id": "123e4567-e89b-12d3-a456-426614174000", "username": "string", "name": "string", "avatar": "https://assets.lummi.ai/assets/abc123", "attributionUrl": "https://www.lummi.ai/creator/abc", "role": "user" }, "imageType": "photo", // photo, illustration, 3d "contentType": "image/png", "orientation": "square", // square, horizontal, vertical "width": 123, "height": 123, "aspectRatio": 1.23, "size": 123, "luminance": 0.12, "numberOfPeople": 123, "tags": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "name": "string", "slug": "cool-cat" } ], "categories": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "name": "string", "slug": "cool-cat" } ], "colorPalette": { "color_name": { "hex": "#00ff00", "weight": 0.12 } }, "colorGroups": ["string"], "dominantColorGroup": "string", "dominantColorWeight": 0.12, "focalPositionX": 0.12, "focalPositionY": 0.12, "focalWidth": 0.12, "focalHeight": 0.12, "focalZone": "top_left", "pro": true, "free": true, "video": true, "transparent": true, "discoverable": true, "unsafe": false, "featuredScore": 123, "trendScore": 12.3, "viewCount": 123, "downloadCount": 123, "collections": 123, "searchAppearances": 123, "createdAt": "2025-05-23T22:04:43.787Z", "updatedAt": "2025-05-23T22:04:43.787Z", "featuredAt": null, "becameDiscoverableAt": null, "blurhash": "string", "generation": { "aiModel": "sd", "batchId": "123e4567-e89b-12d3-a456-426614174000", "parentId": "123e4567-e89b-12d3-a456-426614174000", "rootId": "123e4567-e89b-12d3-a456-426614174000", "prompt": "string", "aspectRatio": "9:21", "imageType": "photo", "shotType": "string", "trend": "string" } } ``` ### Paginated Response Format ```json { "data": [ /* Array of image objects */ ], "meta": { "totalCount": 123 } } ``` ## Error Responses - `400`: Bad request - `402`: Payment required (Enterprise features) - `403`: Forbidden (private collections) - `404`: Not found - `429`: Too many requests (rate limit exceeded) - `500`: Internal server error ## Best Practices 1. **Attribution**: Always include proper attribution for images and authors 2. **Rate Limiting**: Implement retry logic with exponential backoff 3. **Optimization**: Batch requests where possible 4. **Caching**: Cache images and metadata appropriately 5. **Error Handling**: Handle all error responses gracefully 6. **Image Optimization**: Use appropriate format and size parameters for your use case