TikTok Slideshow - Hooked API Documentation

Create TikTok Slideshow

curl --request POST \
  --url https://api.hooked.so/v1/project/create/tiktok-slideshow \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "name": "Summer Collection 2024",
  "slides": [
    {
      "media": "media_summer_001",
      "texts": [
        {
          "text": "Summer Collection 2024",
          "x": 100,
          "y": 150,
          "width": 880,
          "height": 100,
          "fontSize": 52,
          "fontWeight": "700",
          "color": "#ffffff",
          "backgroundColor": "#ff6b6b",
          "textAlign": "center",
          "borderRadius": 12,
          "padding": 20,
          "opacity": 0.95
        },
        {
          "text": "Fresh & Stylish",
          "x": 200,
          "y": 280,
          "width": 680,
          "height": 70,
          "fontSize": 32,
          "fontWeight": "600",
          "color": "#ffed4e",
          "backgroundColor": "transparent",
          "textAlign": "center"
        }
      ]
    },
    {
      "media": "media_summer_002",
      "texts": [
        {
          "text": "100% Premium Cotton",
          "x": 150,
          "y": 1400,
          "width": 780,
          "height": 90,
          "fontSize": 36,
          "fontWeight": "600",
          "color": "#ffffff",
          "backgroundColor": "#000000",
          "textAlign": "center",
          "borderRadius": 10,
          "padding": 12,
          "opacity": 0.9
        }
      ]
    },
    {
      "media": "media_summer_003",
      "duration": 4,
      "texts": [
        {
          "text": "Shop Now!",
          "x": 200,
          "y": 1650,
          "width": 680,
          "height": 120,
          "fontSize": 56,
          "fontWeight": "800",
          "color": "#000000",
          "backgroundColor": "#ffed4e",
          "textAlign": "center",
          "borderRadius": 20,
          "padding": 25,
          "scale": 1.1
        }
      ]
    }
  ],
  "script": "Check out our amazing summer collection. Three new styles, perfect for the season. Get yours today!",
  "avatarId": "avatar_id",
  "voiceId": "tzX5paJ07p5hyWFcU3uG",
  "lipsyncModel": "pro",
  "audio": {
    "speed": 1,
    "stability": 0.5,
    "similarityBoost": 0.75,
    "style": 0,
    "useSpeakerBoost": true
  },
  "musicId": "upbeat_001",
  "webhook": "https://yoursite.com/webhook",
  "metadata": {
    "campaignId": "summer-2024",
    "collection": "beachwear",
    "variant": "A"
  }
}
'

{
  "success": true,
  "data": {
    "videoId": "vid_tiktok_abc123xyz",
    "projectId": "proj_tiktok_abc123xyz",
    "status": "STARTED"
  },
  "message": "TikTok Slideshow successfully created"
}

POST

project

create

tiktok-slideshow

Create TikTok Slideshow

curl --request POST \
  --url https://api.hooked.so/v1/project/create/tiktok-slideshow \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "name": "Summer Collection 2024",
  "slides": [
    {
      "media": "media_summer_001",
      "texts": [
        {
          "text": "Summer Collection 2024",
          "x": 100,
          "y": 150,
          "width": 880,
          "height": 100,
          "fontSize": 52,
          "fontWeight": "700",
          "color": "#ffffff",
          "backgroundColor": "#ff6b6b",
          "textAlign": "center",
          "borderRadius": 12,
          "padding": 20,
          "opacity": 0.95
        },
        {
          "text": "Fresh & Stylish",
          "x": 200,
          "y": 280,
          "width": 680,
          "height": 70,
          "fontSize": 32,
          "fontWeight": "600",
          "color": "#ffed4e",
          "backgroundColor": "transparent",
          "textAlign": "center"
        }
      ]
    },
    {
      "media": "media_summer_002",
      "texts": [
        {
          "text": "100% Premium Cotton",
          "x": 150,
          "y": 1400,
          "width": 780,
          "height": 90,
          "fontSize": 36,
          "fontWeight": "600",
          "color": "#ffffff",
          "backgroundColor": "#000000",
          "textAlign": "center",
          "borderRadius": 10,
          "padding": 12,
          "opacity": 0.9
        }
      ]
    },
    {
      "media": "media_summer_003",
      "duration": 4,
      "texts": [
        {
          "text": "Shop Now!",
          "x": 200,
          "y": 1650,
          "width": 680,
          "height": 120,
          "fontSize": 56,
          "fontWeight": "800",
          "color": "#000000",
          "backgroundColor": "#ffed4e",
          "textAlign": "center",
          "borderRadius": 20,
          "padding": 25,
          "scale": 1.1
        }
      ]
    }
  ],
  "script": "Check out our amazing summer collection. Three new styles, perfect for the season. Get yours today!",
  "avatarId": "avatar_id",
  "voiceId": "tzX5paJ07p5hyWFcU3uG",
  "lipsyncModel": "pro",
  "audio": {
    "speed": 1,
    "stability": 0.5,
    "similarityBoost": 0.75,
    "style": 0,
    "useSpeakerBoost": true
  },
  "musicId": "upbeat_001",
  "webhook": "https://yoursite.com/webhook",
  "metadata": {
    "campaignId": "summer-2024",
    "collection": "beachwear",
    "variant": "A"
  }
}
'

{
  "success": true,
  "data": {
    "videoId": "vid_tiktok_abc123xyz",
    "projectId": "proj_tiktok_abc123xyz",
    "status": "STARTED"
  },
  "message": "TikTok Slideshow successfully created"
}

Try it out! Use the API playground on the right to test the TikTok Slideshow endpoint directly.

Overview

TikTok Slideshow videos combine multiple images or video clips with text overlays, voiceovers, and music to create engaging social media content. Perfect for:

Storytelling with visual elements
Product showcases with descriptions
Educational content with slides
Social media posts with multiple images
Presentation-style videos

Each slide can contain up to 10 text elements with custom positioning, styling, and animations.

Endpoint

POST /v1/project/create/tiktok-slideshow

Required Fields

slides

array

required

Array of slide objects for the slideshow (1-50 slides). Each slide contains a media ID and optional text overlays.

Show Slide Object

media

string

required

Media ID from your media library. The media must already be uploaded to your account.

duration

number

default:3

Slide duration in seconds (1-10)

texts

array

Array of text elements for this slide (0-10 texts)

Show Text Object

text

string

required

Text content (1-500 characters)

number

default:0

X coordinate (must be non-negative and within canvas)

number

Y coordinate (must be non-negative and within canvas)

width

number

default:280

Width in pixels (minimum 10)

height

number

default:50

Height in pixels (minimum 10)

fontSize

number

default:16

Font size in pixels (8-200)

fontWeight

string

default:"600"

Font weight (e.g., “400”, “600”, “bold”)

color

string

default:"#ffffff"

Text color as hex code (e.g., “#ffffff”)

backgroundColor

string

default:"transparent"

Background color for text box

opacity

number

default:1

Text opacity (0-1)

rotation

number

default:0

Text rotation in degrees (-360 to 360)

scale

number

default:1

Text scale multiplier (0.1-10)

zIndex

number

default:1

Layer order (higher = on top)

textAlign

string

default:"center"

Text alignment: left, center, or right

fontFamily

string

default:"TikTok Display Medium"

Font family name

borderRadius

number

default:8

Border radius in pixels (0+)

padding

number

default:6

Text padding in pixels (0+)

maxWidth

number

default:80

Maximum width as percentage (0-100)

wordWrap

string

default:"break-word"

Word wrapping: normal or break-word

Optional Fields

name

string

Project name (1-100 characters). If not provided, a name will be auto-generated.

script

string

Voiceover script (max 10,000 characters). Required if using avatar/voice. Must be provided together with avatarId, voiceId, and lipsyncModel.

avatarId

string

Avatar ID from /v1/avatar/list (max 30 characters). Required if using voice. Must be provided together with script, voiceId, and lipsyncModel.

voiceId

string

Voice ID from /v1/voice/list (max 30 characters). Required if using avatar. Must be provided together with script, avatarId, and lipsyncModel.

lipsyncModel

string

Lipsync model quality. Required if using avatar/voice. Must be provided together with script, avatarId, and voiceId.

base: Standard quality, faster processing
pro: Higher quality, more accurate synchronization

audio

object

Voice audio settings. Used when generating voiceover. Default values are used if not provided.

Show Audio Settings Object

speed

number

Voice speed multiplier (0.7 to 1.2)

stability

number

Voice stability (0 to 1)

similarityBoost

number

Voice similarity boost (0 to 1)

style

number

default:0

Voice style exaggeration (0 to 1)

useSpeakerBoost

boolean

default:true

Enable speaker boost for clearer audio

musicId

string

Background music ID from /v1/music/list (max 30 characters)

webhook

string

Webhook URL for status notifications (max 500 characters, must be HTTPS)

metadata

object

Custom metadata object (max 5KB JSON)

Request Examples

Basic Slideshow

const response = await fetch('https://api.hooked.so/v1/project/create/tiktok-slideshow', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.HOOKED_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Product Launch',
    slides: [
      {
        media: 'media_001',
        duration: 3,
        texts: [
          {
            text: 'New Product Launch',
            x: 100,
            y: 800,
            width: 880,
            height: 120,
            fontSize: 48,
            fontWeight: '700',
            color: '#ffffff',
            backgroundColor: '#000000',
            textAlign: 'center',
            borderRadius: 8,
            padding: 10
          }
        ]
      },
      {
        media: 'media_002',
        duration: 3,
        texts: [
          {
            text: 'Available Now!',
            x: 150,
            y: 1650,
            width: 780,
            height: 100,
            fontSize: 42,
            fontWeight: '800',
            color: '#000000',
            backgroundColor: '#00ff00',
            textAlign: 'center',
            borderRadius: 15,
            padding: 8
          }
        ]
      }
    ]
  })
});

const data = await response.json();
console.log('Video ID:', data.data.videoId);
console.log('Project ID:', data.data.projectId);

Advanced with Avatar and Music

const createAdvancedSlideshow = async () => {
  const response = await fetch('https://api.hooked.so/v1/project/create/tiktok-slideshow', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.HOOKED_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Summer Collection 2024',
      script: 'Check out our amazing summer collection. Three new styles, perfect for the season. Get yours today!',
      avatarId: 'avatar_id',
      voiceId: 'tzX5paJ07p5hyWFcU3uG',
      lipsyncModel: 'pro',
      musicId: 'upbeat_001',
      audio: {
        speed: 1.0,
        stability: 0.5,
        similarityBoost: 0.75,
        style: 0.0,
        useSpeakerBoost: true
      },
      slides: [
        {
          media: 'media_summer_001',
          duration: 4,
          texts: [
            {
              text: 'Summer Collection 2024',
              x: 100,
              y: 150,
              width: 880,
              height: 100,
              fontSize: 52,
              fontWeight: '700',
              color: '#ffffff',
              backgroundColor: '#ff6b6b',
              textAlign: 'center',
              borderRadius: 12,
              padding: 20,
              opacity: 0.95
            },
            {
              text: 'Fresh & Stylish',
              x: 200,
              y: 280,
              width: 680,
              height: 70,
              fontSize: 32,
              fontWeight: '600',
              color: '#ffed4e',
              backgroundColor: 'transparent',
              textAlign: 'center'
            }
          ]
        },
        {
          media: 'media_summer_002',
          duration: 4,
          texts: [
            {
              text: '100% Premium Cotton',
              x: 150,
              y: 1400,
              width: 780,
              height: 90,
              fontSize: 36,
              fontWeight: '600',
              color: '#ffffff',
              backgroundColor: '#000000',
              textAlign: 'center',
              borderRadius: 10,
              padding: 12,
              opacity: 0.9
            }
          ]
        },
        {
          media: 'media_summer_003',
          duration: 4,
          texts: [
            {
              text: 'Shop Now!',
              x: 200,
              y: 1650,
              width: 680,
              height: 120,
              fontSize: 56,
              fontWeight: '800',
              color: '#000000',
              backgroundColor: '#ffed4e',
              textAlign: 'center',
              borderRadius: 20,
              padding: 25,
              scale: 1.1
            }
          ]
        }
      ],
      webhook: 'https://yoursite.com/webhook',
      metadata: {
        campaignId: 'summer-2024',
        collection: 'beachwear',
        variant: 'A'
      }
    })
  });

  return await response.json();
};

Response

{
  "success": true,
  "data": {
    "videoId": "vid_tiktok_abc123xyz",
    "projectId": "proj_tiktok_abc123xyz",
    "status": "STARTED"
  },
  "message": "TikTok Slideshow successfully created"
}

Webhook Notification

When your video is ready, we’ll POST to your webhook URL (if configured):

Webhook Payload

{
  "status": "COMPLETED",
  "data": {
    "videoId": "vid_tiktok_abc123xyz",
    "status": "COMPLETED",
    "url": "https://cdn.hooked.so/videos/abc123xyz.mp4",
    "shareUrl": "https://cdn.hooked.so/shared/abc123xyz.mp4",
    "metadata": {
      "projectId": "proj_tiktok_abc123xyz"
    }
  },
  "message": "Video completed"
}

Best Practices

Text Positioning

Canvas dimensions depend on aspect ratio. For 9:16 (1080x1920), ensure coordinates are within bounds.

Slide Duration

Keep slides between 2-5 seconds for optimal engagement.

Text Readability

Use high contrast colors and appropriate font sizes (24-48px) for mobile viewing.

Image Quality

Use high-resolution images (1080px width minimum) for best results.

Coordinate System

The coordinate system for text positioning varies by aspect ratio:

Aspect Ratio	Canvas Size	Description
`ratio_9_16`	1080 x 1920	Vertical (TikTok/Reels)
`ratio_16_9`	1920 x 1080	Horizontal (YouTube)
`ratio_1_1`	1080 x 1080	Square (Instagram)

Example: For 9:16 format (1080x1920), a text box with x: 100, y: 150, width: 880, height: 100 creates a full-width text near the top.

Error Handling

Error	Description	Solution
`slides: At least one slide is required`	Empty or missing slides array	Provide at least 1 slide
`slides: Cannot have more than 50 slides`	Too many slides	Limit to 50 slides maximum
`slides.0.media: String must contain at least 1 character(s)`	Missing media ID	Provide media ID for each slide
`slides.0.duration: Number must be between 1 and 10`	Invalid duration	Duration must be between 1 and 10 seconds
`slides.0.texts: Cannot have more than 10 text elements`	Too many texts per slide	Limit to 10 text elements per slide
`slides.0.texts.0.text: String must contain at least 1 character(s)`	Missing or empty text content	Provide text content (1-500 characters)
`slides.0.texts.0.x: Number must be greater than or equal to 0`	Invalid X position	X position must be within canvas bounds (0-canvas width)
`slides.0.texts.0.width: Number must be greater than or equal to 10`	Invalid width	Width must be at least 10 pixels
`slides.0.texts.0.height: Number must be greater than or equal to 10`	Invalid height	Height must be at least 10 pixels
`voiceId: Voice "X" not found`	Invalid voice ID	Use valid voice ID from `/v1/voice/list`
`avatarId: Avatar "X" not found`	Invalid avatar ID	Use valid avatar ID from `/v1/avatar/list`
`musicId: Music "X" not found`	Invalid music ID	Use valid music ID from `/v1/music/list`
`webhook: Must be a valid HTTPS URL`	Invalid webhook URL	Ensure webhook URL uses HTTPS
`Not enough credits`	Insufficient credits	Top up your account credits

Next Steps

List Videos

View all your created videos

Video Details

Check your video processing status

Webhooks Guide

Learn how to handle webhook notifications

UGC Ads

Create UGC-style advertisement videos

Authorizations

x-api-key

string

header

required

Body

application/json

slides

object[]

required

Array of slides (1-50 slides). Each slide contains a media ID and optional text elements.

Required array length: 1 - 50 elements

Show child attributes

name

string

Project name (1-100 characters). If not provided, a name will be auto-generated.

Required string length: 1 - 100

script

string

Voiceover script (max 10,000 characters). Required if using avatar/voice. Must be provided together with avatarId, voiceId, and lipsyncModel.

Maximum string length: 10000

avatarId

string

Avatar ID from /v1/avatar/list (max 30 characters). Required if using voice. Must be provided together with script, voiceId, and lipsyncModel.

Maximum string length: 30

voiceId

string

Voice ID from /v1/voice/list (max 30 characters). Required if using avatar. Must be provided together with script, avatarId, and lipsyncModel.

Maximum string length: 30

lipsyncModel

enum<string>

default:base

Lipsync model quality. Required if using avatar/voice. Must be provided together with script, avatarId, and voiceId.

Available options:

base,

pro

musicId

string

Music ID from /v1/music/list (max 30 characters)

Maximum string length: 30

audio

object

Voice audio settings. Used when generating voiceover. Default values are used if not provided.

Show child attributes

webhook

string

HTTPS URL for status notifications (max 500 characters)

Maximum string length: 500

metadata

object

Custom metadata object (max 5KB)

Response

TikTok Slideshow created successfully

success

boolean

data

object

Show child attributes

message

string

Talking Avatar UGC Ads

​Overview

​Endpoint

​Required Fields

​Optional Fields

​Request Examples

​Basic Slideshow

​Advanced with Avatar and Music

​Response

​Webhook Notification

​Best Practices

Text Positioning

Slide Duration

Text Readability

Image Quality

​Coordinate System

​Error Handling

​Next Steps

List Videos

Video Details

Webhooks Guide

UGC Ads

Authorizations

Body

Response

Overview

Endpoint

Required Fields

Optional Fields

Request Examples

Basic Slideshow

Advanced with Avatar and Music

Response

Webhook Notification

Best Practices

Coordinate System

Error Handling

Next Steps