Introduction
The Kuikads API gives you the ability to generate personalized videos, at scale, on demand.
Please take your time to read through this documentation to understand how you can best utilise the Kuikads API to achieve a new level of communication and engagement with your market.
In this documentation you will find a high-level overview of the processes involved in creating videos using our API.
We will use a simple “Happy Birthday” video example to explain the key elements of the process.
Our API
Take a quick look through our docs to see how everything works
Key concepts
There are four key concepts in the Kuikads API solution which we will cover in this document:
- Asset management
- The client
- The Kuikads API
- Distribution
Asset management
Before you can generate any videos, you'll need to prepare the images, videos or font files you want to include. These assets are then uploaded to our cloud storage servers using the /v1/assets endpoint.
The preparation requirements for each asset type are as follows:
Images
Images can be used both as scene backgrounds and as overlaying elements (such as logos).
For images you intend to use as scene backgrounds, you will want to ensure that the images are cropped to the same aspect ratio as the video you intend to use them in.
Videos
Video assets can be used as scene backgrounds. Like images, videos need to be cropped to match the aspect ratio of the video being generated. However, videos also need to be trimmed to the length of the scene they will be a part of.
If the video is shorter than the scene duration, it will be slowed down to fill the whole scene.
If the video is longer than the scene duration, the end of the video will simply be cut off.
Custom Fonts
We have a number of built-in fonts you can use in your videos, however you may want to use your own custom fonts, and you can!
No preparation is necessary for custom fonts you would like to use however, they must be uploaded in True Type (.TTF) format.
It should also be noted that we can only render text in font variations (e.g. bold, italics) that we have access to. Some fonts have variations included as a single font file, however other fonts have them in seperate files. If you want to use a font variation in your videos, ensure it is uploaded alongside your “regular” font.
The client
The client, is you! 🥳 Or, the client is your system. This could be a web application, backend service, third party integration tool (e.g. Zapier) or whatever suits your needs best.
The client needs to be able to manage 5 key responsibilities:
- The trigger event
- Sending the "create video" request
- Ingesting the proceeding webhook request
- Retrieving and storing the generated video
- Distribution
The trigger event
When we refer to the “trigger” we are referring to whatever condition that is met which triggers a video to be created (and later distributed). This could be some action by a user like registering for your application, or perhaps you would like to alert interested parties to a new product release. The possibilities are endless.
In our example, the trigger is a calendar event. Every day, we will run a script which retrieves customers who’s birthday is today, and request a video for each of them that wishes them a happy birthday.
Sending the "create video" request
Once a trigger has been activated, the next step is to send the request which will initiate a video generation.
Requesting a video is easy. There are only two required properties in the payload: template_id and variables.
The template_id references a template (which will have been created prior to this process).
The variables property is a key:value list which will define what values to place in the template to personalise the video being generated.
(Variables are defined in the video template created prior to this process)
In our Happy Birthday example, the "create video" request payload would look something like:
{
"template_id": "8cec521f-8eo0-4683-aefb-0cfa60f4a791",
"variables": {"name": "John"}
}
In response, the Kuikads API will return the a Video schema which includes the template_id and variables that were sent in your request, plus an id for the video.
In addition, a status parameter will be included which, at this stage, will either indicate that the generation is IN_PROGRESS or, if something has gone wrong, the status will be FAILED.
There will also be a temp_storage_url parameter which will later be filled with the URL you can download the generated video from.
In our Happy Birthday example, the "create video" response would be:
{
"id": "c38d50f3-1ea1-4d7d-b686-85d756a91cb8",
"template_id": "8cec521f-8eo0-4683-aefb-0cfa60f4a791",
"variables": {"name": "John"},
"status": "IN_PROGRESS",
"temp_storage_url": null
}
Ingesting the webhook (and handling the video file)
A few seconds after sending the create video request, a webhook will be sent to your configured webhook endpoint. In the payload, you will see the id of your video record, a status (either COMPLETED or FAILED), and the temp_storage_url you can retrieve the video from.
In our Happy Birthday example, the webhook payload would look something like this:
{
"id": "c38d50f3-1ea1-4d7d-b686-85d756a91cb8",
"template_id": "8cec521f-8eo0-4683-aefb-0cfa60f4a791",
"variables": {"name": "John"},
"status": "COMPLETED",
"temp_storage_url": "https://cdn.kuikads.com/hb_20250327-153757.mp4"
}
As the key would suggest, the temp_storage_url is a temporary url. This is because typically we do not handle long-term storage of your generated videos (unless some special arrangement has been agreed to). For this reason, we recommend that you use this url to download the video and store it in your own cloud storage (S3 bucket, Google Cloud etc.)
If the status is FAILED, the temp_storage_url parameter will be replaced by an error property which will simply give you the error message.
So, the process is:
-
Ingest the webhook (and update your records with the new status)
-
Retrieve the video file from the temp_storage_url
-
Upload the file to your cloud storage provider
The Kuikads API
The Kuikads API is us 🥳 this is the tool you will use to generate your hundreds, thousands, or even millions of personalized videos quickly and easily.
The v1 API has three key resources (some of which we have talked about in the previous section) that we will cover:
-
Assets
-
Templates
-
Videos
Assets
Assets are any media or custom font files you would like to include in your videos. This may include:
-
Logos
-
Music
-
Background images
-
Background videos
-
Custom fonts (.TTF)
The files should be prepared as described above before being uploaded to our cloud storage via the /v1/assets endpoint.
Once assets have been uploaded, you can reference them either as variables or in your templates by using the id value returned in the response from our API.
Templates
Templates are the foundation of your videos. Instead of requiring a whole schema every time you create a video, we allow you to create video templates which define reusable components of videos (e.g. the height and width of the video) and personalize those videos by using variables.
Kuikads can create templates for you if requested.
Videos
Videos are what we are all here for! 🥳 Once you have your assets prepared and uploaded, and a template created, you are ready to start creating videos.
Creating a video is as simple as sending a POST request to our /v1/videos endpoint (link to docs). in the request payload you will pass in a reference_id for the video (so you can link responses back to your own records) a template_id of the template you want to use to generate the video, and a list of variables to pass in to the template.
Assuming everything was set up correctly, you will receive a webhook to your pre-configured webhook endpoint which will update you with the status of the video (one of FAILED or COMPLETED).
-
If the status is FAILED, there will also be an error property which will contain the actual error message for troubleshooting.
-
If the status is COMPLETED, there will be a temp_storage_url property which you can use to download your generated videos.
Note: Kuikads will not store your videos long-term unless some special arrangement has been made. Typically, we will only store them temporarily so that you can retrieve them after they are generated.
Distribution of your videos
The distribution of your videos is in your hands, however we do have a few suggestions:
-
Whatsapp
Whatsapp is fast becoming a leader in customer communication around the world and is a perfect distribution channel for Kuikads' personalised videos.
Utilising the Whatsapp API requires your organisation to be a trusted sender (Whatsapp will not allow you to bulk send messages unless you have proven to not be a source of spam). Information about this can be found in their documentation.
There are a few key benefits to distributing via whatsapp:
- Embed videos in your messages directly (unlike with email).
- Seamlessly integrate with Meta cloud storage.
- Integrations available with third party services (Zapier, Twilio etc.)
-
Email
Email is a tried-and-true channel for communications. There are a number of reliable third-party email gateways you can use to send emails including Mailchimp, Mailgun or Twilio (and many more).
Unfortunately, what you can and can’t include in the content of an email is limited by both yours, and the recipient’s email provider. In general, and notably with the most common email providers, Videos cannot be embedded in the email message. However, some of the aforementioned email gateways offer features to include video thumbnails which you can use to direct the recipient to their personalised video.
-
Rich Communication Services (RCS)
RCS is a modern messaging standard that aims to replace SMS and MMS, offering richer features like high-resolution photos, larger files, read receipts, and group chats, all within the native messaging app.
In a nutshell, sending via RCS means you can send your video files over the internet, but they will be received as though they were an SMS (or MMS) message. RCS is now compatible on Android and iPhone.
A number of third-party gateways exist to facilitate the sending of RCS messages such as ClickSend or Telesign (and many more).