Add Subtitle API

Pricing

35 credits per request

Fixed cost regardless of video length or subtitle content length.

Overview

The Add Subtitle API adds subtitles/captions to videos. This endpoint supports multiple input formats (SRT files, text, or auto-transcription) and provides extensive styling options for subtitle appearance.

Endpoint

URL: POST https://api.revidapi.com/paid/add-subtitle
Method: POST

Request

Headers

x-api-key: Required. Your API key for authentication.
Content-Type: Required. Must be application/json.

Body Parameters

Required Parameters

Parameter	Type	Description
`video_url`	string (URI)	URL of the video file to process

Optional Parameters

Parameter	Type	Description
`subtitle_url`	string (URI)	URL of an SRT subtitle file
`subtitle_text`	string	Plain text to use as subtitles (will be displayed for entire video duration)
`auto_generate`	boolean	If true, automatically transcribes audio and generates subtitles. Default: `false`
`settings`	object	Styling options for subtitles (see Settings Schema below)
`language`	string	Language code for subtitles/transcription (e.g., `en`, `vi`). Default: `auto`
`webhook_url`	string (URI)	URL to receive the result when processing is complete
`id`	string	Custom identifier for tracking the request

Settings Schema

{
  "position": "bottom_center",
  "font_family": "Arial",
  "font_size": 24,
  "font_color": "#FFFFFF",
  "background_color": "#000000",
  "outline_color": "#000000",
  "outline_width": 2,
  "alignment": "center",
  "bold": false,
  "italic": false,
  "underline": false
}

Settings Options

Parameter	Type	Description
`position`	string	Position: `top_left`, `top_center`, `top_right`, `middle_left`, `middle_center`, `middle_right`, `bottom_left`, `bottom_center`, `bottom_right`
`font_family`	string	Font family name (e.g., `Arial`, `Times New Roman`)
`font_size`	integer	Font size in pixels
`font_color`	string	Text color in hex format (e.g., `#FFFFFF`)
`background_color`	string	Background color in hex format
`outline_color`	string	Outline/stroke color in hex format
`outline_width`	integer	Outline width in pixels
`alignment`	string	Text alignment: `left`, `center`, `right`
`bold`	boolean	Bold text
`italic`	boolean	Italic text
`underline`	boolean	Underline text

Example Request

Example 1: Using SRT File

{
  "video_url": "https://example.com/video.mp4",
  "subtitle_url": "https://example.com/subtitles.srt",
  "settings": {
    "position": "bottom_center",
    "font_family": "Arial",
    "font_size": 24,
    "font_color": "#FFFFFF",
    "outline_color": "#000000",
    "outline_width": 2,
    "alignment": "center"
  },
  "webhook_url": "https://example.com/webhook",
  "id": "add-subtitle-123"
}

Example 2: Auto-generate Subtitles

{
  "video_url": "https://example.com/video.mp4",
  "auto_generate": true,
  "language": "en",
  "settings": {
    "position": "bottom_center",
    "font_size": 28,
    "font_color": "#FFFF00",
    "outline_color": "#000000"
  },
  "webhook_url": "https://example.com/webhook",
  "id": "add-subtitle-auto-123"
}

curl -X POST "https://api.revidapi.com/paid/add-subtitle" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://example.com/video.mp4",
    "subtitle_url": "https://example.com/subtitles.srt",
    "settings": {
      "position": "bottom_center",
      "font_family": "Arial",
      "font_size": 24,
      "font_color": "#FFFFFF",
      "outline_color": "#000000",
      "outline_width": 2
    },
    "webhook_url": "https://example.com/webhook",
    "id": "add-subtitle-123"
  }'

Response

Immediate Response (202 Accepted)

When a webhook URL is provided, the API returns an immediate acknowledgment with a task_id:

{
  "code": 202,
  "id": "add-subtitle-123",
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "processing"
}

Success Response (via Webhook or Direct)

{
  "code": 200,
  "id": "add-subtitle-123",
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "response": {
    "video_url": "https://storage.example.com/video/subtitled-output.mp4"
  },
  "message": "success"
}

Error Responses

Invalid Request (400)

{
  "code": 400,
  "id": "add-subtitle-123",
  "message": "Invalid request: 'video_url' is a required property"
}

Authentication Error (401)

{
  "code": 401,
  "message": "Invalid API key"
}

Workflow Recommendation

For asynchronous processing:

Create Task: Send POST request to create the task
Wait: Add a wait node (30-45 seconds) to allow server processing time
Check Status: Use GET endpoint to check task status: GET https://api.revidapi.com/paid/get/job/status/{task_id}
Retrieve Result: Once status is "completed", retrieve the video URL from the response

Usage Notes

Fixed Pricing: This endpoint charges a fixed 35 credits per request, regardless of video length.
Input Options: You can provide subtitles via subtitle_url (SRT file), subtitle_text (plain text), or use auto_generate for automatic transcription.
SRT Format: When using subtitle_url, ensure the SRT file is properly formatted with timestamps.
Styling: Use the settings object to customize subtitle appearance, position, and formatting.
Auto-generation: When auto_generate is true, the API transcribes the audio and creates time-synced subtitles.

Common Issues

Invalid SRT Format: Ensure SRT files are properly formatted with valid timestamps
Font Availability: Some fonts may not be available on the server
Position Clipping: Ensure subtitle position doesn't get clipped by video edges

Best Practices

Use Webhooks: Always use webhooks for better reliability
Unique IDs: Provide unique id values for tracking
SRT Validation: Validate SRT file format before submission
Styling Consistency: Use consistent styling across videos for better user experience
Color Contrast: Ensure sufficient contrast between text and background for readability
Auto-generation: Use auto-generation for videos without existing subtitles