Skip to main content

​
Overview

Add Captions automatically transcribes your video and adds professional captions. Perfect for social media content, accessibility, and increasing engagement.

​
Basic Example

const response = await fetch('https://api.tryhooked.ai/v1/project/create/add-captions', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.HOOKED_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);

​
With Custom Caption Style

const addCaptionsStyled = async () => {
  const response = await fetch('https://api.tryhooked.ai/v1/project/create/add-captions', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.HOOKED_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Tutorial Video with Captions',
      media: 'media_tutorial_video',
      language: 'en',
      addStickers: false,
      caption: {
        preset: 'beast',
        alignment: 'bottom'
      }
    })
  });

  return await response.json();
};

​
With Background Music

const addCaptionsWithMusic = async () => {
  const response = await fetch('https://api.tryhooked.ai/v1/project/create/add-captions', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.HOOKED_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Product Demo with Music',
      media: 'media_product_demo',
      language: 'en',
      addStickers: false,
      caption: {
        preset: 'modern',
        alignment: 'bottom'
      },
      musicId: 'upbeat_001',
      webhook: 'https://yoursite.com/webhook',
      metadata: {
        campaignId: 'product-launch-2024',
        platform: 'tiktok'
      }
    })
  });

  return await response.json();
};

​
Tips for Add Captions

Clear audio: Ensure your video has clear, high-quality audio for best transcription accuracy
Correct language: Always specify the correct language code for optimal results
Style selection: Choose caption presets that match your content style and target audience
Bottom alignment: For social media, bottom alignment typically performs best
Test different presets: Try various caption styles to see what resonates with your audience

​
Aspect Ratio Guide

Choose the right aspect ratio for your platform:
PlatformAspect RatioValue
TikTok, Instagram Reels, YouTube ShortsVerticalratio_9_16
YouTube, LinkedInHorizontalratio_16_9
Instagram FeedSquareratio_1_1

​
Handling the Webhook Response

// Express.js webhook handler
app.post('/webhook', (req, res) => {
  const { data, status, message } = req.body;

  if (status === "COMPLETED") {
    const { videoId, url, shareUrl } = data;
    console.log('Captions added successfully!');
    console.log('Video ID:', videoId);
    console.log('Download URL:', url);
    console.log('Share URL:', shareUrl);

    // Save to your database, notify team, etc.
  } else if (status === "FAILED") {
    console.error('Caption generation failed:', message);
    // Handle failure, notify user, retry, etc.
  }

  res.status(200).send('OK');
});

​
Common Use Cases

  • Social Media Content: Add captions to make videos more engaging and accessible
  • Educational Videos: Help learners follow along with automatic captions
  • Accessibility: Make content accessible to deaf and hard-of-hearing viewers
  • Multi-Language: Transcribe videos in different languages for global audiences
  • SEO: Improve video SEO with searchable caption content
  • Silent Viewing: Enable viewers to watch without sound in public places