> ## Documentation Index
> Fetch the complete documentation index at: https://docs.slidevid.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# TikTok Slideshow
> Create TikTok-style slideshow videos with text overlays and custom positioning
**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
Array of slides for the slideshow (1-50 slides)
Public URL to the image or video file (must be valid URL)
Unique media ID (max 30 characters)
Media type: `image` or `video`
Array of text elements for this slide (0-10 texts)
Text content (1-500 characters)
X coordinate (must be non-negative and within canvas)
Y coordinate (must be non-negative and within canvas)
Width in pixels (minimum 10)
Height in pixels (minimum 10)
Font size in pixels (8-200)
Font weight (e.g., "400", "600", "bold")
Text color as hex code (e.g., "#ffffff")
Background color for text box
Text opacity (0-1)
Text rotation in degrees (-360 to 360)
Text scale multiplier (0.1-10)
Layer order (higher = on top)
Text alignment: `left`, `center`, or `right`
Font family name
Border radius in pixels (0+)
Text padding in pixels (0+)
Maximum width as percentage (0-100)
Word wrapping: `normal` or `break-word`
Slide duration in seconds (0.1-60)
Whether the slide media was AI-generated
Video aspect ratio:
* `ratio_9_16`: Vertical (TikTok, Reels, Shorts) - **Default**
* `ratio_16_9`: Horizontal (YouTube)
* `ratio_1_1`: Square (Instagram)
Language code (exactly 2 characters, e.g., "en", "es")
***
## Optional Fields
Project name (1-100 characters). If not provided, a name will be auto-generated.
Voiceover script for the slideshow (max 10,000 characters). If provided, requires `voiceId`.
Voice ID for narration from `/v1/voice/list` (max 30 characters). Required if `script` is provided.
Avatar ID to appear in the video from `/v1/avatar/list` (max 30 characters)
Background music ID from `/v1/music/list` (max 30 characters)
Webhook URL for status notifications (max 500 characters, must be HTTPS)
Custom metadata object (max 5KB JSON)
***
## Request Examples
### Basic Slideshow
```javascript theme={null}
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
```javascript theme={null}
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
```json Success Response theme={null}
{
"success": true,
"data": {
"videoId": "vid_tiktok_abc123xyz",
"projectId": "proj_tiktok_abc123xyz",
"status": "STARTED"
},
"message": "TikTok Slideshow successfully created"
}
```
```json Error Response - Validation Error theme={null}
{
"success": false,
"message": "slides: At least one slide is required"
}
```
```json Error Response - Invalid Text Position theme={null}
{
"success": false,
"message": "slides.0.texts.0.x: Number must be greater than or equal to 0"
}
```
```json Error Response - Voice Not Found theme={null}
{
"success": false,
"message": "voiceId: Voice \"invalid_voice\" not found."
}
```
***
## Webhook Notification
When your video is ready, we'll POST to your webhook URL (if configured):
```json Webhook Payload theme={null}
{
"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
Canvas dimensions depend on aspect ratio. For 9:16 (1080x1920), ensure coordinates are within bounds.
Keep slides between 2-5 seconds for optimal engagement.
Use high contrast colors and appropriate font sizes (24-48px) for mobile viewing.
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
View all your created videos
Check your video processing status
Learn how to handle webhook notifications
Create UGC-style advertisement videos
## OpenAPI
````yaml POST /v1/project/create/tiktok-slideshow
openapi: 3.0.0
info:
title: SlideVid API
version: 1.0.0
description: AI Video Generation API
servers:
- url: https://api.slidevid.ai
security:
- ApiKeyAuth: []
paths:
/v1/project/create/tiktok-slideshow:
post:
tags:
- Videos
summary: Create TikTok Slideshow
description: >-
Create TikTok-style slideshow videos with text overlays and custom
positioning
operationId: createTikTokSlideshow
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- slides
- aspectRatio
- language
properties:
name:
type: string
description: >-
Project name (1-100 characters). If not provided, a name
will be auto-generated.
minLength: 1
maxLength: 100
slides:
type: array
description: Array of slides (1-50 slides)
minItems: 1
maxItems: 50
items:
type: object
required:
- url
- mediaId
- mediaType
- duration
properties:
url:
type: string
description: Public URL to image or video file
mediaId:
type: string
description: Unique media ID (max 30 characters)
maxLength: 30
mediaType:
type: string
enum:
- image
- video
description: Media type
texts:
type: array
description: Array of text elements (0-10 texts)
minItems: 0
maxItems: 10
items:
type: object
required:
- text
properties:
text:
type: string
description: Text content (1-500 characters)
minLength: 1
maxLength: 500
x:
type: number
description: >-
X coordinate (must be non-negative and within
canvas)
minimum: 0
default: 0
'y':
type: number
description: >-
Y coordinate (must be non-negative and within
canvas)
minimum: 0
default: 43.13
width:
type: number
description: Width in pixels
minimum: 10
default: 280
height:
type: number
description: Height in pixels
minimum: 10
default: 50
fontSize:
type: number
description: Font size (8-200)
minimum: 8
maximum: 200
default: 16
fontWeight:
type: string
description: Font weight
default: '600'
color:
type: string
description: Text color as hex code
default: '#ffffff'
backgroundColor:
type: string
description: Background color
default: transparent
opacity:
type: number
description: Text opacity (0-1)
minimum: 0
maximum: 1
default: 1
rotation:
type: number
description: Rotation in degrees (-360 to 360)
minimum: -360
maximum: 360
default: 0
scale:
type: number
description: Scale multiplier (0.1-10)
minimum: 0.1
maximum: 10
default: 1
zIndex:
type: number
description: Layer order
minimum: 0
default: 1
textAlign:
type: string
enum:
- left
- center
- right
description: Text alignment
default: center
fontFamily:
type: string
description: Font family name
default: TikTok Display Medium
borderRadius:
type: number
description: Border radius in pixels
minimum: 0
default: 8
padding:
type: number
description: Text padding in pixels
minimum: 0
default: 6
maxWidth:
type: number
description: Maximum width as percentage (0-100)
minimum: 0
maximum: 100
default: 80
wordWrap:
type: string
enum:
- normal
- break-word
description: Word wrapping
default: break-word
duration:
type: number
description: Slide duration in seconds (0.1-60)
minimum: 0.1
maximum: 60
default: 3
isAIGenerated:
type: boolean
description: Whether media is AI-generated
default: false
script:
type: string
description: Voiceover script (max 10,000 characters)
maxLength: 10000
voiceId:
type: string
description: Voice ID from /v1/voice/list (max 30 characters)
maxLength: 30
avatarId:
type: string
description: Avatar ID from /v1/avatar/list (max 30 characters)
maxLength: 30
musicId:
type: string
description: Music ID from /v1/music/list (max 30 characters)
maxLength: 30
aspectRatio:
type: string
enum:
- ratio_9_16
- ratio_16_9
- ratio_1_1
description: Video aspect ratio
default: ratio_9_16
language:
type: string
description: Language code (exactly 2 characters, e.g., en, es, fr)
minLength: 2
maxLength: 2
default: en
webhook:
type: string
description: HTTPS URL for status notifications (max 500 characters)
maxLength: 500
metadata:
type: object
description: Custom metadata object (max 5KB)
example:
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
responses:
'200':
description: TikTok Slideshow created successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
data:
type: object
properties:
videoId:
type: string
projectId:
type: string
status:
type: string
message:
type: string
example:
success: true
data:
videoId: vid_tiktok_abc123xyz
projectId: proj_tiktok_abc123xyz
status: STARTED
message: TikTok Slideshow successfully created
'400':
description: Validation error
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
example:
success: false
message: 'slides: At least one slide is required'
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
example:
success: false
message: Invalid API key
security:
- ApiKeyAuth: []
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
````