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:

veed_test_oEnZhnd3vg0LEoTs6Z9Ij

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 crop, trim, and add text:

The result we want to achieve is:

Constructing the render object

As you can see the video has been cropped, trimmed and some text has been added. To achieve these 3 changes, 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 (such as videos, images, text, etc.)

More on this can be found at render object​

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:

Render object w/ video
{
  "elements": [
    {
      "type": "video",
      "params": {
        "source": {
          "url": "https://cdn.veed.dev/380rreVE_9uhiksitOGIW.mp4" 
        }
      }
    }
  ]
}

Crop

Following the render object reference, cropping the video is simple. All you need to do is add a crop object, as a member of the video element params. The following picture shows how the crop object acts on the video element:

Render object w/ video (crop)
{
  "elements": [
    {
      "type": "video",
      "params": {
        "source": {
          "url": "https://cdn.veed.dev/380rreVE_9uhiksitOGIW.mp4" 
        },
        "crop": {
          "x": 100,
          "y": 100,
          "width": 500,
          "height": 300,
        }
      }
    }
  ]
}

Trimming

Trimming a video is as simple as cropping. You just pass in an additional trim object to the video elements params. (Note that trim values are in seconds)

Render object w/ video (crop & trim)
{
  "elements": [
    {
      "type": "video",
      "params": {
        "source": {
          "url": "https://cdn.veed.dev/380rreVE_9uhiksitOGIW.mp4" 
        },
        "crop": {
          "x": 100,
          "y": 100,
          "width": 500,
          "height": 300
        },
        "trim": {
          "from": 2.0,
          "to": 5.0
        },
      }
    }
  ]
}

Adding text

Adding text to our render requires adding a text element to our elements array.

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

Render object w/ video (crop & trip) and text
{
  "elements": [
    {
      "type": "video",
      "params": {
        "source": {
          "url": "https://cdn.veed.dev/380rreVE_9uhiksitOGIW.mp4" 
        },
        "crop": {
          "x": 100,
          "y": 100,
          "width": 500,
          "height": 300
        },
        "trim": {
          "from": 2.0,
          "to": 5.0
        },
      }
    },
    {
      "type": "text",
      "params": {
        "value": "My First Render!",
        "position": {
          "x": "center",
          "y": "top",
        }
      }
    }
  ]
}

Sending the request

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

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

REQUEST
curl \
  -X POST \
  --header "Authorization: veed_test_oEnZhnd3vg0LEoTs6Z9Ij" \
  --data @render.json \
  https://api.veed.dev/render

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

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

The returned id represents the task that is in charge of rendering. The id is used to track the progress of the render and get the final result.

Obtaining the finished 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:

REQUEST
curl \
  --header "Authorization: veed_test_oEnZhnd3vg0LEoTs6Z9Ij" \
  https://api.veed.dev/render/b477e483-592a-4bc6-a22b-563ef7f48e25

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 PROGRESS , which will look like this:

RESPONSE
  {
    "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 complete. Once it reaches 100 your render is done, and you need to poll the API once more:

REQUEST
curl \
  --header "Authorization: veed_test_oEnZhnd3vg0LEoTs6Z9Ij" \
  https://api.veed.dev/render/b477e483-592a-4bc6-a22b-563ef7f48e25

This time we get a SUCCESS response.

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

Once you have the url you can download the resulting render and enjoy your new video!

​