Add Captions Example

Overview

Add Captions transcribes a video from your media library and burns captions onto it. Captions are on by default. The output keeps the source video’s aspect ratio.

Basic Example

media is the ID of one video in your library (a single string, not an array).

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

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

The create call answers right away with the projectId. The finished video comes later: poll GET /v1/project/{projectId} or pass a webhook (see below).

With Custom Caption Style

const addCaptionsStyled = async () => {
  const response = await fetch('https://api.hooked.so/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: 'clxmedia0002',
      language: 'en', // the language spoken in the video (default "en"); set it when the video is not in English
      caption: {
        preset: 'beast',
        alignment: 'bottom'
      }
    })
  });

  return await response.json();
};

With Background Music

const addCaptionsWithMusic = async () => {
  const response = await fetch('https://api.hooked.so/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: 'clxmedia0003',
      caption: {
        preset: 'modern',
        alignment: 'bottom'
      },
      musicId: '1', // from GET /v1/music/list, or your own uploaded track
      webhook: 'https://yoursite.com/webhook?token=YOUR_SECRET',
      metadata: {
        campaignId: 'product-launch',
        platform: 'tiktok'
      }
    })
  });

  return await response.json();
};

Parameters

Parameter	Type	Required	Description
`media`	string	Yes	ID of a video in your media library
`name`	string	No	Project name (max 100 characters)
`language`	string	No	Two-letter code of the language spoken in the video. Default `en`
`caption.preset`	string	No	Caption style. Default `classic`
`caption.alignment`	string	No	`top`, `middle` or `bottom` (default)
`caption.disabled`	boolean	No	Default `false` (captions on)
`musicId`	string	No	Background music: an ID from `/v1/music/list` or one of your team’s own uploaded tracks
`webhook`	string	No	HTTPS URL called when the video is ready or the project fails
`metadata`	object	No	Your own data (max 5KB), sent back in the webhook

Caption presets: any id of Get Catalog with name=caption-presets (for example wrap1, tiktok, beast, classic).

Managed teams pay 4 credits plus 4 per started 30 seconds of the video, charged when processing starts. Teams in bring-your-own-keys mode are not charged credits for generation, but need their own OpenRouter key (transcription) in Settings → AI keys. Without it the call answers 402 with code: "missing_credentials" and the missingProviders list, before anything is created or charged.

Tips for Add Captions

Clear audio: Ensure your video has clear, high-quality audio for best transcription accuracy

Set the language: Pass language when the video is not in English

Style selection: Choose caption presets that match your content style and target audience

Retry creates safely: send an Idempotency-Key header. A retry with the same key after a timeout or 5xx returns the first answer instead of charging twice

Checking the Result

const getResult = async (projectId) => {
  while (true) {
    const res = await fetch(`https://api.hooked.so/v1/project/${projectId}`, {
      headers: { 'x-api-key': process.env.HOOKED_API_KEY }
    });
    const { data } = await res.json();

    if (data.video?.status === 'COMPLETED') return data.video.url;
    if (data.status === 'failed' || data.video?.status === 'FAILED') {
      throw new Error(data.video?.message || data.message || 'Project failed');
    }
    await new Promise((resolve) => setTimeout(resolve, 15000));
  }
};

Handling the Webhook Response

Webhooks are signed: check the Hooked-Signature header as shown in Webhooks.

// Express.js webhook handler
app.post('/webhook', (req, res) => {
  if (req.query.token !== process.env.HOOKED_WEBHOOK_TOKEN) return res.sendStatus(401);

  const { status, message, data } = req.body;
  const { videoId, projectId, url, metadata } = data;

  if (status === 'COMPLETED') {
    console.log('Captions added to project', projectId, '- video', videoId);
    console.log('Download URL:', url);
    // Save to your database, notify team, etc.
  } else if (status === 'FAILED') {
    if (videoId === null) {
      console.error('Project failed before rendering:', message);
    } else {
      console.error('Render failed:', message);
    }
  }

  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: Caption videos in other languages with the language field
Silent Viewing: Enable viewers to watch without sound in public places

Getting Started

Core Concepts

AI Agents

Guides

Examples

Overview

Basic Example

With Custom Caption Style

With Background Music

Parameters

Tips for Add Captions

Checking the Result

Handling the Webhook Response

Common Use Cases

​Overview

​Basic Example

​With Custom Caption Style

​With Background Music

​Parameters

​Tips for Add Captions

​Checking the Result

​Handling the Webhook Response

​Common Use Cases

Overview

Basic Example

With Custom Caption Style

With Background Music

Parameters

Tips for Add Captions

Checking the Result

Handling the Webhook Response

Common Use Cases