API Docs
API Docs
Video Subtitling
Generate time-synced subtitles for video content using our Video Subtitling API.
Create Video Subtitling Request
/api/vs
This endpoint generates subtitles for a video by embedding provided SRT subtitle text into the video timeline. Videos are uploaded using multipart form data.
The request is processed asynchronously. Once accepted, the API returns a unique log_id which can be used to track subtitle processing and retrieve the final video output.
Request Body
project_title (string, required)
A human-readable title to identify the video subtitling project.
Example: "My Project"
file (file, optional)
Video file to which subtitles will be applied. Required if youtube_url is not provided. Supported formats include MP4.
Example: "video.mp4"
youtube_url (string, optional)
YouTube video URL for subtitling. Required if file is not provided. Do not provide both file and youtube_url.
Example: "https://www.youtube.com/watch?v=XXXX"
subtitle_language (string, required)
Language of the subtitle text being applied to the video.
View example →subtitle_srt_text (string, required)
Subtitle content in SRT format. This text will be embedded into the video with proper timing.
Example: "1\\n00:00:00,000 --> 00:00:01,000\\nHello world"
Note: You must provide either a video file or a youtube_url. Providing both or neither will result in a validation error.
Response
On successful submission, the API returns a unique log_id.
Use this log_id with the Fetch Video Subtitling By ID endpoint to retrieve the processed video and subtitle metadata.
{
"log_id": "69504e977d5247d58c029ed6"
}curl
curl --location 'https://api.narris.io/api/vs' \ --header 'x-api-key: YOUR_API_KEY' \ --form 'project_title="My Project"' \ --form 'file=@"/path/to/video.mp4"' \ --form 'subtitle_language="english"' \ --form 'subtitle_srt_text="@subtitles.srt"'
Fetch Video Subtitling List
/api/vs/logs
This endpoint allows you to fetch a paginated list of previously created video subtitling requests.
Each entry represents a video subtitling job and includes the source video, subtitle language, creation time, completion time, and output video (if available).
Request Body
page (number, optional)
Page number for pagination.
Example: 1
limit (number, optional)
Number of records to return per page.
Example: 10
Response
On success, the API returns a paginated list of video subtitling logs.
Each log contains a unique _id which can be used with the Fetch Video Subtitling By ID endpoint to retrieve the final subtitled video and detailed configuration.
{
"total": 13,
"page": 1,
"limit": 10,
"logs": [
{
"_id": "69504e977d5247d58c029ed6",
"project_title": "My Project",
"video_url": "https://lingui-dev.s3.amazonaws.com/input/video.mp4",
"subtitle_language": "english",
"createdAt": "2025-12-27T21:24:39.070Z",
"finishedAt": "2025-12-27T21:24:43.853Z",
"output_file": "https://lingui-dev.s3.amazonaws.com/video_subtitle/output/subtitled.mp4"
},
{
"_id": "694b2d9365dde71d5b29b69d",
"project_title": "My Project",
"video_url": "https://lingui-dev.s3.amazonaws.com/input/video.mp4",
"subtitle_language": "english",
"createdAt": "2025-12-24T00:02:27.203Z",
"finishedAt": "2025-12-24T00:03:24.402Z",
"output_file": "https://lingui-dev.s3.amazonaws.com/video_subtitle/output/subtitled.mp4"
}
]
}curl
curl --location 'https://api.narris.io/api/vs/logs?page=1&limit=10' \ --header 'Content-Type: application/json' \ --header 'x-api-key: YOUR_API_KEY'
Fetch Video Subtitling By ID
/api/vs/{log_id}
This endpoint allows you to fetch the complete details of a video subtitling request using its unique log_id.
The response includes the original video URL, subtitle configuration, processing status, timestamps, and the final subtitled video output once the job is completed.
Request Body
log_id (string, required)
Unique identifier of the video subtitling request returned during creation or from subtitling logs.
Example: "694b2c9e9f519599a4ed1bf0"
Response
On success, the API returns detailed information about the video subtitling request.
If processing is completed, the output_file field will contain the URL of the final subtitled video.
{
"_id": "694b2c9e9f519599a4ed1bf0",
"project_title": "My Project",
"video_url": "https://lingui-dev.s3.amazonaws.com/input/video.mp4",
"subtitle_srt_text": "1\n00:00:00,000 --> 00:00:00,760\nWhat is the most\n\n2\n00:00:00,760 --> 00:00:02,360\nimportant thing a woman",
"subtitle_language": "english",
"single_line_subtitle": false,
"font_size": "Medium",
"primary_color": "#FFFFFF",
"outline_color": "#000000",
"background_color": "#000000",
"opacity": "only_shadow",
"status": "finished",
"createdAt": "2025-12-23T23:58:22.095Z",
"updatedAt": "2025-12-23T23:59:12.495Z",
"finishedAt": "2025-12-23T23:59:12.494Z",
"output_file": "https://lingui-dev.s3.amazonaws.com/video_subtitle/output/subtitled.mp4"
}curl
curl --location 'https://api.narris.io/api/vs/694b2c9e9f519599a4ed1bf0' \ --header 'Content-Type: application/json' \ --header 'x-api-key: YOUR_API_KEY'
Notes for Developers
• Video subtitling requests are processed asynchronously. Always store the returned log_id to track processing status.
• Subtitles are generated with precise timestamps and can be delivered in formats such as SRT or embedded video output.
• Jobs may remain in pending or processing state depending on video duration and system load.
• Use the Fetch Video Subtitling List endpoint to view all subtitling jobs and Fetch Video Subtitling By ID to retrieve the final subtitle files and processed video output.