Skip to main content

Overview

TikTok Slideshow videos tell a story with a series of images or clips, each with its own text on top. They work well for product showcases, tutorials, lists and social media content. Optionally an AI avatar narrates the slideshow. Each slide is { media, texts?, duration? }:
  • media (required): a media ID from your Hooked library (image or video). An ID that does not exist or belongs to another team answers 400.
  • texts (optional): up to 10 text boxes. Each one is { text, x, y, width, height, fontSize }; the font, colors and the rest of the look come from the slideshow template.
  • duration (optional): seconds on screen, 0.1 to 60, default 3. With an avatar the narration sets the length and durations are relative weights between slides.
Up to 50 slides per project.

Basic Slideshow

Each slide’s media is the ID of an image or video in your media library. Add files with Upload Media or Import Media from URL and wait until they are COMPLETED.

Slideshow Narrated by an Avatar

Send avatarId (from GET /v1/avatar/list) and script together and the avatar narrates the slideshow, cut out from its background in a corner of the screen. The avatar speaks in its own voice: there is no voiceId or voice settings to send. language sets the language it speaks (detected from the script when omitted). A script without an avatarId (or the other way round) answers 400.
Managed teams pay 7 credits for a slideshow. With an avatar it is 7 credits plus 100 per started 15 seconds of the script (estimated at about 2.5 words per second). The estimate is charged when the project is created and refunded if it fails.A slideshow without an avatar needs only an OpenRouter key for teams in bring-your-own-keys mode; with an avatar it also needs Gemini (the avatar’s clips) and Bria (cutting it out). No ElevenLabs key is needed. A missing key answers 402 with code: "missing_credentials" and the list in missingProviders, before anything is created or charged.

Getting the Video

The create call answers right away with { success: true, data: { projectId, status }, message }. Then wait for your webhook or poll the project:
The render starts as soon as the project is completed; video fills in a minute or two later.
Send an Idempotency-Key header to retry safely: if a request times out or answers 5xx, sending it again with the same key and body returns the first answer instead of creating (and charging) the project twice.

Tips for TikTok Slideshows

Keep slides short: 1-10 seconds per slide works best for engagement (default: 3 seconds)
Pick backgrounds the text reads on: the text style comes from the template, so choose media where it stays readable
Positions are canvas pixels: For 9:16 the canvas is 1080x1920, and each text box must fit inside it
Add narration: Send avatarId and script together to have an avatar talk over the slides
Media IDs only: Each slide only needs the media ID - the media must already be in your library

Canvas Dimensions by Aspect Ratio

aspectRatio (default ratio_9_16) sets the canvas the text boxes are measured against:

Text Positioning Guide

x, y, width, height and fontSize are in pixels of the final canvas. x/y are the top-left corner of the box. The box must fit the canvas (x + width ≤ canvas width and y + height ≤ canvas height), or the request answers 400. width and height must be at least 40 px and fontSize between 32 and 800 px.
Always send the four box fields: a box without them gets the editor’s default placement.

Text Fields

Only these fields are used. The font, colors, background and alignment of the text come from the slideshow template, so other style fields change nothing.

Common Use Cases

  • Product Launches: Showcase multiple product angles with descriptions
  • Tutorials: Step-by-step guides with visual aids
  • Before/After: Transformations with text explanations
  • Lists: “Top 5” or “Best of” content with images
  • Stories: Narrative content with sequential images
  • Testimonials: Customer reviews with photos

Handling the Webhook Response

Webhooks are signed: check the Hooked-Signature header as shown in Webhooks. Answer 200 quickly; Hooked tries 3 times with a 10-second timeout.