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:
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
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"}}}]}
Instead of the dummy source.url
it is possible to provide source.asset_id
and use a video uploaded to our service previously. Find out more at creating an asset
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 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 to our render requires adding a text
element to our elements
array.
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 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",}}}]}
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:
REQUESTcurl \-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.
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:
REQUESTcurl \--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:
REQUESTcurl \--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!