Video best practices

How to create & upload a video

The concept of creating and uploading a video is pretty simple:

  1. Create a video object: Think about it as a box or shell for the video. Once you've created a video object, it's an empty shell, however, it has an id and assets.
  2. Upload a video: Now you can upload your video into that object.

A tutorial for uploading a video with curl can be found here

A more visual representation can be found below:

A diagram that shows the steps of creating a video object, and uploading a video A diagram that shows the steps of creating a video object, and uploading a video

Important things to know

  • All qualities encoding: The video object will include up to 6 responsive video streams from 240p to 4K
  • Video size: The video file size is limited to 30 GiB. The files will be compressed to fit delivery needs (4k max def with H.264 at 60fps max + AAC)
  • Highest quality encoding by default: Mp4 encoded versions are created at the highest quality (max 4K) by default.
  • 360° videos support: Panoramic videos are videos recorded in 360°. You can toggle this after your 360° video upload.
  • Video Access Management: When creating a video object, it can be either private or public. The feature allows you to change it later by updating the video object.
  • Progressive Upload: Ability to upload videos in a progressive manner while they are being recorded.

Recommendations

For optimal ingestion, the video should use:

  • Resolution ≤ 4k
  • Video codec: h264
    • ≤ 1080p max bitrate: 16Mbps
    • > 1080p ≤ 4k max bitrate: 50Mbps
  • Standard Dynamic Range: yuv420p
  • Framerate ≤ 60fps
  • Audio Codec: aac

Limitations

  • When using the sandbox environment, the API:
    • limits the videos you upload to 30 seconds
    • adds a watermark to your videos that you cannot remove
    • deletes uploaded videos after 24 hours
  • The API deletes empty video containers after 7 days.
  • When using progressive upload:
    • a video uploaded in a single chunk must be between 0 and 200MiB
    • a video uploaded in several chunks must use at most 10 000 chunks each between 5MiB and 200MiB except the last chunk which must be between 0 and 200MiB
  • a video must be uploaded/downloaded/copied in at most 7 days (168 hours)
  • an uploaded/downloaded/copied video must be:
    • at most 30 GiB
    • of at most 24h
  • ProRes RAW video codec is currently not supported.

Progressive video upload & uploading large videos

Some videos you might upload could be very large in size. We made sure that this is addressed and that there's a convenient way to upload large videos while breaking them into chunks. Please be sure to read the guide on how to make progressive video upload.

Video Access Management

The video object will be created as public by default. If you want to make the video private, you just need to create a private video object or update it later. You can read all about Private Videos here

  • Searchable parameters: title, description, tags and metadata
$ curl https://ws.api.video/videos \
    -H 'Authorization: Bearer {access_token} \

-d '{"title" : "My video", "description" : "so many details", "mp4Support" : true }'`

Create a video from a URL

You can also create a video directly from a video hosted on a third-party server by giving its URI in source parameter:

$ curl https://ws.api.video/videos \
   -H 'Authorization: Bearer {access_token} \

-d '{"source":"http://uri/to/video.mp4", "title":"My video"}'`

In this case, the service will respond 202 Accepted and ingest the video asynchronously.

Resources

Check out api.video's blog content and tutorials about:

Was this page helpful?

On this page