Skip to content

Bulk Video Request

This API guide provides an overview of bulk request generation.

Bulk Video Request

A bulk request allows you to generate multiple personalized video files in one go by using a CSV file with user-specific data. Instead of creating each audio individually, you can input various fields, such as names and company details, into the CSV, and the system will automatically generate customized audios for each entry. 🦊

Let's say you want to create personalized audio files for multiple users. Your CSV file contains the following data:

First Name Company Name
John Acme Corp
Jane Beta Ltd

Now, in your audio text, you use the supported macros like this:

"Hello {{First Name}}, welcome to {{Company Name}}!"

When the bulk request is processed, the macros will be replaced with the values from the CSV. The generated audios would be:

  1. "Hello John Smith, welcome to Acme Corp!"
  2. "Hello Jane Doe, welcome to Beta Ltd!"

This allows you to create customized audio files for each user in your CSV, making bulk requests both efficient and personalized.

Quick Start

Let’s dive in and explore how to create a bulk request with your custom configurations.

Creating Bulk Request

To create a bulk request, use the following API request. It lets you define various settings, including audio text, avatar, and background, to generate a bulk request. Customize the parameters to fit your needs. If You have a bulk template, to use that to create a bulk request use create bulk template API.

You can obtain the 'audio_id' and 'audio_service' from the audio listing API and the "csv_id" from the csv listing API.

You can use macros in the format '{{}}' within the 'audio_text', which will be dynamically replaced by values from the CSV file you provided. For example, if you include '{{First Name}}' in your text, it will be replaced by names like "John" and "Smith" for each corresponding entry in the CSV, creating personalized audio for each video in the list. We support up to 20 template variable per request. Ensure that the number and names of these variables match exactly between your text and the CSV file. Template variable text case is not case-sensitive. If any template variables are missing from the CSV, an error will be returned.

In the response, you will receive details on the number of successful videos and any that have failed. Use the 'id' from the response to check the status of the bulk request using bulk status API

  • 'id': The identifier for the bulk request.
  • 'successful_requests_count': The number of videos successfully sent for processing.
  • 'failed_requests_count': The number of videos that failed to go for processing.
curl --request POST \
     --url 'https://api.immersive-fox.com/v1/bulk_requests/generate_video/' \
     --header 'X-Api-Key: <your-api-key>' \
     --header 'Content-Type: application/json' \
     --data { \
                "csv_id": 45 \
                "subtitles_flag": false \
                "video_name": "My First Video" \
                "configurations": [ \
                    { \
                        "audio_text": "Hi, My name is {{First Name}}", \
                        "avatar": 102, \
                        "avatar_size": 76, \
                        "background_color": "#ffffff", \
                        "background_music_is_personalized": "system", \
                        "background_music_volume": 0.1, \
                        "frame_height": 1080, \
                        "frame_width": 1920, \
                        "is_personalized_audio": false, \
                        "scene_number": 1, \
                        "scene_transition": "none", \
                        "audio_id": 2, \
                        "audio_service": "google_audio", \
                        "user_voice_speed": 1, \
                        "x_position": 0.604931, \
                        "y_position": 0.43101 \
                    } \
                ] \
            } 

{   
    "id": 178,
    "message": "Requests Created",
    "successful_requests_count": 3,
    "failed_requests_count": 0,
    "failed_requests": []
}