Skip to main content

API Usages

Shotit API provides a HTTP interface for developers to interact with Shotit programmatically.

Using the API, you can develop programs such as: chat bots, browser plugins, video tagging / deduplication applications, games or whatever scripts that you need to know the video info from a screenshot.

My tip

Please replace api.yourendpoints.domain with your own shotit api service domain.

Search by image URL

curl "https://api.yourendpoints.domain/search?url=https://i.ibb.co/KGwVkqy/big-buck-bunny-10.png"

This method is the easiest if your image is already hosted somewhere in public. Otherwise, you must upload the image.

Search by image upload

curl --data-binary "@demo.jpg" https://api.yourendpoints.domain/search

Supported Content-Types are image/*, video/*, application/octet-stream and application/x-www-form-urlencoded

File size is limited to 25MB. The server would throw HTTP 413 Payload Too Large if it is too large.

Search by FORM POST (multipart/form-data)

<form
action="https://api.yourendpoints.domain/search"
method="POST"
enctype="multipart/form-data"
>
<input type="file" name="image" />
<input type="submit" />
</form>

File size is limited to 25MB. The server would throw HTTP 413 Payload Too Large if it is too large.

Cut Black Borders

shotit can detect black borders automatically and cut away unnecessary parts of the images that would affect search results accuracy. This is useful if your image is a screencap from a smartphone or iPad that contains black bars.

To enable black border crop, add cutBorders to the query string. e.g.

curl "https://api.yourendpoints.domain/search?cutBorders&url=https://i.ibb.co/KGwVkqy/big-buck-bunny-10.png"

Filter by imdb ID

You can search for a matching scene only in a particular anime by imdb ID. This is useful when you are certain about the anime name but cannot remember which episode.

First you have to look for the imdb ID of your anime from imdb first. Then add imdbID=1 to the query string. e.g. imdb ID of Cowboy Bebop is 1

curl "https://api.yourendpoints.domain/search?imdbID=1&url=https://i.ibb.co/KGwVkqy/big-buck-bunny-10.png"

Search Image Format

shotit support any media format that can be decoded by ffmpeg, including video and gif. When using video / gif, only the 1st frame would be extracted for searching.

Your image / video must be smaller than 25MB. Otherwise it would fail with HTTP 413 (Request Entity Too Large).

The recommended resolution is 640 x 360px, higher resolution doesn't yield better search results. The algorithm is also resistant to jpeg artifacts, so you don't have to use uncompressed formats like png.

Response format

{
"frameCount": 745506,
"error": "",
"result": [
{
"imdb": 99939,
"filename": "Nekopara - OVA (BD 1280x720 x264 AAC).mp4",
"episode": null,
"from": 97.75,
"to": 98.92,
"similarity": 0.9440424588727485,
"video": "https://media.shotit/video/99939/Nekopara%20-%20OVA%20(BD%201280x720%20x264%20AAC).mp4?t=98.335&now=1653892514&token=xxxxxxxxxxxxxx",
"image": "https://media.shotit/image/99939/Nekopara%20-%20OVA%20(BD%201280x720%20x264%20AAC).mp4.jpg?t=98.335&now=1653892514&token=xxxxxxxxxxxxxx"
}
]
}
FieldsMeaningValue
frameCountTotal number of frames searchednumber
errorError messagestring
resultSearch results (see table below)Array of Objects
FieldsMeaningValue
imdbThe matching imdb ID or imdb infonumber or object
filenameThe filename of file where the match is foundstring
episodeThe extracted episode number from filenameRefer to aniep
fromStarting time of the matching scene (seconds)number
toEnding time of the matching scene (seconds)number
similaritySimilarity compared to the search imagenumber (0 to 1)
videoURL to the preview video of the matching scenestring
imageURL to the preview image of the matching scenestring
  • Results are sorted from most similar to least similar
  • Similarity lower than 90% are most likely incorrect results. It's up to you to judge what is a match and what is just visually similar.
  • episode can be null because it is just a result of parsing the filename with aniep

By default, it only returns imdb ID for search results. To get more anime info, make a second query to imdb API. If you need chinese-translated titles, take a look at imdb-chinese

Error codes

Example Error response

{
"error": "Concurrency limit exceeded"
}
HTTP StatusPossible Causes
400Invalid image url / Failed to process image / OpenCV: Failed to detect and cut borders
402Search quota depleted / Concurrency limit exceeded
403Invalid API key
405Method Not Allowed
500Internal Server Error
503Search queue is full / Database is not responding
504Server is overloaded

the "error" value is empty string when there's no error

Media Preview

The url you obtained from image and video from search result is served by shotit-media

These urls would expire in 300 seconds (5 minutes)

It can generate image or video preview of 3 sizes by appending size=l (large), size=m (medium, default) or size=s (small) at the end of the url. e.g.

https://media.shotit/image/xxx/xxxxxx.mp4.jpg?t=0&now=1653892514&token=xxxxx&size=s
https://media.shotit/video/xxx/xxxxxx.mp4?t=0&now=1653892514&token=xxxxx&size=s

For video preview, it can generate a video with sound (default), or a muted video by appending mute to the end of url. e.g.

https://media.shotit/video/xxx/xxxxxx.mp4?t=0&now=1653892514&token=xxxxx&mute
https://media.shotit/video/xxx/xxxxxx.mp4?t=0&now=1653892514&token=xxxxx&size=s&mute

The media server would detect boundaries of the scene and cut videos at the boundaries. You cannot specify the length of video preview.

Do not attempt to parse and modify the urls except documented above. The urls are not permanent and may change without notice.

Error codes

HTTP StatusMeaning
200OK
400Invalid url param
403Invalid token
404File not found
410Token Expired
>=500Server Error (Maybe broken video or overloaded)

/me

Let you check the search quota and limit for your account (with API key) or IP address (without API key).

curl "https://api.yourendpoints.domain/me"

Example Response

{
"id": "127.0.0.1",
"priority": 0,
"concurrency": 1,
"quota": 1000,
"quotaUsed": 43
}
FieldsMeaningValue
idIP address (guest) or email address (user)string
priorityYour priority in search queuenumber (0: lowest)
concurrencyNumber of parallel search requests you can makenumber
quotaSearch quota you have for this monthnumber
quotaUsedSearch quota you have used this monthnumber

Using the API with API Keys

If you have an API Key that grants you more search quota and limits, put your API key in either HTTP header x-trace-key or query string key.

When searching with API Keys, it would count towards your account quota and limits. When searching without an API Key, you search as guests using your IP address.

Using API Keys in HTTP header

curl -H "x-trace-key: xxxxxxxxxxxxxxxxxxxxxxx" "https://api.yourendpoints.domain/me"

Using API Keys in query string

If you're lazy and don't mind your API Key being exposed to browser history or logs. Just put your key in key in query string

curl "https://api.yourendpoints.domain/me?key=xxxxxxxxxxxxxxxxxxxxxxx"