Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/coah80/yoink/llms.txt

Use this file to discover all available pages before exploring further.

Yoink’s gallery feature uses gallery-dl to download image collections from a wide range of platforms. A single image is returned directly; multiple images are packed into a ZIP archive. For TikTok photo carousels that include a backing audio track, Yoink can render the images into an MP4 slideshow with smooth crossfade transitions.
The gallery feature requires gallery-dl to be installed on the server. Check availability before displaying the gallery UI to users.

​
Checking availability

Before making any gallery requests, confirm that gallery-dl is present on the server: 
GET /api/gallery/status

{ "available": true }
If available is false, gallery downloads are not supported on this instance. Preview the contents of a gallery URL before downloading. The metadata endpoint returns up to 10 preview images, a total image count, a title, and the source site — all within a 30-second timeout: 
GET /api/gallery/metadata?url=<url>
Example response: 
{
  "title": "Landscape Photography",
  "imageCount": 42,
  "images": [
    { "filename": "001_sunset", "extension": "jpg", "url": "https://..." },
    { "filename": "002_forest", "extension": "png", "url": "https://..." }
  ],
  "site": "pixiv.net",
  "isGallery": true
}
For TikTok photo carousels, the metadata response includes additional fields: 
{
  "isTikTokCarousel": true,
  "hasAudio": true,
  "musicTitle": "Original Sound - creator",
  "musicDuration": 15.0
}
Use isTikTokCarousel and hasAudio to decide whether to offer the slideshow download option. 
GET /api/gallery/download?url=<url>&progressId=<id>&clientId=<id>&filename=<name>
ParameterDescription
urlGallery URL to download
progressIdOptional — correlate with SSE progress stream
clientIdOptional — per-client concurrency tracking
filenameOptional — override the output filename (without extension)
What you get back:
  • Single image — the image file is returned directly with the appropriate MIME type (image/jpeg, image/png, image/webp, etc.)
  • Multiple images — a ZIP archive containing all downloaded files, named after the gallery hostname if no title is available
Gallery files inside the ZIP follow the naming pattern gallery-dl writes: 
001_filename.jpg
002_filename.jpg
003_filename.png
…
When a TikTok post contains multiple images and a backing audio track, use the slideshow endpoint instead to receive a single MP4 video: 
GET /api/gallery/slideshow?url=<url>&progressId=<id>&clientId=<id>&filename=<name>
Yoink performs the following steps to build the slideshow:
1

Download images and audio

gallery-dl downloads all images and the audio track from the TikTok carousel into a temporary directory.
2

Analyse dimensions and duration

ffprobe reads the audio duration and the dimensions of the first image. If the image is taller than it is wide, a 1080×1920 (portrait) canvas is used; otherwise 1920×1080 (landscape).
3

Render the slideshow

ffmpeg builds a filter graph that:
  • Scales each image to fit the canvas with black letterboxing
  • Applies xfade=transition=fade with a 0.5-second crossfade between each slide
  • Distributes slide timing evenly across the audio duration
  • Mixes the original audio track at 192 kbps AAC
The output is an H.264 MP4 at CRF 23 with the fast preset.
If no audio file is found, the slideshow endpoint falls back to the standard gallery download and returns a ZIP instead.

​
Supported platforms

gallery-dl supports a large number of platforms beyond TikTok. Some notable examples:

Pixiv

Artwork, manga, and illustration galleries with series support.

Flickr

Public photo albums and photostreams.

Twitter / X

Tweet image attachments and media timelines.

Instagram

Posts, reels, and story highlights.

DeviantArt

Galleries and individual deviation pages.

And many more

Danbooru, Gelbooru, ArtStation, Tumblr, Reddit, and hundreds of others.
Refer to the gallery-dl supported sites list for the complete catalogue.

​
Authentication with cookies

If your server has a cookies file configured, Yoink automatically passes it to gallery-dl via the --cookies flag. This allows downloading from platforms that require a logged-in session (such as private Pixiv content or Twitter/X with age-restricted media).

​
Progress tracking

Gallery downloads emit SSE progress events on the standard progress stream. Events report how many images have been downloaded so far: 
{
  "status": "downloading",
  "message": "Downloaded 12 images...",
  "downloadedCount": 12
}
The slideshow render additionally emits a processing event while ffmpeg is running.
For large galleries, the metadata endpoint previews only the first 10 images. The actual download will fetch the complete gallery — check imageCount in the metadata response to set user expectations before starting the download.

Build docs developers (and LLMs) love

Get started for freeTalk to us