Now you've signed up, and obtained your API key, you are ready to start editing video. In this example, we will show you how to construct a request that will trim and add text to a video


Getting Ready

All of the interactions with VEED API are RESTful and, as such, each request sent to our system needs to contain your API key as a part of the Authorization header. Make sure you have your API key ready. You can find it in your dashboard and it should look something like this:

key_test_XXXXXXXXXXXXXX

Next, of course, we need your video! You can either use an existing public url where the video is stored, or try out our asset service to upload and store the video yourself. (This walkthrough will show you how to render video via a public url but you can also check out our creating an asset guide for more info on the assets feature)

In this walkthrough we will be using the following video to trim and add text:


Expected Result

By the end of this video, we would have successfully edited the video embed above and our final render will be as shown below:

You will notice that the video has been trimmed and some text has been added automatically.


Constructing the render object

To achieve the edits above, we need to create a render object. A render object is made up of global parameters (such as aspect ratio, background colour, output format), and a list of elements and assets (such as videos, images, text, etc.) with which the final render is created.

More on this can be found at render object

We will now construct our render object in 4 steps as outlined below:

1. Adding a video element

Every render object needs at least one entry in the elements array. We'll start off with the source video shown above. When making the request, change the source.url string to match the location of the video you are planning to use:

{
  "elements": [
    {
      "type": "video",
      "params": {
        "source": {
          "url": "https://storage.googleapis.com/veed-docs/sample-video.mp4" 
        }
      }
    }
  ]
}

πŸ“˜

Note

Instead of the dummy source.url it is possible to provide source.asset_id and use a video uploaded to our service previously.


2. Trimming the video

Trimming videos is a simple process with our API. You just pass in an additional trim object to the video elements params as shown below. Note that trim values are specified in seconds.

{
  "elements": [
    {
      "type": "video",
      "params": {
        "source": {
          "url": "https://storage.googleapis.com/veed-docs/sample-video.mp4" 
        },
        "trim": {
          "from": 2.0,
          "to": 5.0
        }
      }
    }
  ]
}

3. Adding Text to the video

Having successfully specified the trimming parameters, our final task is to add some text to the video. Adding text to our render requires adding a text element to our elements array.

πŸ“˜

Note

Elements use the array index as a guide for layering, starting from the bottom, and working up. So we need to append our text (after the other elements), so that it appears as the top layer on the video.

The only required parameter is value (the string of text you want to include), but we will also have to provide a position object, to place it using alignment string enums. You can, of course, use precise pixel values if you wish.

{
      "type": "text",
      "params": {
        "value": "My First Render!",
        "position": {
          "x": "center",
          "y": "top",
        }
      }
    }
}

Sending the request

Having successfully added all the appropriate configurations to trim and add some text to the video, we should now have one render object that looks like this:

{
    "elements": [{
            "type": "video",
            "params": {
                "source": {
                    "url": "https://storage.googleapis.com/veed-docs/sample-video.mp4"
                },
                "trim": {
                    "from": 2.0,
                    "to": 5.0
                }
            }
        },
        {
            "type": "text",
            "params": {
                "value": "My First Render!",
                "position": {
                    "x": "center",
                    "y": "top"
                }
            }
        }
    ]
}

Now that we have our render object created, we need to send a request to start the rendering process.

Save the object above to a file called render.json. Then, from the directory where the file is saved, run the curl command below with the file name as a POST body. Make sure to change the API key to match the one from your dashboard:

curl \
  -X POST \
  --header "Content-Type: application/json" \
  --header "Authorization: key_test_XXXXXXXXXXXXXX" \
  --data @render.json \
  https://api.veed.io/api/renders

If the render request is successfully queued, you will get a response like this:

{
  "id": "b477e483-592a-4bc6-a22b-563ef7f48e25"
}

The returned id represents the task that is in charge of rendering. The id can be used to track the progress of the render and get the final result when it has been completed.

πŸ“˜

Note

If you already have a webhook configured on your dashboard, you will automatically receive a message whenever the status of a render changes.


Getting the final render

In this example, we will get the result by polling the API. Alternatively, you can use the webhook method (which we recommend - find out more, here).

As soon as you get the response, you can start polling the API, using the id returned earlier:

curl \
  --header "Authorization: veed_test_XXXXXXXXXXXXXXXX" \
  https://api.veed.io/api/renders/{your-render-id}

You will now get a new response, which will tell you the status: QUEUED , PROGRESS , SUCCESS, FAILED.

If your rendering pool is empty, the request should start immediately and your first response should be of type RENDER/PROGRESS , which will look like this:

{
    "type": "RENDER/PROGRESS",
    "payload": {
      "id": "b477e483-592a-4bc6-a22b-563ef7f48e25",
      "progress": 56,
    }
  }

Inside the payload object you will get a progress field, which indicates the percentage of rendering that has been completed. Once it reaches 100, your render is done and you need to poll the API once more.

curl \
  --header "Authorization: veed_test_XXXXXXXXXXXXXXXX" \
  https://api.veed.io/api/renders/b477e483-592a-4bc6-a22b-563ef7f48e25

This time you should get a response of type RENDER/SUCCESS.

{
    "type": "RENDER/SUCCESS",
    "payload": {
      "id": "b477e483-592a-4bc6-a22b-563ef7f48e25",
      "progress": 100,
      "url": "https://cdn.veed.dev/R1vqZ0KfPp5y2z7ddiTyt.mp4"
    }
  }

Now that you have the url, you can download the resulting render and enjoy your new video!