> ## 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.
# Add Captions
> Add automatic captions to your videos with customizable styles and positioning
**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 ID of the video to add captions to (as a string)
***
## Optional Fields
Custom name for the project (max 100 characters). If not provided, a name will be auto-generated.
Background music ID from `/v1/music/list` (max 30 characters)
Caption settings for the video
Caption preset style. Available presets: `default`, `beast`, `umi`, `tiktok`, `wrap1`, `wrap2`, `ariel`, `hooked`, `classic`, `active`, `bubble`, `glass`, `comic`, `glow`, `pastel`, `neon`, `retroTV`, `red`, `marker`, `modern`, `blue`, `vivid`.
Caption position on the video: `top`, `middle`, or `bottom`
Webhook URL for status notifications (max 500 characters, must be HTTPS)
Custom metadata object (max 5KB JSON)
***
## Request Examples
### Basic Caption Addition
```javascript theme={null}
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: '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
```javascript theme={null}
const addCaptionsAdvanced = 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: 'Social Media Captioned Video',
media: 'media_xyz789',
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
```javascript theme={null}
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 Captions',
media: 'media_product_demo',
addStickers: false,
caption: {
preset: 'modern',
alignment: 'bottom'
},
musicId: 'calm_background_music'
})
});
return await response.json();
};
```
***
## Response
```json Success Response theme={null}
{
"success": true,
"data": {
"videoId": "vid_caption_abc123xyz",
"projectId": "proj_caption_abc123xyz",
"status": "STARTED"
}
}
```
```json Error Response - Invalid Media theme={null}
{
"success": false,
"message": "media: Media ID is required"
}
```
```json Error Response - Media Not Found theme={null}
{
"success": false,
"message": "media: Media not found"
}
```
```json Error Response - Music Not Found theme={null}
{
"success": false,
"message": "musicId: Music \"invalid_music\" not found."
}
```
***
## Webhook Notification
When your captioned video is ready, we'll POST to your webhook URL (if configured):
```json Webhook Payload theme={null}
{
"status": "COMPLETED",
"data": {
"videoId": "vid_caption_abc123xyz",
"status": "COMPLETED",
"url": "https://cdn.hooked.so/videos/abc123xyz.mp4",
"shareUrl": "https://cdn.hooked.so/shared/abc123xyz.mp4",
"metadata": {
"projectId": "proj_caption_abc123xyz"
}
},
"message": "Video completed"
}
```
***
## Caption Presets
Available caption presets for the `caption.preset` field:
| Preset | Description |
| --------- | -------------------------------------------------------- |
| `default` | Default caption style with bold text and shadow effects |
| `beast` | Bold uppercase style with Komika font |
| `umi` | Yellow glowing text style |
| `tiktok` | Viral & trendy style, perfect for social media |
| `wrap1` | Wrapped style with red background highlight |
| `wrap2` | Wrapped style with blue background highlight (uppercase) |
| `ariel` | Bold uppercase style with purple highlight |
| `hooked` | Brand style with purple background |
| `classic` | Clean, simple captions with black background (Default) |
| `active` | Green background with bold text |
| `bubble` | White background bubble style |
| `glass` | Glassmorphic transparency effect |
| `comic` | Comic Sans font with colorful style |
| `glow` | Pink and orange glow effects |
| `pastel` | Soft pastel pink background |
| `neon` | Green neon glow effect |
| `retroTV` | Retro TV style with cyan glow |
| `red` | Red glow effect with white text |
| `marker` | Yellow marker/highlighter style |
| `modern` | Contemporary white background style |
| `blue` | Blue background style |
| `vivid` | Vibrant pink background with uppercase text |
***
## Best Practices
Ensure your video has clear audio for accurate transcription
Choose caption styles that match your content and brand
Bottom alignment works best for most social media content
***
## Error Handling
| Error | Description | Solution |
| --------------------------------------- | ------------------------- | --------------------------------------------------- |
| `media: Media ID is required` | Missing media ID | Provide a valid media ID string |
| `media: Media not found` | Invalid media ID | Ensure the media ID exists and is correct |
| `media: Media is not a video` | Media is not a video type | Ensure the media ID points to a video, not an image |
| `musicId: Music "X" not found` | Invalid music ID | Use valid music ID from `/v1/music/list` |
| `caption.alignment: Invalid enum value` | Invalid alignment | Use `bottom`, `middle`, or `top` |
| `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
Browse available background music
Learn how to handle webhook notifications
## OpenAPI
````yaml POST /v1/project/create/add-captions
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/add-captions:
post:
tags:
- Videos
summary: Add Captions
description: >-
Add automatic captions to videos with customizable styles and
positioning
operationId: addCaptions
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- media
properties:
name:
type: string
description: Custom name for the project
maxLength: 100
media:
type: string
description: Media ID from uploaded video
caption:
type: object
description: Caption styling and positioning settings
properties:
preset:
type: string
description: Caption style preset
enum:
- default
- beast
- umi
- tiktok
- wrap1
- wrap2
- ariel
- hooked
- classic
- active
- bubble
- glass
- comic
- glow
- pastel
- neon
- retroTV
- red
- marker
- modern
- blue
- vivid
default: classic
alignment:
type: string
description: Vertical position of captions
enum:
- bottom
- middle
- top
default: bottom
addStickers:
type: boolean
description: Add AI-generated stickers to enhance video engagement
default: false
musicId:
type: string
description: Background music ID from /v1/music/list
maxLength: 30
webhook:
type: string
description: HTTPS URL for status notifications (max 500 characters)
maxLength: 500
metadata:
type: object
description: Custom metadata object (max 5KB)
example:
media: media_abc123
caption:
preset: beast
alignment: bottom
addStickers: true
musicId: upbeat_001
responses:
'200':
description: Add Captions 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
example:
success: true
data:
videoId: vid_caption_abc123xyz
projectId: proj_caption_abc123xyz
status: STARTED
'400':
description: Validation error
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
example:
success: false
message: 'media: Media ID 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
````