API documentation

Fluffle provides a publicly available HTTP-based API which can be used to integrate Fluffle into your own applications. Please read the next chapter (preprocessing) carefully before looking at anything else as its crucial for interacting with the API.

Preprocessing

Fluffle has been built with performance in mind. One of the many optimizations applied to Fluffle is having the client shrink the image before sending it over. This has the possibility of dramatically reducing the size of the request (great for users with slow connections), but also hugely impacts the cost of processing the image server side. You should implement this optimization in your application too if you want to make use of Fluffle its API.

At the moment, it is recommend you shrink the image to a size where both its width and height don’t fall below 256 pixels as this seems to work nicely. 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. On the subject of transparency, Fluffle has a standardized way of dealing with it. If the image you want to send over has transparency, you must not flatten it before sending it to Fluffle.

Reverse searching

To reverse search an image, you need to send Fluffle a POST-request encoded using multipart/form-data. You must make your application identifiable by setting a custom User-Agent. It's recommended you use the following format for the User-Agent header: 'applicationName/applicationVersion (by yourName on somePlatform)'. So for example, 'Fluffle/1.2.3 (by NoppesTheFolf on Twitter)', would be a correct. If your project is open source, then instead of your personal contact details, it would preferred to instead link to where said project is hosted (like GitHub). Please keep in mind that providing your contact details is only a recommendation, you don't have to if you don't want to. These will only be used if your application is causing trouble so that we can resolve any issues it might be causing.

Parameters

Example request

Alright, that’s enough documentation… let’s see some code! The code below is a small script written in Python which preprocesses the image “fluffy-critter.png” and reverse searches it using Fluffle its API. You can use this as reference material for implementing Fluffle its API in your programming language of choice.

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

# Preprocess the image as per Fluffle its documentation
image = Image.open("fluffy-critter.png")
width, height = image.size


def calculate_size(width, height, target):
    def calculate_size(d1, d2, d1_target): return round(d1_target / d1 * d2)

    if width > height:
        return calculate_size(height, width, target), target

    return target, calculate_size(width, height, target)


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

# And then reverse search the preprocessed image
headers = {
    "User-Agent": "api-demo/1.0 (by NoppesTheFolf on Twitter)"
}
files = {
    "file": buffer.getvalue()
}
data = {
    "platforms": [
        "fur affinity",
        "furry network"
    ],
    "limit": 8
}

response = post("https://api.fluffle.xyz/v1/search", headers=headers, files=files, data=data).json()
pprint(response)

Responses

The chapter below describes all of the responses you can get from the API. Please note that there is no guarantee that you will always receive a JSON structure as a response on errors because the API is running behind Cloudflare.

Your request was valid and could therefore be processed. The submitted image has been compared against all (specified) platforms and the results said comparison yielded are embedded in the body of the request.

Example response

{
  "stats": {
    "count": 18311838,
    "elapsedMilliseconds": 402
  },
  "results": [
    {
      "id": 1344062,
      "score": 0.966796875,
      "match": "exact",
      "platform": "e621",
      "location": "https://e621.net/posts/546281",
      "isSfw": true,
      "thumbnail": {
        "width": 300,
        "centerX": 0,
        "height": 400,
        "centerY": 37,
        "location": "https://static.fluffle.xyz/file/fluffle/0e2c770cf4a9eccb7f16570f5586aa9d.jpg"
      },
      "credits": [
        {
          "id": 123,
          "name": "lycanruff"
        }
      ]
    }
  ]
}

The request you sent over to Fluffle is invalid. The response body will tell you what you did wrong and how you can resolve the issue. For example, requesting Fluffle to search for images on a non-existent platform will cause such a response. These errors can always be prevented by properly implementing the API. They are only meant to give guidance to developers.

{
  "code": "VALIDATION_FAILED",
  "message": "One or more validation errors occurred.",
  "errors": {
    "platforms": [
      "Platform with the name 'some platform name' either doesn't exist or is not supported."
    ]
  }
}

The submitted image its area exceeded the 16MP limit.

{
  "code": "AREA_TOO_LARGE",
  "message": "An informational message for developers."
}

There are a couple of variations of this response due to Fluffle running behind Cloudflare. You can get a JSON one generated by Fluffle if your image exceed the 4 MiB limit and a HTML one by Cloudflare if you exceed their limit. You shouldn't have to handle this response if you just make sure the image you send over isn't larger than 4 MiB. If you do wish to handle the response, then you should use the status code.

{
  "code": "FILE_TOO_LARGE",
  "message": "An informational message for developers."
}

The image embedded in the request couldn't be processed due to it not being encoded in a supported format. Currently only JPEG and non-animated PNG and WebP are supported. Support for AVIF might be added in a future release.

{
  "code": "UNSUPPORTED_FILE_TYPE",
  "message": "An informational message for developers."
}

The image embedded in the request got recognized as being encoded in a supported format, but it couldn't be read in said format. Therefore, the image couldn't be processed and is deemed corrupt.

{
  "code": "CORRUPT_FILE",
  "message": "An informational message for developers."
}

Something unexpected happened which made the server unable to fulfil the request. The response will contain a so-called trace ID which may prove useful when trying to determine the root cause of the error. You may choose to contact the grumpy folf - don’t worry, I won’t bite - who made Fluffle so that the issue can be solved. Please make sure you can provide the trace ID sent along with the request if you choose to do so!

{
  "code": "KABOOM",
  "message": "Now you have become death, the destroyer of applications.",
  "traceId": "12345678-01"
}

Fluffle is unable to fulfil your request at this moment. This can be the case due to a variety of reasons. One being for example that the server assigned to process your request has restarted (unexpectedly) and is still getting ready. It should be noted that this response is extremely rare as downtime is limited as much as possible, of course. It is worth retrying the request after some time as it will succeed eventually. You should consider waiting at least 10 seconds before giving it another shot.

{
  "code": "UNAVAILABLE",
  "message": "An informational message for developers."
}

Due to Fluffle running behind Cloudflare, there are various other status codes you might want to deal with. A complete list of status codes used by Cloudflare can be found on their support page. It's a good idea to treat the 502, 504, 521, 522, 523 and 524 status codes as transient errors (and are therefore worth retrying), just like 503 responses. Keep in mind that Cloudflare doesn't give you a JSON response.