Quickstart
Step 1: Generate API key
1. Navigate to your Workspace-Invite-API
2. Click the “Get API Key” button. Your unique API key will be displayed within seconds.
Note: This feature requires a Pro plan.
Important: Treat your API key like a password. Keep it confidential and do not share it with anyone.
Step 2: Post a long video
Please note that the Vizard.ai API currently supports videos that can be downloaded directly through web browser, and YouTube, Google Drive, Vimeo, StreamYard link.
Request
URL
https://elb-api.vizard.ai/hvizard-server-front/open-api/v1/project/create
Method: POST
Rate Limits: 3 requests per minute
Headers
Name of Header | Value | Required |
---|---|---|
Content-Type | application/json | YES |
VIZARDAI_API_KEY | Vizard ai api key | YES |
Body (Raw json)
Name | DataType | Required | Description |
---|---|---|---|
lang | string | YES | Language code of video. |
videoUrl | string | YES | The URL of the remote video should start with either http or https. |
ext | string | NO | The extension of the video file. Options: mp4, 3gp, avi, mov. If videoType is 1, ‘ext’ needs to be set. |
preferLength | array | YES | The duration of the clipped video: 0: auto; 1: less than 30s; 2: 30s to 60s; 3: 60s to 90s; 4: 90s to 3min. |
projectName | string | NO | The name of the long video. |
subtitleSwitch | int | NO | Subtitle switch. 0: off; 1: on; (default value) |
headlineSwitch | int | NO | Headline switch. 0: off; 1: on; (default value) |
videoType | int | YES | 1: remote video file that can be downloaded directly through web browser; 2: YouTube link; 3: Google Drive link; 4: Vimeo link; 5: StreamYard link. |
maxClipNumber | int | NO | The maximum number of clips. Range: [0, 100]. |
keywords | string | NO | Keywords to include relevant content. If multiple keywords, separate them with commas. |
Response
Content-Type: application/json
Body
Data Name | Data Type | Description |
---|---|---|
code | int | 2000: created succeeded; 4001: invalid api key; 4002: created failed; 4003: requests exceeded the limit; 4004: unsupported video format; 4005: invalid video url; 4006: illegal parameter; 4007: insufficient remaining time in the account. |
projectid | string | Used for polling clips generation |
shareLink | string | The share link of project, when your subscription is team plan. |
Step 3: Get clips
Vizard.ai offers two ways to get clips. First, it can be obtained by polling. Second, the webhook address can be configured in the workbench. Once the webhook address is configured, Vizard.ai will send clips to the webhook address by posting json content, please process the request body to get clips. Either way, you’ll get the same json content. Please note: for webhook address, we currently only do one callback, please make sure your server is available, otherwise you will have to poll clips.
Poll Request
URL
https://elb-api.vizard.ai/hvizard-server-front/open-api/v1/project/query/{projectId}
Method:GET
Headers
Name of Header | Value | Required |
---|---|---|
VIZARDAI_API_KEY | Vizard ai api key | YES |
Parameters
Name | Data Type | Required | Description |
---|---|---|---|
projectId | Long | YES | Get the video export result by projectId. Please append it to https request url, behind ’/query/’. |
Poll Response
Content-Type: application/json
Body
Data Name | Data Type | Description |
---|---|---|
code | int | 1000: processing; 2000: clipping succeeded; 4001: invalid api key; 4002: clipping failed; 4003: requests exceeded the limit; 4004: unsupported video format; 4005: invalid video url; 4006: illegal parameter; 4007: insufficient remaining time in the account; 4008: failed to download from video url |
videos | array | A list of URLs for video clips. The video URL is valid for 3 hours. Please ensure that you complete the download within this time frame. If the 3-hour period expires, you can query again to obtain a new valid video URL. It is important to note that after 7 days, the video will be permanently deleted. |
shareLink | string | The share link of project, when your subscription is team plan. |
Video
Field Name | Data Type | Description |
---|---|---|
projectId | Long | The id of project. |
videoUrl | string | Video download URL. |
videoMsDuration | long | Video duration in milliseconds. |
title | string | Video title. |
viralReason | string | AI clip reason. |
viralScore | float | AI clip score. |
transcript | string | Video text content. |
relatedTopic | array | Video related topics. |
Appendix
Video languages
Language Name | Language Code |
---|---|
English | en |
Arabic (عربي) | ar |
Bulgarian (български) | bg |
Croatian (Hrvatski) | hr |
Czech (čeština) | cs |
Danish (Dansk) | da |
Dutch (Nederlands) | nl |
Finnish (Suomi) | fi |
French (Français) | fr |
German (Deutsch) | de |
Greek(Ελληνικά) | el |
Hebrew (עִברִית) | iw |
Hindi (हिंदी) | hi |
Hungarian (Magyar nyelv) | hu |
Indonesian (Bahasa Indonesia) | id |
Italian (Italiano) | it |
Japanese (日本語) | ja |
Korean (한국어) | ko |
Lithuanian (Lietuvių kalba) | lt |
Malay (Melayu) | mal |
Mandarin - Simplified (普通话-简体) | zh |
Mandarin - Traditional (國語-繁體) | zh-TW |
Norwegian (Norsk) | no |
Polish (Polski) | pl |
Portuguese (Português) | pt |
Romanian (Limba română) | ro |
Russian (Pусский) | ru |
Serbian (Српски) | sr |
Slovak (Slovenský) | sk |
Spanish (Español) | es |
Swedish (Svenska) | sv |
Turkish (Türkçe) | tr |
Ukrainian (Україна) | uk |
Vietnamese (Tiếng Việt) | vi |
File types
mp4, 3gp, avi, mov
Maximum video length
360 mins
Maximum file size
8GB
Video storage
As long as you are subscribing
Upload minutes
Same as the minutes in your plan
Resolution of the clips
Vizard.ai exports as high resolution video as possible based on the width and height of the original video, as well as the aspect ratio of the clip video. In general, the smallest side of the clip video will be higher than the smallest side of the original video.
Sample Code
Python
import requests
import time
VIZARDAI_API_KEY = "YOUR_VIZARD_AI_API_KEY"
PROJECT_NAME = "api-vizard-sample"
VIDEO_URL = "https://cdn-docs.vizard.ai/openapi/sample.mp4"
VIDEO_FILE_EXT = "mp4"
LANG = "en"
PREFER_LENGTH = "[0]"
SUBTITLE_SWITCH = 1
HEADLINE_SWITCH = 1
VIDEO_TYPE = 1
headers = {
"Content-Type": "application/json",
"VIZARDAI_API_KEY": VIZARDAI_API_KEY
}
def create_project():
create_data = {
'projectName': PROJECT_NAME,
'videoUrl': VIDEO_URL,
'ext': VIDEO_FILE_EXT,
'lang': LANG,
'preferLength': PREFER_LENGTH,
'subtitleSwitch': SUBTITLE_SWITCH,
'headlineSwitch': HEADLINE_SWITCH,
'videoType': VIDEO_TYPE,
}
create_url = "https://elb-api.vizard.ai/hvizard-server-front/open-api/v1/project/create"
print('creating project')
response = requests.post(create_url, headers=headers, json=create_data)
create_result = response.json()
if response.status_code == 200:
print(create_result)
if create_result["code"] == 2000:
project_id = create_result["projectId"]
else:
print("create error:", create_result)
project_id = ""
else:
print('create request failed: ', create_result)
project_id = ""
return project_id
def query_clips(project_id):
query_url = "https://elb-api.vizard.ai/hvizard-server-front/open-api/v1/project/query/" + str(project_id)
while (True):
print('querying clips...')
response = requests.get(query_url, headers=headers)
if response.status_code == 200:
query_result = response.json()
if query_result["code"] == 2000:
print('clipping succeeded.')
print(query_result)
break
elif query_result["code"] == 1000:
time.sleep(5)
continue
else:
print(query_result)
print("clipping error:")
if 'message' in query_result:
print(query_result['message'])
break
else:
print('query request failed: ', response.json)
break
def main():
project_id = create_project()
if (project_id != ""):
query_clips(project_id)
if __name__ == "__main__":
main()
Java
import java.io.*;
import java.net.*;
import org.json.*;
public class VizardSample {
private static final String VIZARDAI_API_KEY = "YOUR_API_KEY";
public static void main(String[] args) {
String projectId = createProject();
queryClips(projectId);
}
private static String createProject() {
try {
URL url = new URL("https://elb-api.vizard.ai/hvizard-server-front/open-api/v1/project/create");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("POST");
conn.setRequestProperty("Content-Type", "application/json");
conn.setRequestProperty("VIZARDAI_API_KEY", VIZARDAI_API_KEY);
conn.setDoOutput(true);
// JSONObject jsonObject = buildRequestParametersForRemoteVideoFile();
JSONObject jsonObject = buildRequestParametersForYouTubeLink();
try (OutputStream os = conn.getOutputStream()) {
os.write(jsonObject.toString().getBytes("utf-8"));
}
int status = conn.getResponseCode();
StringBuilder response = new StringBuilder();
try (BufferedReader br = new BufferedReader(new InputStreamReader(conn.getInputStream(), "utf-8"))) {
String responseLine;
while ((responseLine = br.readLine()) != null) {
response.append(responseLine.trim());
}
}
JSONObject responseJson = new JSONObject(response.toString());
if (status == HttpURLConnection.HTTP_OK && responseJson.getInt("code") == 2000) {
String projectId = String.valueOf(responseJson.getInt("projectId"));
System.out.println("Project created, and projectId is " + projectId);
return projectId;
} else {
System.out.println("Create error: " + responseJson.toString());
return "";
}
} catch (Exception e) {
System.out.println("Create request failed: " + e.getMessage());
return "";
}
}
private static void queryClips(String projectId) {
if (projectId == null || projectId.isEmpty()) {
System.out.println("projectId is empty");
return;
}
while (true) {
try {
System.out.println("Querying clips...");
URL url = new URL("https://elb-api.vizard.ai/hvizard-server-front/open-api/v1/project/query/" + projectId);
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("GET");
conn.setRequestProperty("Content-Type", "application/json");
conn.setRequestProperty("VIZARDAI_API_KEY", VIZARDAI_API_KEY);
StringBuilder response = new StringBuilder();
try (BufferedReader br = new BufferedReader(new InputStreamReader(conn.getInputStream(), "utf-8"))) {
String responseLine;
while ((responseLine = br.readLine()) != null) {
response.append(responseLine.trim());
}
}
JSONObject responseJson = new JSONObject(response.toString());
if (conn.getResponseCode() == HttpURLConnection.HTTP_OK) {
if (responseJson.getInt("code") == 2000) {
System.out.println("Clipping succeeded.");
System.out.println(responseJson.toString());
break;
} else if (responseJson.getInt("code") == 1000) {
Thread.sleep(5000);
continue;
} else {
System.out.println("Clipping error:");
System.out.println(responseJson.toString());
break;
}
} else {
System.out.println("Query request failed: " + response.toString());
break;
}
} catch (Exception e) {
System.out.println("Query request failed: " + e.getMessage());
break;
}
}
}
private static JSONObject buildRequestParametersForRemoteVideoFile() {
JSONObject jsonObject = new JSONObject();
jsonObject.put("videoType", 1);
jsonObject.put("projectName", "api-sample-remote-video-file");
jsonObject.put("videoUrl", "https://cdn-docs.vizard.ai/openapi/sample.mp4");
jsonObject.put("ext", "mp4");
jsonObject.put("lang", "en");
jsonObject.put("preferLength", "[0]");
jsonObject.put("subtitleSwitch", 1);
jsonObject.put("headlineSwitch", 1);
return jsonObject;
}
private static JSONObject buildRequestParametersForYouTubeLink() {
JSONObject jsonObject = new JSONObject();
jsonObject.put("videoType", 2);
jsonObject.put("projectName", "api-sample-youtube");
jsonObject.put("videoUrl", "https://www.youtube.com/watch?v=qeu9ek_HygM");
jsonObject.put("lang", "en");
jsonObject.put("preferLength", "[0]");
jsonObject.put("subtitleSwitch", 1);
jsonObject.put("headlineSwitch", 1);
return jsonObject;
}
}
Go
import (
"bytes"
"encoding/json"
"fmt"
"io/ioutil"
"net/http"
"time"
)
const (
vizardAIKey = "YOUR_API_KEY"
createURL = "https://elb-api.vizard.ai/hvizard-server-front/open-api/v1/project/create"
queryURLBase = "https://elb-api.vizard.ai/hvizard-server-front/open-api/v1/project/query/"
contentType = "application/json"
)
func main() {
projectId := createProject()
if projectId != "" {
queryClips(projectId)
}
}
func createProject() string {
client := &http.Client{}
jsonData := buildRequestParametersForRemoteVideoFile()
// jsonData := buildRequestParametersForYouTubeLink()
req, err := http.NewRequest("POST", createURL, bytes.NewBuffer(jsonData))
if err != nil {
fmt.Println("Create request failed:", err)
return ""
}
req.Header.Set("Content-Type", contentType)
req.Header.Set("VIZARDAI_API_KEY", vizardAIKey)
resp, err := client.Do(req)
if err != nil {
fmt.Println("Create request failed:", err)
return ""
}
defer resp.Body.Close()
body, err := ioutil.ReadAll(resp.Body)
if err != nil {
fmt.Println("Create request failed:", err)
return ""
}
var responseJson map[string]interface{}
json.Unmarshal(body, &responseJson)
if resp.StatusCode == http.StatusOK {
if responseJson["code"].(float64) == 2000 {
projectId := fmt.Sprintf("%.0f", responseJson["projectId"])
fmt.Println("Project created, and projectId is", projectId)
return projectId
} else {
fmt.Println("Create error:", string(body))
return ""
}
} else {
fmt.Println("Create request failed:", string(body))
return ""
}
}
func queryClips(projectId string) {
if projectId == "" {
fmt.Println("projectId is empty")
return
}
fmt.Println("Querying clips...")
client := &http.Client{}
for {
req, err := http.NewRequest("GET", queryURLBase+projectId, nil)
if err != nil {
fmt.Println("Query request failed:", err)
break
}
req.Header.Set("Content-Type", contentType)
req.Header.Set("VIZARDAI_API_KEY", vizardAIKey)
resp, err := client.Do(req)
if err != nil {
fmt.Println("Query request failed:", err)
break
}
defer resp.Body.Close()
body, err := ioutil.ReadAll(resp.Body)
if err != nil {
fmt.Println("Query request failed:", err)
break
}
var responseJson map[string]interface{}
json.Unmarshal(body, &responseJson)
if resp.StatusCode == http.StatusOK {
if responseJson["code"].(float64) == 2000 {
fmt.Println("Clipping succeeded.")
fmt.Println(string(body))
break
} else if responseJson["code"].(float64) == 1000 {
time.Sleep(5 * time.Second)
continue
} else {
fmt.Println("Clipping error:")
fmt.Println(string(body))
break
}
} else {
fmt.Println("Query request failed:", string(body))
break
}
}
}
func buildRequestParametersForRemoteVideoFile() []byte {
jsonData := map[string]interface{}{
"videoType": 1,
"projectName": "api-sample-remote-video-file",
"videoUrl": "https://cdn-docs.vizard.ai/openapi/sample.mp4",
"ext": "mp4",
"lang": "en",
"preferLength": "[0]",
"subtitleSwitch": 1,
"headlineSwitch": 1,
}
data, _ := json.Marshal(jsonData)
return data
}
func buildRequestParametersForYouTubeLink() []byte {
jsonData := map[string]interface{}{
"videoType": 2,
"projectName": "api-sample-youtube",
"videoUrl": "https://www.youtube.com/watch?v=qeu9ek_HygM",
"lang": "en",
"preferLength": "[0]",
"subtitleSwitch": 1,
"headlineSwitch": 1,
}
data, _ := json.Marshal(jsonData)
return data
}
Curl
// create project for remote video file
curl -X POST "https://elb-api.vizard.ai/hvizard-server-front/open-api/v1/project/create" \
-H "Content-Type: application/json" \
-H "VIZARDAI_API_KEY: YOUR_VIZARD_AI_API_KEY" \
-d '{
"videoType": 1,
"projectName": "api-sample-remote-video-file",
"videoUrl": "https://cdn-docs.vizard.ai/openapi/sample.mp4",
"ext": "mp4",
"lang": "en",
"preferLength": "[0]",
"subtitleSwitch": 1,
"headlineSwitch": 1
}'
// create project for youtube link
curl -X POST "https://elb-api.vizard.ai/hvizard-server-front/open-api/v1/project/create" \
-H "Content-Type: application/json" \
-H "VIZARDAI_API_KEY: YOUR_API_KEY" \
-d '{
"videoType": 2,
"projectName": "api-sample-youtube",
"videoUrl": "https://www.youtube.com/watch?v=qeu9ek_HygM",
"lang": "en",
"preferLength": "[0]",
"subtitleSwitch": 1,
"headlineSwitch": 1
}'
// query clips
curl -X GET "https://elb-api.vizard.ai/hvizard-server-front/open-api/v1/project/query/{projectId}" \
-H "Content-Type: application/json" \
-H "VIZARDAI_API_KEY: YOUR_API_KEY"