Lummi API
Introduction
Lummi REST API offers tools for searching, retrieving, and customizing images, with features like filters, metadata, and advanced image effects.
Authentication
The API uses Bearer Token authentication. Developers must include their API key in the Authorization header of each request.
Example:
Authorization: Bearer YOUR_API_KEY
Rate Limiting
The API enforces rate limits to ensure fair usage and system stability.
- Default Limit: 10 requests per minute.
- Approved Applications: 100 requests per minute.
If the limit is exceeded, the API will return a 429 Too Many Requests response. To avoid disruptions:
- Optimize your API usage by batching requests where possible.
- Implement retry logic with exponential backoff to handle rate limit errors.
For higher limits, submit your application for review at https://www.lummi.ai/portal/developer.
Attribution Guidelines
To comply with usage guidelines and ensure proper credit is given to image creators, developers MUST include both image attribution and author attribution for each image displayed.
Image Attribution
When displaying images obtained through the Lummi API, you MUST provide a clickable link to the original source of the image. Use the attributionUrl property from the image object.
Developers MUST also attribute the original author of the image. Use the attributionUrl from the author object to create a clickable link to the author's profile.
Example
<div className="relative">
<img src={image.url} alt={image.name} />
<p className="absolute bottom-0 right-0">
Photo by
<a href={author.attributionUrl} target="_blank">
{author.name}
</a>
on
<a href={image.attributionUrl} target="_blank">
Lummi
</a>
</p>
</div>
General Best Practices for Attribution
- Visibility: The attribution should appear near the image, on top of it, or be visible on hover.
- Formatting: Use clear and clickable text links for all attribution URLs.
- Styling: Match the attribution style with your application’s design for a seamless user experience.
By adhering to these guidelines, developers ensure compliance with Lummi's terms of service and respect the work of creators.
Dynamic Image Transformations
Every image object includes a url property, which returns a direct URL to the image. You can customize the size and format of each image by adding specific query parameters to this URL. Below are the supported parameters and examples of their usage.
1. Resizing
You can resize an image by specifying one or both of the following parameters:
w(width): Sets the output width (in pixels).h(height): Sets the output height (in pixels).
When you provide both w and h, the image is fit within those dimensions while preserving its aspect ratio. In this case, only one dimension (either width or height) will match your parameters — unless the original aspect ratio is 1:1.
By default, the URL for each image may already include query parameters for width (w) and height (h). These default values ensure a certain size is always delivered unless you override them. You can modify or remove these parameters to fetch different sizes or the original image.
Examples
const imageUrl = new URL(image.url);
# Default size
imageUrl.toString(); # "https://assets.lummi.ai/assets/abc123?w=xxx&h=xxx&auto=format"
# Original size
imageUrl.searchParams.delete("w");
imageUrl.searchParams.delete("h");
imageUrl.toString(); # "https://assets.lummi.ai/assets/abc123?auto=format"
# Resize to a width of 400px
imageUrl.searchParams.set("w", "400");
imageUrl.searchParams.delete("h");
imageUrl.toString(); # "https://assets.lummi.ai/assets/abc123?w=400&auto=format"
# Resize to a height of 300px
imageUrl.searchParams.set("h", "300");
imageUrl.searchParams.delete("w");
imageUrl.toString(); # "https://assets.lummi.ai/assets/abc123?h=300&auto=format"
# Resize to both width 400px and height 300px (maintains aspect ratio)
imageUrl.searchParams.set("w", "400");
imageUrl.searchParams.set("h", "300");
imageUrl.toString(); # "https://assets.lummi.ai/assets/abc123?w=400&h=300&auto=format"
2. Format Conversion
You can also convert an image to a different format by removing the auto parameter and adding the fm parameter. Supported values for fm include jpg, png, avif, and webp.
By default, the URL for each image includes a query parameter for automatic format selection (auto). This ensures that the most optimal format is always delivered unless you override it. You can remove auto parameter to fetch a different format or the original one.
Examples
const imageUrl = new URL(image.url);
# Default (automatic) format
imageUrl.toString(); # "https://assets.lummi.ai/assets/abc123?auto=format&w=xxx&h=xxx"
# Original format
imageUrl.searchParams.delete("auto");
imageUrl.toString(); # "https://assets.lummi.ai/assets/abc123?w=xxx&h=xxx"
# Convert to `png` format
imageUrl.searchParams.delete("auto");
imageUrl.searchParams.set("fm", "png");
imageUrl.toString(); # "https://assets.lummi.ai/assets/abc123?fm=png&w=xxx&h=xxx"
Combining Parameters
You can mix-and-match the w, h, fm, and auto parameters to perform multiple transformations at once:
const imageUrl = new URL(image.url);
imageUrl.searchParams.delete("auto");
imageUrl.searchParams.set("fm", "avif");
imageUrl.searchParams.set("w", "400");
imageUrl.searchParams.set("h", "300");
imageUrl.toString(); # "https://assets.lummi.ai/assets/abc123?fm=avif&w=400&h=300"