API documentation

REST API documentation

The REST API allows you to generate videos.

Billing

Videos are cost 1 credit. You can view your credit balance via the interface.

Authorization

Finding your API Key

You can find your API Key by clicking the code button on the editor.

Authorizing a request

Include an Authorization header in your requests to the API.

Authorization: Bearer <API Key>

Concepts

Video

The video configuration used to render a video.

The video can be automatically generated via the editor. Click on the </> button to generate the JSON which matches the editor.

Field Type Description
title String The title of this video
ratio ["square", "landscape", "portrait"] The size of the video
music String A URL to an MP3 to use as background music
voice String The voice ID to use
primary_colour String Hex color used for some templates
text_colour String Hex color of text with primary_colour background
title_font String A Google font to use for title text
body_font String A Google font to use for other text
components [Component] A list of components (max 30). See Title, Text, and CTA components below.

Voice

The text to speech voice over.

Beta voices are not currently available via the API

ID Gender Accent
Emma female american
Olivia female american
Ava female american
Charlotte female american
James male american
Matthew male american
Amy female british
Emily female british
Robert male british
David male british

Title Component

A title component with title and subtitle

Field Type Description
type "title" The component type
template [0, 1, 2, 3] The style template to use. See editor to try.
title String Max length 200 characters
subtitle String Max length 200 characters
image String (optional) A URL to an image to use

Text Component

A text component

Field Type Description
type "text" The component type
template [0, 1, 2, 3] The style template to use. See editor to try.
text String Max length 500 characters
image String (optional) A URL to an image to use
animation [null, "zoom_in", "zoom_out", "slide_up", "slide_down", "slide_left", "slide_right"] The image animation used if an image is included

 

To use videos instead of images, replace the image field with the URL to your video. Note that it must be WebM vp9 format and the url must end in ".webm"

CTA Component

A call to action component

Field Type Description
type "cta" The component type
template [0] The style template to use. See editor to try.
text String Max length 200 characters
image String (optional) A URL to an image to use
theme ["dark", "light"] Dark uses primary_colour as background, light uses white.

Render

Field Type Description
id String The render ID
video_id String The video ID
status ["pending", "preprocessing", "rendering", "postprocessing", "complete", "error"] The rendering status
progress Integer The % progress of rendering
video_url String URL to the video
thumbnail_url String URL to thumbnail image
animated_thumbnail_url String URL to thumbnail GIF
subtitles_url String An SRT thumbnail file
metadata Object video metadata including video duration in seconds

Endpoints

https://api.vidon.ai/v1

GET /video/<video_id>

This endpoint retrieves a video object

GET /video/<video_id>/render/<render_id>

This endpoint retrieves a render object. This can be polled every minute until the video status is either "complete" or "error".

Response - New video

Example response from a newly created video

{
"id": '1',
"video_id": '1',
"status": 'pending',
"progress": 0,
}

Response - Rendering video

Example response from a video which is rendering

{
"id": '1',
"video_id": '1',
"status": 'rendering',
"progress": 50,
}

Response - Completed video

Example response from a completed video

{
"id: '1',
"video_id": '1',
"status": 'complete',
"progress": 100,
"video_url": 'https://storage-dev.getvidon.com/video/OyAtMMnvZK/render/6wVS4dztXi/video.mp4',
"thumbnail_url": 'https://storage-dev.getvidon.com/video/OyAtMMnvZK/render/6wVS4dztXi/thumbnail.jpg',
"animated_thumbnail_url": 'https://storage-dev.getvidon.com/video/OyAtMMnvZK/render/6wVS4dztXi/thumbnail.gif',
"subtitles_url": 'https://storage-dev.getvidon.com/video/OyAtMMnvZK/render/6wVS4dztXi/subtitles.srt',
"metadata": {"duration": 6}
}

Response - Error video

Example response if the video had an error

{
"id": '1',
"video_id": '1',
"status": 'error',
"message": "Unable to render video",
}

POST /video

This endpoint creates a video render returning the render ID. You must poll the video until the video status is complete.

We recommend polling every 1 minute.

Video generation takes between 30 seconds and 5 minutes depending on the length of the video.

Request

The video can be automatically generated via the editor. Click on the </> button to generate the JSON which matches the editor.

Post a video object, an example request:

{
  "ratio": "square",
  "music": "https://storage.getvidon.com/assets/music/The_Limit.mp3",
  "voice": "Olivia",
  "face": "https://storage-dev.getvidon.com/assets/presenter/h6fa.png?t=2",
  "primary_colour": "#f9c015",
  "text_colour": "#FFFFFF",
  "title_font": "Inter",
  "body_font": "Inter",
  "components": [
    {
      "type": "title",
      "template": 0,
      "theme": null,
      "image": null,
      "subtitle": "My subtitle",
      "title": "My title"
    },
    {
      "type": "text",
      "template": 3,
      "theme": null,
      "image": false,
      "text": "Some text"
    },
    {
      "type": "cta",
      "template": 0,
      "theme": "light",
    "image": null,
      "text": "A call to action"
    }
  ]
}

Response

API returns a render object, an example response. Use the GET /video/<video_id>/render/<id> endpoint to poll the video status.

{
"id": "1",
"video_id": "1",
"status": "pending",
"progress": 0,
}

Error response

{
"error": "invalid_request",
"message": "Field "music" must be a valid URL"
}

NodeJS Create video example

Here is a sample written in NodeJS which creates a new video and polls for the response every 30 seconds.

const fetch = require('node-fetch')

// NOTE: This will charge 1 credit per video

const API_KEY = 'YOUR_API_KEY' // TODO: replace with your api key

const BASE_URL = 'https://api.vidon.ai/v1'

const video = {
  "title": "Test video",
  "ratio": "square",
  "music": "https://storage.getvidon.com/assets/music/Hey_Oh_Young_Pop.mp3",
  "voice": "Olivia",
  "face": "https://storage-dev.getvidon.com/assets/presenter/h6fa.png?t=2",
  "primary_colour": "#f9c015",
  "text_colour": "#FFFFFF",
  "title_font": "Inter",
  "body_font": "Inter",
  "components": [
    {
      "type": "text",
      "template": 3,
      "animation": "zoom_out",
      "text": "hello world",
      "image": false
    },
  ]
}

async function vidon_api(endpoint, data) {
  let res = await fetch(`${BASE_URL}/${endpoint}`, {method: data ? 'POST' : 'GET', body: data ? JSON.stringify(data) : null, headers: {'Content-Type': 'application/json', 'Authorization': `Bearer ${API_KEY}`}})
  let json = await res.json()

  return json
}

async function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms))
}

async function create_video(video) {
  console.log('Creating video...')

  let data = await vidon_api(`video`, video)

  console.log('Created video:', data)

// Poll every 30 seconds until the video is ready, max 10 retries
let attempts = 10
  for (let i=0; i<attempts; i++) {
    await sleep(30 * 1000) // Sleep for 30 seconds

    // Check video status
    data = await vidon_api(`video/${data.video_id}/render/${data.id}`)

    if (data.status === 'complete' || data.status === 'error') {
      break
    }

    console.log(`Video not complete yet:`, data)
  }

  console.log('Video complete:', data)
}

create_video(video)