NAV Navbar
shell

Introduction

Welcome to the Uploadfilter Nudity API!

You can view code examples in the dark area to the right.

Authentication

To authorize, you can use the following ways:

curl "https://api.uploadfilter.io/v1/status"
  -H "apikey: APIKEY"

curl "https://api.uploadfilter.io/v1/status?apikey=APIKEY"

curl "https://api.uploadfilter.io/v1/nudity" -F "apikey=APIKEY" -F "file=@file.jpg"

Uploadfilter uses API keys to allow access to the API. You can register a new API key at our developer portal.

Uploadfilter looks for the API key in a header that looks like the following (recommended, works with all requests):

apikey: APIKEY

For GET requests you can also use a URL parameter:

ex. https://api.uploadfilter.io/v1/nudity?apikey=APIKEY

For POST requests you can also use a form field:

apikey=APIKEY

Status

curl "https://api.uploadfilter.io/v1/nudity/status"
  -H "apikey: APIKEY"

The above command returns JSON structured like this:

{
  "remaining_requests": 1500
}

This endpoint retrieves the number of remaining requests.

Any of the requests below also return a x-ratelimit-remaining header with the number of the remaining requests.

HTTP Request

GET https://api.uploadfilter.io/v1/nudity/status

Checking an image

Response

file:

Key Description
name The file name.
url The remote url.
hash A SHA512 hash of the file.

result:

Key Description
value The classification from 0-1.
classification The classification as a string.
classification_code The classification as an int.

The API returns a classification in the schema above:

Anything value >= 0.2 or classification_code > 0 (so 1 and 2) is classified as not safe for work.

Checking a remote URL

curl "https://api.uploadfilter.io/v1/nudity"
  -H "apikey: APIKEY" -H "url: https://homepages.cae.wisc.edu/~ece533/images/arctichare.png"

curl "https://api.uploadfilter.io/v1/nudity?url=https://homepages.cae.wisc.edu/~ece533/images/arctichare.png"
  -H "apikey: APIKEY"

The above command returns JSON structured like this:

{
   "file":{
      "name": "arctichare.png",
      "url": "https://homepages.cae.wisc.edu/~ece533/images/arctichare.png",
      "hash": "4488f9c4e69f3e179881331ee5ea926f5e03f6805d64da66c9a98869f4286c301dcb9de3a7b3dae52df656fdce9d005831e410eac125c7b5df3bc4a12e321b13"
   },
   "result":{
      "value": 0.021482398733496666,
      "classification": "propably safe",
      "classification_code": 0
   }
}

HTTP Request

GET https://api.uploadfilter.io/v1/nudity

Query Parameters (via URL or Header)

Parameter Description
url The remote URL to check

Check an uploaded file

curl "https://api.uploadfilter.io/v1/nudity"
  -H "apikey: APIKEY" -F "file=@file.jpg"

The above command returns JSON structured like this:

{
   "file":{
      "hash": "4488f9c4e69f3e179881331ee5ea926f5e03f6805d64da66c9a98869f4286c301dcb9de3a7b3dae52df656fdce9d005831e410eac125c7b5df3bc4a12e321b13"
   },
   "result":{
      "value": 0.003030473366379738,
      "classification": "propably safe",
      "classification_code": 0
   }
}

HTTP Request

POST https://api.uploadfilter.io/v1/nudity

Query Parameters

Parameter Description
file The file to upload and check.

Errors

The Uploadfilter API uses the following error codes:

HTTP Error Code Meaning
400 Bad Request -- Your request is invalid.
403 Forbidden -- API key is wrong or you don't have enough rights to access it.
404 Not Found -- The route was not found.
500 Internal Server Error -- See below.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

The API returns errors in this template:

{
    "error": {
        "error_code": 1,
        "message": "Not authorized"
    }
}
Error Code Meaning
1 Not authorized - API key is wrong or you don't have enough rights to access it.
2 Rate limit exceeded -- You don't have enough requests.
3 Parameter not valid or not found.
100 Incorrect file format.
5000 Internal Server Error -- We had a problem with our server. Try again later.
5001 Internal Server Error -- We had a problem with our server. Try again later.
6000-6999 HTTP Errors while retrieving remote URLs. 6000 + HTTP Error Code = Error Code
7000 Error while computing NSFW value.
shell