> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hooked.so/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

<Note>
  **Try it out!** Use the API playground on the right to test the TikTok Slideshow endpoint directly.
</Note>

## 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

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

***

## Endpoint

```
POST /v1/project/create/tiktok-slideshow
```

***

## Required Fields

<ParamField body="slides" type="array" required>
  Array of slide objects for the slideshow (1-50 slides). Each slide contains a media ID and optional text overlays.

  <Expandable title="Slide Object">
    <ParamField body="media" type="string" required>
      Media ID from your media library. The media must already be uploaded to your account.
    </ParamField>

    <ParamField body="duration" type="number" default={3}>
      Slide duration in seconds (1-10)
    </ParamField>

    <ParamField body="texts" type="array">
      Array of text elements for this slide (0-10 texts)

      <Expandable title="Text Object">
        <ParamField body="text" type="string" required>
          Text content (1-500 characters)
        </ParamField>

        <ParamField body="x" type="number" default={0}>
          X coordinate (must be non-negative and within canvas)
        </ParamField>

        <ParamField body="y" type="number" default={43.13}>
          Y coordinate (must be non-negative and within canvas)
        </ParamField>

        <ParamField body="width" type="number" default={280}>
          Width in pixels (minimum 10)
        </ParamField>

        <ParamField body="height" type="number" default={50}>
          Height in pixels (minimum 10)
        </ParamField>

        <ParamField body="fontSize" type="number" default={16}>
          Font size in pixels (8-200)
        </ParamField>

        <ParamField body="fontWeight" type="string" default="600">
          Font weight (e.g., "400", "600", "bold")
        </ParamField>

        <ParamField body="color" type="string" default="#ffffff">
          Text color as hex code (e.g., "#ffffff")
        </ParamField>

        <ParamField body="backgroundColor" type="string" default="transparent">
          Background color for text box
        </ParamField>

        <ParamField body="opacity" type="number" default={1}>
          Text opacity (0-1)
        </ParamField>

        <ParamField body="rotation" type="number" default={0}>
          Text rotation in degrees (-360 to 360)
        </ParamField>

        <ParamField body="scale" type="number" default={1}>
          Text scale multiplier (0.1-10)
        </ParamField>

        <ParamField body="zIndex" type="number" default={1}>
          Layer order (higher = on top)
        </ParamField>

        <ParamField body="textAlign" type="string" default="center">
          Text alignment: `left`, `center`, or `right`
        </ParamField>

        <ParamField body="fontFamily" type="string" default="TikTok Display Medium">
          Font family name
        </ParamField>

        <ParamField body="borderRadius" type="number" default={8}>
          Border radius in pixels (0+)
        </ParamField>

        <ParamField body="padding" type="number" default={6}>
          Text padding in pixels (0+)
        </ParamField>

        <ParamField body="maxWidth" type="number" default={80}>
          Maximum width as percentage (0-100)
        </ParamField>

        <ParamField body="wordWrap" type="string" default="break-word">
          Word wrapping: `normal` or `break-word`
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

***

## Optional Fields

<ParamField body="name" type="string">
  Project name (1-100 characters). If not provided, a name will be auto-generated.
</ParamField>

<ParamField body="script" type="string">
  Voiceover script (max 10,000 characters). Required if using avatar/voice. Must be provided together with avatarId, voiceId, and lipsyncModel.
</ParamField>

<ParamField body="avatarId" type="string">
  Avatar ID from /v1/avatar/list (max 30 characters). Required if using voice. Must be provided together with script, voiceId, and lipsyncModel.
</ParamField>

<ParamField body="voiceId" type="string">
  Voice ID from /v1/voice/list (max 30 characters). Required if using avatar. Must be provided together with script, avatarId, and lipsyncModel.
</ParamField>

<ParamField body="lipsyncModel" type="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
</ParamField>

<ParamField body="audio" type="object">
  Voice audio settings. Used when generating voiceover. Default values are used if not provided.

  <Expandable title="Audio Settings Object">
    <ParamField body="speed" type="number" default={1.0}>
      Voice speed multiplier (0.7 to 1.2)
    </ParamField>

    <ParamField body="stability" type="number" default={0.7}>
      Voice stability (0 to 1)
    </ParamField>

    <ParamField body="similarityBoost" type="number" default={0.75}>
      Voice similarity boost (0 to 1)
    </ParamField>

    <ParamField body="style" type="number" default={0}>
      Voice style exaggeration (0 to 1)
    </ParamField>

    <ParamField body="useSpeakerBoost" type="boolean" default={true}>
      Enable speaker boost for clearer audio
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="musicId" type="string">
  Background music ID from `/v1/music/list` (max 30 characters)
</ParamField>

<ParamField body="webhook" type="string">
  Webhook URL for status notifications (max 500 characters, must be HTTPS)
</ParamField>

<ParamField body="metadata" type="object">
  Custom metadata object (max 5KB JSON)
</ParamField>

***

## Request Examples

### Basic Slideshow

```javascript theme={null}
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

```javascript theme={null}
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

<ResponseExample>
  ```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."
  }
  ```
</ResponseExample>

***

## 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.hooked.so/videos/abc123xyz.mp4",
    "shareUrl": "https://cdn.hooked.so/shared/abc123xyz.mp4",
    "metadata": {
      "projectId": "proj_tiktok_abc123xyz"
    }
  },
  "message": "Video completed"
}
```

***

## Best Practices

<CardGroup cols={2}>
  <Card title="Text Positioning" icon="arrows-up-down-left-right">
    Canvas dimensions depend on aspect ratio. For 9:16 (1080x1920), ensure coordinates are within bounds.
  </Card>

  <Card title="Slide Duration" icon="clock">
    Keep slides between 2-5 seconds for optimal engagement.
  </Card>

  <Card title="Text Readability" icon="eye">
    Use high contrast colors and appropriate font sizes (24-48px) for mobile viewing.
  </Card>

  <Card title="Image Quality" icon="image">
    Use high-resolution images (1080px width minimum) for best results.
  </Card>
</CardGroup>

***

## 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

<CardGroup cols={2}>
  <Card title="List Videos" icon="list" href="/api-reference/video/list">
    View all your created videos
  </Card>

  <Card title="Video Details" icon="video" href="/api-reference/video/details">
    Check your video processing status
  </Card>

  <Card title="Webhooks Guide" icon="webhook" href="/guides/webhooks">
    Learn how to handle webhook notifications
  </Card>

  <Card title="UGC Ads" icon="bullhorn" href="/api-reference/video/ugc-ads">
    Create UGC-style advertisement videos
  </Card>
</CardGroup>


## OpenAPI

````yaml POST /v1/project/create/tiktok-slideshow
openapi: 3.0.0
info:
  title: Hooked API
  version: 1.0.0
  description: AI Video Generation API
servers:
  - url: https://api.hooked.so
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
              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). Each slide contains a media
                    ID and optional text elements.
                  minItems: 1
                  maxItems: 50
                  items:
                    type: object
                    required:
                      - media
                    properties:
                      media:
                        type: string
                        description: Media ID from your media library
                      duration:
                        type: number
                        description: Slide duration in seconds (1-10)
                        minimum: 1
                        maximum: 10
                        default: 3
                      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
                script:
                  type: string
                  description: >-
                    Voiceover script (max 10,000 characters). Required if using
                    avatar/voice. Must be provided together with avatarId,
                    voiceId, and lipsyncModel.
                  maxLength: 10000
                avatarId:
                  type: string
                  description: >-
                    Avatar ID from /v1/avatar/list (max 30 characters). Required
                    if using voice. Must be provided together with script,
                    voiceId, and lipsyncModel.
                  maxLength: 30
                voiceId:
                  type: string
                  description: >-
                    Voice ID from /v1/voice/list (max 30 characters). Required
                    if using avatar. Must be provided together with script,
                    avatarId, and lipsyncModel.
                  maxLength: 30
                lipsyncModel:
                  type: string
                  description: >-
                    Lipsync model quality. Required if using avatar/voice. Must
                    be provided together with script, avatarId, and voiceId.
                  enum:
                    - base
                    - pro
                  default: base
                musicId:
                  type: string
                  description: Music ID from /v1/music/list (max 30 characters)
                  maxLength: 30
                audio:
                  type: object
                  description: >-
                    Voice audio settings. Used when generating voiceover.
                    Default values are used if not provided.
                  properties:
                    speed:
                      type: number
                      description: Voice speed multiplier (0.7 to 1.2)
                      minimum: 0.7
                      maximum: 1.2
                      default: 1
                    stability:
                      type: number
                      description: Voice stability (0 to 1)
                      minimum: 0
                      maximum: 1
                      default: 0.5
                    similarityBoost:
                      type: number
                      description: Voice similarity boost (0 to 1)
                      minimum: 0
                      maximum: 1
                      default: 0.75
                    style:
                      type: number
                      description: Voice style exaggeration (0 to 1)
                      minimum: 0
                      maximum: 1
                      default: 0
                    useSpeakerBoost:
                      type: boolean
                      description: Enable speaker boost for clearer audio
                      default: true
                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
              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
      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

````