Download Image Galleries and Create TikTok Slideshows

The gallery endpoints rely on gallery-dl being installed on the server. They are purpose-built for sites that host image collections — Reddit galleries, Pixiv, DeviantArt, Tumblr, and similar — as well as TikTok photo carousels, which gallery-dl can also download along with the carousel’s background audio. Before making gallery requests from your application, call GET /api/gallery/status to confirm gallery-dl is available. If available is false, all other gallery endpoints will return 503.

Progress events for gallery downloads and slideshow rendering are emitted on the progressId channel. Pass progressId before subscribing to GET /api/progress/{progressId} for real-time updates.

GET /api/gallery/status

Returns whether gallery-dl is installed and available on the server.

GET /api/gallery/status

Response

available

boolean

true if gallery-dl is installed and executable. false if it is missing — all other gallery endpoints will return 503 in this state.

curl Example

curl https://yoink.example.com/api/gallery/status
# {"available":true}

GET /api/gallery/metadata

Fetches metadata for an image gallery without downloading any files. Internally calls gallery-dl --dump-json --range 1-10 with a 30-second timeout.

GET /api/gallery/metadata?url={url}

Query Parameters

url

string

required

URL of the gallery page to inspect. Must be a site supported by gallery-dl.

Response

title

string

Gallery or post title, derived from gallery-dl metadata fields subcategory, category, or gallery. Falls back to "Image" if none are present.

imageCount

number

Number of images found (up to 10 from the metadata probe).

images

array

Array of up to 10 image preview objects. Each object contains:

filename (string) — bare filename without extension
extension (string) — file extension (e.g. jpg, png, webp)
url (string) — direct URL to the image

site

string

Hostname extracted from the source URL (e.g. reddit.com, pixiv.net). The www. prefix is stripped.

isGallery

boolean

Always true.

Show TikTok Carousel fields

These fields are only present when the URL is a TikTok photo post (isTikTokCarousel: true).

isTikTokCarousel

boolean

true when gallery-dl identifies the post as a TikTok image carousel.

hasAudio

boolean

true when gallery-dl found a playable audio URL in the TikTok post metadata.

musicTitle

string

Title of the background music track, if available.

musicDuration

number

Duration of the background music in seconds, if available.

Errors

Status	Meaning
`400`	Missing or invalid URL
`500`	gallery-dl failed or no images found
`503`	gallery-dl not installed on this server

curl Example

curl "https://yoink.example.com/api/gallery/metadata?url=https%3A%2F%2Fwww.reddit.com%2Fr%2Fearth%2Fcomments%2Fexample%2F"

GET /api/gallery/download

Downloads all images from a gallery. If the gallery contains a single image, streams that image directly with the correct MIME type. If it contains multiple images, assembles them into a ZIP archive and streams that.

GET /api/gallery/download?url={url}&progressId={id}&clientId={id}&filename={name}

Query Parameters

url

string

required

URL of the gallery to download.

progressId

string

Pre-generated UUID for SSE progress tracking. If omitted, one is generated internally.

clientId

string

Session identifier for per-client job limiting (max 3 concurrent).

filename

string

Filename hint for the downloaded file or ZIP archive (without extension). Defaults to the source hostname.

Response

Single image: streams the image binary with appropriate MIME type (image/jpeg, image/png, image/webp, etc.) and Content-Disposition: attachment. Multiple images: streams a ZIP archive (application/zip) containing all downloaded files, named <filename>.zip. Progress is emitted on the progressId SSE channel with messages like "Downloaded 5 images...".

Errors

Status	Meaning
`400`	Invalid URL
`429`	Too many concurrent jobs for this client
`500`	gallery-dl failed or no images downloaded
`503`	gallery-dl not installed on this server

curl Examples

Download gallery as ZIP
Download with progress tracking

curl -L -o gallery.zip \
  "https://yoink.example.com/api/gallery/download?url=https%3A%2F%2Fwww.reddit.com%2Fr%2Fearth%2Fcomments%2Fexample%2F&filename=earth_gallery"

PROGRESS_ID="$(python3 -c 'import uuid; print(uuid.uuid4())')"

# Subscribe to SSE progress in background
curl -N "https://yoink.example.com/api/progress/${PROGRESS_ID}" &

# Start download
curl -L -o gallery.zip \
  "https://yoink.example.com/api/gallery/download?url=https%3A%2F%2Fwww.reddit.com%2Fr%2Fearth%2Fcomments%2Fexample%2F&progressId=${PROGRESS_ID}"

GET /api/gallery/slideshow

Downloads a TikTok photo carousel (or any gallery with accompanying audio), then uses FFmpeg to assemble the images into an MP4 slideshow with crossfade transitions at 0.5-second duration. The output resolution adapts to the source images: portrait images produce 1080×1920 output; landscape images produce 1920×1080. If no audio is found in the downloaded files, the endpoint automatically falls back to the standard gallery download behaviour (streaming images or a ZIP).

GET /api/gallery/slideshow?url={url}&progressId={id}&clientId={id}&filename={name}

Query Parameters

Same as GET /api/gallery/download.

url

string

required

URL of the TikTok carousel or gallery with audio.

progressId

string

Pre-generated UUID for SSE progress tracking.

clientId

string

Session identifier for per-client job limiting.

filename

string

Output filename hint (without extension). The server appends .mp4.

Response

Streams an MP4 video (video/mp4) with Content-Disposition: attachment. The video is encoded with libx264 (CRF 23, fast preset) and AAC audio at 192 kbps.

FFmpeg has a hard 5-minute timeout for slideshow rendering. Very long carousels with many high-resolution images may time out. Split large carousels and use /api/gallery/download instead if this occurs.

curl Example

curl -L -o slideshow.mp4 \
  "https://yoink.example.com/api/gallery/slideshow?url=https%3A%2F%2Fwww.tiktok.com%2F%40example%2Fvideo%2F1234567890&filename=tiktok_carousel"

Core

Endpoints

Download Image Galleries and Create TikTok Slideshows

GET /api/gallery/status

Response

curl Example

GET /api/gallery/metadata

Query Parameters

Response

Errors

curl Example

GET /api/gallery/download

Query Parameters

Response

Errors

curl Examples

GET /api/gallery/slideshow

Query Parameters

Response

curl Example

Build docs developers (and LLMs) love

Core

Endpoints

Documentation Index

​GET /api/gallery/status

​Response

​curl Example

​GET /api/gallery/metadata

​Query Parameters

​Response

​Errors

​curl Example

​GET /api/gallery/download

​Query Parameters

​Response

​Errors

​curl Examples

​GET /api/gallery/slideshow

​Query Parameters

​Response

​curl Example

Build docs developers (and LLMs) love

GET /api/gallery/status

Response

curl Example

GET /api/gallery/metadata

Query Parameters

Response

Errors

curl Example

GET /api/gallery/download

Query Parameters

Response

Errors

curl Examples

GET /api/gallery/slideshow

Query Parameters

Response

curl Example