Skip to main content
POST
/
v1
/
project
/
create
/
add-captions
Add Captions
curl --request POST \
  --url https://api.slidevid.ai/v1/project/create/add-captions \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "media": "media_abc123",
  "language": "en",
  "caption": {
    "preset": "beast",
    "alignment": "bottom"
  },
  "addStickers": true,
  "musicId": "upbeat_001"
}
'
{
  "success": true,
  "data": {
    "videoId": "vid_caption_abc123xyz",
    "projectId": "proj_caption_abc123xyz",
    "status": "STARTED"
  }
}

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.

Try it out! Use the API playground on the right to test the Add Captions endpoint directly.

​
Overview

Add Captions automatically transcribes your video and adds professional-looking captions with customizable styles. Perfect for:
  • Social media content (TikTok, Instagram Reels, YouTube Shorts)
  • Accessibility compliance
  • Increasing video engagement
  • Multi-language content
  • Educational videos
Captions are automatically synced with your video’s audio and support multiple styling presets.

​
Endpoint

POST /v1/project/create/add-captions

​
Required Fields

​
media
string
required
Media ID of the video to add captions to (as a string)

​
Optional Fields

​
name
string
Custom name for the project (max 100 characters). If not provided, a name will be auto-generated.
​
musicId
string
Background music ID from /v1/music/list (max 30 characters)
​
caption
object
Caption settings for the video
​
language
string
default:"en"
Language code for the video (2 characters). Example: en, es
​
webhook
string
Webhook URL for status notifications (max 500 characters, must be HTTPS)
​
metadata
object
Custom metadata object (max 5KB JSON)

​
Request Examples

​
Basic Caption Addition

const response = await fetch('https://api.tryslidevid.ai/v1/project/create/add-captions', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.SLIDEVID_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    media: 'media_abc123'
  })
});

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

​
Advanced with Custom Styling

const addCaptionsAdvanced = async () => {
  const response = await fetch('https://api.tryslidevid.ai/v1/project/create/add-captions', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.SLIDEVID_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Social Media Captioned Video',
      media: 'media_xyz789',
      language: 'en',
      caption: {
        preset: 'modern',
        alignment: 'bottom'
      },
      addStickers: false,
      musicId: 'upbeat_background_001',
      webhook: 'https://yoursite.com/webhook',
      metadata: {
        campaignId: 'social-media-2024',
        platform: 'tiktok'
      }
    })
  });

  return await response.json();
};

​
With Background Music

const addCaptionsWithMusic = async () => {
  const response = await fetch('https://api.tryslidevid.ai/v1/project/create/add-captions', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.SLIDEVID_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Product Demo with Captions',
      media: 'media_product_demo',
      language: 'en',
      addStickers: false,
      caption: {
        preset: 'modern',
        alignment: 'bottom'
      },
      musicId: 'calm_background_music'
    })
  });

  return await response.json();
};

​
Response

{
  "success": true,
  "data": {
    "videoId": "vid_caption_abc123xyz",
    "projectId": "proj_caption_abc123xyz",
    "status": "STARTED"
  }
}

​
Webhook Notification

When your captioned video is ready, we’ll POST to your webhook URL (if configured):
Webhook Payload
{
  "status": "COMPLETED",
  "data": {
    "videoId": "vid_caption_abc123xyz",
    "status": "COMPLETED",
    "url": "https://cdn.tryslidevid.ai/videos/abc123xyz.mp4",
    "shareUrl": "https://cdn.tryslidevid.ai/shared/abc123xyz.mp4",
    "metadata": {
      "projectId": "proj_caption_abc123xyz"
    }
  },
  "message": "Video completed"
}

​
Caption Presets

Available caption presets for the caption.preset field:
PresetDescription
defaultDefault caption style with bold text and shadow effects
beastBold uppercase style with Komika font
umiYellow glowing text style
tiktokViral & trendy style, perfect for social media
wrap1Wrapped style with red background highlight
wrap2Wrapped style with blue background highlight (uppercase)
arielBold uppercase style with purple highlight
hookedBrand style with purple background
classicClean, simple captions with black background (Default)
activeGreen background with bold text
bubbleWhite background bubble style
glassGlassmorphic transparency effect
comicComic Sans font with colorful style
glowPink and orange glow effects
pastelSoft pastel pink background
neonGreen neon glow effect
retroTVRetro TV style with cyan glow
redRed glow effect with white text
markerYellow marker/highlighter style
modernContemporary white background style
blueBlue background style
vividVibrant pink background with uppercase text

​
Best Practices

Clear Audio

Ensure your video has clear audio for accurate transcription

Language Match

Set the correct language code for best transcription accuracy

Style Selection

Choose caption styles that match your content and brand

Positioning

Bottom alignment works best for most social media content

​
Error Handling

ErrorDescriptionSolution
media: Media ID is requiredMissing media IDProvide a valid media ID string
media: Media not foundInvalid media IDEnsure the media ID exists and is correct
media: Media is not a videoMedia is not a video typeEnsure the media ID points to a video, not an image
language: Language code too longInvalid language codeUse 2-character language code (e.g., “en”, “es”)
musicId: Music "X" not foundInvalid music IDUse valid music ID from /v1/music/list
caption.alignment: Invalid enum valueInvalid alignmentUse bottom, middle, or top
webhook: Must be a valid HTTPS URLInvalid webhook URLEnsure webhook URL uses HTTPS
Not enough creditsInsufficient creditsTop up your account credits

​
Next Steps

List Videos

View all your created videos

Video Details

Check your video processing status

Music Library

Browse available background music

Webhooks Guide

Learn how to handle webhook notifications

Authorizations

​
x-api-key
string
header
required

Body

application/json
​
media
object[]
required

Array containing exactly one video file

Required array length: 1 element
​
language
string
default:en
required

Language code for transcription (exactly 2 characters)

Required string length: 2
​
caption
object
required

Caption styling and positioning settings

​
addStickers
boolean
default:false

Add AI-generated stickers to enhance video engagement

​
musicId
string

Background music ID from /v1/music/list

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

Add Captions created successfully

​
success
boolean
​
data
object