Get your API key
To generate a batch of Vidatas, you will need an API key, and the Id of your project. In our Platform, go into your Account , in the Token pannel, you will be able to manage your API tokens and get a API Key.
Your project ID will be sent to you by a Vidata administrator as soon as the project is created.
Exemple
7988fb58-4730-4bf8-8f89-efe8b632a820
Find the variables of your project
Each project is associated with a video and has a list of variables for which a customization will need to be sent.
You can use the API to retrieve them, using the query:
GET https://api.vidata.io/v1/video/{video_id}/variables
Sample query
GET https://api.vidata.io/v1/video/95d0224d-fc6f-4b55-88bf-a3e1c4400cf2/variables
Reply to your request
{
"Texts":
[
{
"ExampleValue": "Matthieu Rogier;",
"MaxLength": "100;",
"Name": "TXT_NAME;",
"DefaultValue": "Matthieu Rogier;",
{
"ExampleValue": "Métrologue;",
"MaxLength": "100;",
"Name": "TXT_METIER;",
"DefaultValue": "Métrologue;",
],
"Images":
[
],
"Videos":
[
]
}
Create a Vidata batch
Now that you have your API key, the project Id, and the list of variables, you can write your query. For each Vidata in the batch, you need to send a Customization, i.e. an object containing the video variables, and their value.
POST https://api.vidata.io/v1/vidata/batch?vkey=[API_KEY]
Informations
When you create your customizations dictionary, you can add
a field TXT_USEREMAIL to link the generated video to a unique email.
Sample query
POST https://api.vidata.io/v1/vidata/batch?vkey=[API_KEY]
{
ProjectKey: "7988fb58-4730-4bf8-8f89-efe8b632a820",
Customizations: [
{
"TXT_USEREMAIL" : "user1@mail.com",
"TXT_NAME": "Matthieu Rogier",
"TXT_METIER": "Métrologue",
},
{
"TXT_USEREMAIL" : "user2@mail.com",
"TXT_NAME": "Matthieu Rogier",
"TXT_METIER": "Métrologue",
}
]
}
}
Response
If the request is valid, the API will respond with an HTTP 201 Created status, and will return a batchId .
{
"batchId" : "c706af5f-27ac-407e-bc58-4541869cc69b"
}
Binding
Bindings (relation between a video variable name and a field name) can be defined per project on the vidata platform.
You can add an optional UseSavedBindings parameter. If the project has ben configured properly, the customization names in the request will be binded to the correct variable name in the video,
{
ProjectKey: "7988fb58-4730-4bf8-8f89-efe8b632a820",
UseSavedBindings: true,
Customizations: [
{
"name" : "Matthieu Rogier",
"TXT_METIER": "Métrologue",
},
]
}
}
Callback
On completion, the batch can send a callback and ping a specified url to let you know all the vidatas have been generated.
You can add an optional CompletionCallbackUrl parameter, along with the url you would like to use, as shown below
{
"ProjectKey": "string",
"Customizations": [
{
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
}
],
"CompletionCallbackUrl": "string"
}
Retrieve the batch status
Once you have a batchId, you can request its status and see the progress of the generation with the following query.
GET https://api.vidata.io/v1/vidata/batch/{batchId}?vkey=[API_KEY]&projectId=[project_Key_or_Id]
Sample query
GET https://api.vidata.io/v1/vidata/batch/{batchId}?vkey=[API_KEY]&projectId=[project_Key_or_Id]
{
BatchId = "c706af5f-27ac-407e-bc58-4541869cc69b",
ProjectId = "7988fb58-4730-4bf8-8f89-efe8b632a820",
CreationTimestamp = "2019-11-04T12:55:03.9798009+00:00",
State = "Running",
RemainingVideos = 10
}
The possible values for the state are:
- Pending: The batch has not started yet
- Running: The videos are being generated
- Completed: All the videos have been generated, and a report is ready
Export the batch output
When the batch is completed, you can export the result through the 2 following query.
For a result in JSON:
GET https://api.vidata.io/v1/vidata/batch/{batchId}/export?vkey=[API_KEY]&projectId=[project_Key_or_Id]
The result with return a list of all the Vidata created, along with the variables used and some additional information (mp4 url, cover url and vidata id)
"BatchId": "c706af5f-27ac-407e-bc58-4541869cc69b",
"Content": [
{
"TXT_USEREMAIL": "user1@mail.com",
"TXT_Var1": "exampleVar1",
"TXT_Var2": "exampleVaRr2",
...
"VDT_State": "Rendered",
"VDT_Video_Slug": "xxxxxxxxxxx",
"VDT_Video_Url": "https://vdtcariboustorage.blob.core.windows.net/video-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx-Resolution720p.mp4",
"VDT_Cover_Url": "https://vdtcariboustorage.blob.core.windows.net/video-cover-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.png",
"VDT_Landing_Page_Url": "https://contact.vidata.io/lp_example/?id=xxxxxxxxxxx",
"VDT_Video_Quality": "Resolution720p",
"VDT_Date_Created": "04/11/2019 13:55",
"VDT_Info": null
},
{
"TXT_USEREMAIL": ""user1@mail.com",
...
Additionally, the response can be requested in CSV:
GET https://api.vidata.io/v1/vidata/batch/{batchId}/export/csv?vkey=[API_KEY]&projectId=[project_Key_or_Id]
