Vidds API

At Vidds, our goal is to make video creation and editing as easy as possible. Our API is an extension of that goal. We aim to make our API the same – simple to use and understand, and easy to accomplish what you need! With the API, you can automate and scale your video creation.

Table Of Contents

Overview

Our API is based on our editor. That means it is scene-based, and you can customize your video and scenes easily.

When you use the API for the first time, you will provide a template id from a video you’ve already created. The API will load your template, then apply each modification you make, such as changing text, images, videos, colors, and more.

Playing Around

While we aim to make this documentation complete and thorough, we highly recommend you try out our API tools first. We have two powerful tools to help you understand the API by using it directly in your web browser!

1. Naming – When scenes and elements are created in your video template, they are assigned a random ID. With the API enabled, you will see a section below the video settings with a link to the Naming tool. This allows you to rename the IDs to something human-readable so your API requests will be clear. For example, the first scene might have an ID of “XDf1”, and you might rename it to “intro” to be more clear. If there’s an image element within that scene, you could rename it to “logo”.
   
2. Playground – Once you’ve renamed your scenes and elements, click the Playground link to open the API testing tool. In the playground, you can select any template, then click the “+” button, select a scene or element, then get a list of all the modifications you can make (for example, a text element will allow you to change the text, color, background, etc). Once you’ve made a few modifications, click Apply to reload your video with all of the changes made. Last, you can use the Export button to get a JSON-formatted list of modifications you can paste into a script to get you started.

The playground is great for self-documenting our API and allows you to see the full list of changes you can make, so you can see exactly what happens with a live preview!

API Keys

In order to submit a request, you need an API key. To create an API key, log in to your dashboard, click the user icon in the upper right, then account, then choose the “API” tab at the top. In the API tab, you can click “Create a New Key,” then enter your password and a title for the key. Once it’s created, you will see the key displayed. Copy the key and save it somewhere – once you close the modal, you will not be able to see the key again.

Can’t see the API tab? The Vidds API is in early access mode, so you may need to contact us (support@vidds.co) to enable it for your account.

Submitting a Request

The Vidds API doesn’t require any SDK! It’s a simple HTTP request to submit your first request. And it’s so easy, you can use the “curl” command line tool to test it out!

Generating a new video requires 3 things:

1. A POST request to https://creator.vidds.co/app/auto/gen
2. An authentication header: Authorization: Bearer <your api token>
3. A JSON-formatted body with the request content.

Here’s a sample JSON request:

{
 "template_id": 123,
 "title": "First auto-gen’d Video!",
 "render": true, 
 "modifications": [
   {"id":"_video","bg_color":"#fff", "width":"1920","height":"1080"},
   {"id":"intro.brand","text":"Vidds API Test","color":"#48f"},
   {"id":"intro.message","text":"My first video created with the API!"},
   {"id":"content.desc","text":"Updating text, images, videos, and more!","color":"#4e62d5"},
   {"id":"content.bg","src":"https://vidds.co/wp-content/uploads/2020/11/YouTube-Video.mp4"},
   {"id":"intro.logo","src":"https://vidds.co/wp-content/uploads/2020/10/VIDDS-LOGO-CONCEPT-1-2.svg"},
   {"id":"cta.brand","text":"Wow, so easy!"}
 ]
}

You can see that it includes the template_id (which you can find in the Playground), a title for the new video, render set to true, and a list of modifications to make.

Other Requests

You can also check the status of a request. More information is provided #below.

API Response

The API response will vary based on what you submit and the current status of the API request. The API responds immediately, but rendering can take minutes.

If it’s successful, the status will be 200 (or 2xx). Errors will be 4xx or 5xx.

Here’s a sample successful response:

{“id”:22,”token_id”:1,”state”:1,”reference”:null,”status”:”Template saved – 385″,”log”:null}

Here’s a sample error response:

{“error”:”Request error: {‘idx’: 1, ‘msg’: ‘Modifier not found: textx’}”}

The Request JSON

You can use the playground to generate a request and see all available options. Here is a breakdown of each option. All keys are case-sensitive (should be lower case).

template_id

The ID of the template to use to generate the full video. To find the template ID, you can select a video from the playground, then click export to see the included template_id field.

title

The new title for the video. If not provided, it will be auto-generated based on the title of the template used.

save / render

For each API request, you must specify either save or render and set the value to true. For most API uses, you will want to render the video. When you’re getting started, or if you might need to modify the result manually, the save option will save it as a new template on your dashboard.

reference

Create a reference value for this request. This is an optional string you can associate with the API call. The reference serves two purposes:

1. A value you can use to refer to how it was created, or what it was created based on. For example, if you created a video based on blog posts, you could assign the value “blog 13” so you know the video was rendered for blog post #13.
2. (Not implemented) Prevent accidental re-runs. If a reference value has already been submitted to Vidds, the request will be aborted with an error stating the reference has already been run.

charge

Specify the payment method(s) for the API request. This is a comma separated list of each method that you will allow, and in the order in which they should be used. Ex: “api,credit,plan”.

• api: Use API credits
• plan: Use plan credits from a recurring Vidds plan
• credit: If we’ve provided you with video credits, this will use those credits
• pay: Charge the credit card on file for this video

Your method is billed based on the length of your video. Larger videos (such as rendering 4k) will incur additional usage.

We recommend using the ‘api’ option – API credits are provided per second and billed that way, while other credits are rounded (eg a 5-minute plan credit will be used even if your video is 2 minutes long).

modifications

Modifications are the main part of the request. They specify exactly what to change within your template before rendering.

You only need to provide modifications that you want to change. Your template already includes the current settings, and the modifications only override them. For example, There is no need to specify video modifications of {width: 1920, height: 1080} if that is already the size of your template. Similarly, there’s no need to specify text modification like {color: “#000”} if the text already has that color.

Each modification includes an “id” field which specifies what to change. The ID will be one of:

• _video – This specifies the video itself (for changing dimensions, background colors, etc)
• scene-name – If the ID is of a scene, it will modify the scene settings (duration, background color, etc)
• scene.element – This specifies an element within a scene. Element modifications depend on the type (text, media, shapes, etc).

A Note on Scene Timing

When you render a video with the API, it might not be the same length as the template you provided.

A powerful feature of Vidds is automatically calculating how long a scene is displayed based on the content within it. This allows you to change a video within a scene and have it adjust to play the entire video. Similarly, adding longer text or shorter text will change the length of a scene.

If this is not desirable (for example, you want every API to create the same length video), you can override this in the Vidds editor by setting the scene length manually, or you can set it through the API.

With that, let’s get into the modifications!

Don’t see what you’re looking for?

The Vidds API is in open beta. We wanted to release early to allow everyone to start benefiting and give us feedback. If there’s a feature in the editor that you don’t see here, contact Vidds support and we’ll get it out as quickly as we can!

_video Modifications

• bg_color: The background color applied to the entire video. Should be specified in hex. Ex: “#000”
  Note: If a scene is given a background color, it will be displayed over the video.
• width: Width of the video, in pixels. Ex: 1920
• height: Height of the video, in pixels. Ex: 1080

Scene Modifications

• bg_color: The background color for the scene. Should be specified in hex. Ex: “#fff”
• dur: Duration of the scene, in seconds. Ex: 4.5 (4 ½ seconds)
  Note: You can also set this to the string “auto” to have Vidds auto-calculate the scene length.

Element Modifications

Each element type has specific modifications that can be applied to them, but there are a few modifications that apply to all elements:

• remove: Remove the element from the new video. Boolean. Ex: true
• b_radius: The border radius of the element, in pixels. Ex: 12
• rotate: The rotation of the element, in degrees. Ex: 90

Text Element Modifications

• text: The new text to display in the element.
  Ex: “My new text\nAnd maybe a second line”
• color: The color of the text, specified in hex.
  Ex: “#f00”
• bg_color: The background color of the element.
  Ex: “#0000” (Note the 4th 0 for the alpha channel, making this example transparent)
• font: The font and weight to apply to the element. This field can be any font available at https://fonts.google.com. It must include the font weight as well.
  Ex: “Cinzel Decorative:700” (Font name + “:” + weight)

Media Element Modifications

• src: The URL of the new media content. Ex: “https://mysite.com/videos/post1.mp4”
  Note: You can switch between media types. An image can be replaced with another image, a video, or an audio file.
  Video formats: Video formats are very complex, and we recommend using media files that are browser-friendly for best results. Mp4 and webm are recommended, although others may load depending on the codecs used.

Shape Element Modifications

Progress Bar Element Modifications

Request: Generate Status

When you generate a new video, the ID of the request is provided in the response. You can use this (or the reference in the future) to check the status.

To check the status, you need:

1. A GET request to https://creator.vidds.co/app/auto/status/<id>
2. An authentication header, Authorization: Bearer <your api token>

API Response JSON

Above, we showed a sample successful response from the auto/gen endpoint. Here are the full details

• id: The ID of the request
• next_check: Recommended time to wait before checking the status again
• state: The state of the request (this should be 1)
• reference: If a reference was provided, it will be set here
• status: A string status
• log: Any log messages related to your request
• render_state: Pending (0), Generating(1), Complete (2), Error (3)
• render_perc: If the render is generating, the percentage of the generate step
• render_status: String display similar to what is displayed in the dashboard (Starting, Generating, Finalizing, etc)

video_url: If the render has completed, a temporary URL to access the video
Note: Vidds does not provide video hosting, and this URL should be used to download the video. The URL will expire, although you can request the status again to get a new URL.