TikTok Slideshow - SlideVid API Documentation

Create TikTok Slideshow

curl --request POST \
  --url https://api.slidevid.ai/v1/project/create/tiktok-slideshow \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "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",
  "musicId": "upbeat_001",
  "slides": [
    {
      "url": "https://your-cdn.com/summer1.jpg",
      "mediaId": "media_summer_001",
      "mediaType": "image",
      "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"
        }
      ],
      "isAIGenerated": false
    },
    {
      "url": "https://your-cdn.com/summer2.jpg",
      "mediaId": "media_summer_002",
      "mediaType": "image",
      "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
        }
      ],
      "isAIGenerated": false
    },
    {
      "url": "https://your-cdn.com/summer3.jpg",
      "mediaId": "media_summer_003",
      "mediaType": "image",
      "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
        }
      ],
      "isAIGenerated": false
    }
  ],
  "aspectRatio": "ratio_9_16",
  "language": "en",
  "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.slidevid.ai/v1/project/create/tiktok-slideshow \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "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",
  "musicId": "upbeat_001",
  "slides": [
    {
      "url": "https://your-cdn.com/summer1.jpg",
      "mediaId": "media_summer_001",
      "mediaType": "image",
      "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"
        }
      ],
      "isAIGenerated": false
    },
    {
      "url": "https://your-cdn.com/summer2.jpg",
      "mediaId": "media_summer_002",
      "mediaType": "image",
      "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
        }
      ],
      "isAIGenerated": false
    },
    {
      "url": "https://your-cdn.com/summer3.jpg",
      "mediaId": "media_summer_003",
      "mediaType": "image",
      "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
        }
      ],
      "isAIGenerated": false
    }
  ],
  "aspectRatio": "ratio_9_16",
  "language": "en",
  "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 slides for the slideshow (1-50 slides)

Show Slide Object

url

string

required

Public URL to the image or video file (must be valid URL)

mediaId

string

required

Unique media ID (max 30 characters)

mediaType

string

required

Media type: image or video

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

duration

number

default:3

Slide duration in seconds (0.1-60)

isAIGenerated

boolean

default:false

Whether the slide media was AI-generated

aspectRatio

string

required

Video aspect ratio:

ratio_9_16: Vertical (TikTok, Reels, Shorts) - Default
ratio_16_9: Horizontal (YouTube)
ratio_1_1: Square (Instagram)

language

string

required

Language code (exactly 2 characters, e.g., “en”, “es”)

Optional Fields

name

string

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

script

string

Voiceover script for the slideshow (max 10,000 characters). If provided, requires voiceId.

voiceId

string

Voice ID for narration from /v1/voice/list (max 30 characters). Required if script is provided.

avatarId

string

Avatar ID to appear in the video from /v1/avatar/list (max 30 characters)

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.slidevid.ai/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: [
      {
        url: 'https://your-cdn.com/product1.jpg',
        mediaId: 'media_001',
        mediaType: 'image',
        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
          }
        ],
        isAIGenerated: false
      },
      {
        url: 'https://your-cdn.com/product2.jpg',
        mediaId: 'media_002',
        mediaType: 'image',
        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
          }
        ],
        isAIGenerated: false
      }
    ],
    aspectRatio: 'ratio_9_16',
    language: 'en'
  })
});

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.slidevid.ai/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',
      musicId: 'upbeat_001',
      slides: [
        {
          url: 'https://your-cdn.com/summer1.jpg',
          mediaId: 'media_summer_001',
          mediaType: 'image',
          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'
            }
          ],
          isAIGenerated: false
        },
        {
          url: 'https://your-cdn.com/summer2.jpg',
          mediaId: 'media_summer_002',
          mediaType: 'image',
          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
            }
          ],
          isAIGenerated: false
        },
        {
          url: 'https://your-cdn.com/summer3.jpg',
          mediaId: 'media_summer_003',
          mediaType: 'image',
          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
            }
          ],
          isAIGenerated: false
        }
      ],
      aspectRatio: 'ratio_9_16',
      language: 'en',
      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.slidevid.ai/videos/abc123xyz.mp4",
    "shareUrl": "https://cdn.slidevid.ai/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.url: String must contain at least 1 character(s)`	Missing or empty slide URL	Provide valid HTTPS URL for each slide
`slides.0.mediaId: String must contain at least 1 character(s)`	Missing media ID	Provide unique media ID for each slide
`slides.0.mediaType: Invalid enum value`	Invalid media type	Use `image` or `video`
`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
`slides.0.duration: Number must be greater than or equal to 0.1`	Invalid duration	Duration must be between 0.1 and 60 seconds
`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)

Required array length: 1 - 50 elements

Show child attributes

aspectRatio

enum<string>

default:ratio_9_16

required

Video aspect ratio

Available options:

ratio_9_16,

ratio_16_9,

ratio_1_1

language

string

default:en

required

Language code (exactly 2 characters, e.g., en, es, fr)

Required string length: 2

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)

Maximum string length: 10000

voiceId

string

Voice ID from /v1/voice/list (max 30 characters)

Maximum string length: 30

avatarId

string

Avatar ID from /v1/avatar/list (max 30 characters)

Maximum string length: 30

musicId

string

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

Maximum string length: 30

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

Script to Video 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