API reference

Slideshows

Generate, list, fetch, and export TikTok slideshows.

1 min readLast updated May 17, 2026 Edit this page

Slideshows are the main output of ViralSlides. Each one is a 6-slide deck plus marketing assets, owned by exactly one app.

GET/v0/api/v1/slideshowsAPI key or session

List slideshows in your organization, newest first.

Parameters

Name	In	Type	Description
page	query	integer	1-indexed page (default 1).
limit	query	integer	Items per page, max 100 (default 20).
app_id	query	string	Filter to one app.
status	query	string	QUEUED \| RENDERING \| READY \| FAILED.

Response

json

{
  "success": true,
  "data": [
    {
      "_id": "ss_01HQ...",
      "app_id": "app_01HQ...",
      "hook_id": "hk_01HQ...",
      "hook_text_snapshot": "POV: you found the meditation app that...",
      "status": "READY",
      "language": "en",
      "template_set": "default",
      "createdAt": "2026-05-17T11:55:00.000Z"
    }
  ],
  "page": 1,
  "limit": 20,
  "total": 42
}

POST/v0/api/v1/apps/:id/slideshowsAPI key or session

Generate a niche-template slideshow for the given app. The app's niche drives which templates are available; the default image source provides the slide imagery. Subject to your plan's slideshows-per-month quota.

Parameters

Name	In	Type	Description
id*	path	string	Target app id.
template_key*	body	string	Niche template key, e.g. "trending-designs-monthly". See GET /v0/api/v1/niches for the catalog.
variable_overrides	body	object	Optional explicit values for template variables (e.g. {"aesthetic":"Coquette"}). LLM picks any missing fields.

Request

Request bodyjson

{
  "template_key": "trending-designs-monthly",
  "variable_overrides": { "month": "May", "year": "2026" }
}

Response

202 Acceptedjson

{
  "success": true,
  "body": { "slideshow_id": "ss_01HQ..." }
}

cURL

Terminalbash

curl -X POST https://api.viralslides.app/v0/api/v1/apps/app_01HQ.../slideshows \
  -H "Authorization: Bearer vs_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "template_key": "trending-designs-monthly"
  }'

TypeScript / JS

Node.jstypescript

const res = await fetch("https://api.viralslides.app/v0/api/v1/apps/app_01HQ.../slideshows", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VIRALSLIDES_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ template_key: "trending-designs-monthly" }),
})
const { body } = await res.json()
console.log(body.slideshow_id)

Errors

Status	Code	Description
400	TEMPLATE_KEY_REQUIRED	Body missing template_key.
400	NICHE_NOT_REGISTERED	The app's niche is not in the niche catalog.
400	NO_IMAGE_SOURCE	The app has no image source configured.
402	QUOTA_EXCEEDED	You've hit slideshows_per_month for this billing cycle.
404	APP_NOT_FOUND	The target app id is not in your organization.

GET/v0/api/v1/slideshows/:idAPI key or session

Fetch a slideshow by id, including all slides and marketing assets.

Parameters

Name	In	Type	Description
id*	path	string	Slideshow id.

Response

json

{
  "success": true,
  "body": {
    "_id": "ss_01HQ...",
    "app_id": "app_01HQ...",
    "status": "READY",
    "slides": [ /* 6 slides */ ],
    "marketing_assets": [ /* caption, hashtags, ctas */ ]
  }
}

Errors

Status	Code	Description
404	SLIDESHOW_NOT_FOUND	Not in your organization.

GET/v0/api/v1/slideshows/:id/zipAPI key or session

Build (or fetch a cached) ZIP bundle of slides + marketing assets and return a download URL. The URL is valid for ~1 hour.

Parameters

Name	In	Type	Description
id*	path	string	Slideshow id.

Response

json

{
  "success": true,
  "data": {
    "url": "https://cdn.viralslides.app/orgs/.../export.zip",
    "expires_at": "2026-05-17T13:00:00.000Z",
    "cached": false
  }
}

cURL

Terminalbash

curl https://api.viralslides.app/v0/api/v1/slideshows/ss_01HQ.../zip \
  -H "Authorization: Bearer vs_live_..."

TypeScript / JS

Node.jstypescript

const res = await fetch(`https://api.viralslides.app/v0/api/v1/slideshows/${id}/zip`, {
  headers: { Authorization: `Bearer ${process.env.VIRALSLIDES_API_KEY}` },
})
const { data } = await res.json()
// data.url is a public CDN URL good for ~1 hour
window.location.href = data.url

Errors

Status	Code	Description
404	SLIDESHOW_NOT_FOUND	Not in your organization.
500	ZIP_GENERATION_FAILED	Internal error packing the ZIP. Retry safe.
500	ZIP_UPLOAD_FAILED	Storage upload failed. Retry safe.

ZIP contents

Each ZIP contains slides/01.png … 06.png, marketing/caption.txt, marketing/hashtags.txt, marketing/cta.txt, metadata.json, and README.txt. ZIPs are cached in R2 — if the slideshow hasn't changed since the last build, you get the cached URL back.