Introduction

Fluffle provides a publicly available API which can be used to integrate Fluffle into your own applications. Head over to the /exact-search-by-file endpoint to give it a try! Below you can find some more information about how the API works.

🚧
Using the legacy API still? You can find the documentation for that at https://fluffle.xyz/api/. Consider switching to the /exact-search-by-file endpoint!

User-Agent required

When you send the API a request, you must make your application identifiable by setting a custom User-Agent header. Preferably set a User-Agent in the format of applicationName/applicationVersion (by yourName on somePlatform), so something like Fluffle/main (by NoppesTheFolf on GitHub) would be correct.

Rate limits

Each client can have only one concurrent request processed at a time. Additional requests (up to 32) are enqueued. If a client exceeds the queue limit, the API responds with a 429 (Too Many Requests).

In practice, that means if you choose to parallelize the requests you make to Fluffle, you will only be able to get rid of some network overhead. This can still be significant depending on where you are calling Fluffle from, as Fluffle is hosted in Europe.

Shrinking images

If you want your requests to be handled faster, or are hitting the 4 MiB file limit per request, then you should consider shrinking the images before you send them to Fluffle. This will reduce the amount of data you need to send over, and more importantly, reduce the cost of processing the image server side.

It is recommended you shrink the image to a size where both its width and height don’t fall below 256 pixels. A few examples: 1920x1080 becomes 455x256, 1000x1000 becomes 256x256 and 700x1200 becomes 256x439. It's recommended to export the shrunken image as a PNG due to the format its lossless nature and support for transparency.

📘
You're not required to shrink the images you send to Fluffle. However, if you plan on sending lots of requests to Fluffle, then it would be appreciated if you did to relieve some load on Fluffle's side.

import io
from pprint import pprint
from PIL import Image
from requests import post

# Shrink the image
image = Image.open("critter.png")
width, height = image.size

def calculate_size(width, height, target):
    scale = target / min(width, height)
    return round(width * scale), round(height * scale)

image.thumbnail(calculate_size(width, height, 256))
buffer = io.BytesIO()
image.save(buffer, "png")

# And then reverse search the shrunken image
headers = {
    "User-Agent": "api-demo/na (by NoppesTheFolf on GitHub)"
}
files = {
    "file": buffer.getvalue()
}
data = {
    "limit": 8
}

response = post("https://api.fluffle.xyz/exact-search-by-file", headers=headers, files=files, data=data)
response.raise_for_status()
pprint(response.json())

Creating an API client

Fluffle's Search API has an OpenAPI specification hosted at https://api.fluffle.xyz/openapi/v1.json. You can use this OpenAPI specification to automatically generate a HTTP client using tools like OpenAPI Generator or Kiota. Generally IDEs also come with code generators built-in.

If you want to take a more lightweight approach, check out the code examples that can automatically be generated on the page of an endpoint like /exact-search-by-file.