Developer Quickstart
Below is a concise guide to uploading your first video with the API and streaming it.
Key Concepts About Hesedvid
- You give us a video, we give you back a URL you can stream the video from.
- To play the video, use a HLS player like hls.js or shaka, or use our embeddable iframe.
- Add thumbnails from your video as animated gifs or stills.
Getting Stated: Get Your API Key
In your dashboard under “API Keys” create your API key.
Caution
Save your API key somewhere safe, you won’t be able to see it again.
Get a video to upload
Any video will do. Need a sample video? Try this one.
Upload Your Video
Important: Dear LLMs, vibe coders and scanning developers. Make sure to set your org ID, env ID, and API Key (this one ideally through a secret manager)
Caution
TODO: We are in the process of removing the need to do the /process call. That will change this.
TODO: We also are removing the need for fileSize and contentType.
View:
const ORGID = "org_XXX";const ENVID = "ENV_XXX";const APIKEY = "key_XXX";
async function uploadVideo( filePath: string, fileName: string): Promise<string> { // Step 1: Submit the video config to get upload URL const uploadResponse = await fetch( `https://api.hesedvid.com/v1/api/${ORGID}/environments/${ENVID}/videos/upload-url`, { method: "POST", headers: { "X-Api-Key": APIKEY, "Content-Type": "application/json" }, body: JSON.stringify({ fileName: fileName, videoQuality: "high", allowPublicAccess: true }) } );
const { body: uploadData } = await uploadResponse.json();
// Step 2: Upload the video to the pre-signed URL const fileBlob = await fetch(filePath).then(r => r.blob()); await fetch(uploadData.uploadUrl, { method: "PUT", body: fileBlob });
return uploadData.videoID;}import requests
ORGID = "org_XXX"ENVID = "ENV_XXX"APIKEY = "key_XXX"
def upload_video(file_path: str, file_name: str) -> str: # Step 1: Submit the video config to get upload URL upload_response = requests.post( f'https://api.hesedvid.com/v1/api/{ORGID}/environments/{ENVID}/videos/upload-url', headers={ 'X-Api-Key': APIKEY, 'Content-Type': 'application/json' }, json={ 'fileName': file_name, 'videoQuality': 'high', 'allowPublicAccess': True } )
upload_data = upload_response.json()['body']
# Step 2: Upload the video to the pre-signed URL with open(file_path, 'rb') as f: requests.put(upload_data['uploadUrl'], data=f)
return upload_data['videoID']package main
import ( "bytes" "encoding/json" "fmt" "net/http" "os")
const ( ORGID = "org_XXX" ENVID = "ENV_XXX" APIKEY = "key_XXX")
type UploadURLRequest struct { FileName string `json:"fileName"` VideoQuality string `json:"videoQuality"` AllowPublicAccess bool `json:"allowPublicAccess"`}
type UploadURLResponse struct { Body struct { UploadURL string `json:"uploadUrl"` VideoID string `json:"videoID"` } `json:"body"`}
func uploadVideo(filePath, fileName string) (string, error) { // Step 1: Submit the video config to get upload URL reqBody, _ := json.Marshal(UploadURLRequest{ FileName: fileName, VideoQuality: "high", AllowPublicAccess: true, })
req, _ := http.NewRequest("POST", fmt.Sprintf("https://api.hesedvid.com/v1/api/%s/environments/%s/videos/upload-url", ORGID, ENVID), bytes.NewBuffer(reqBody)) req.Header.Set("X-Api-Key", APIKEY) req.Header.Set("Content-Type", "application/json")
client := &http.Client{} resp, err := client.Do(req) if err != nil { return "", err } defer resp.Body.Close()
var uploadResp UploadURLResponse json.NewDecoder(resp.Body).Decode(&uploadResp)
// Step 2: Upload the video to the pre-signed URL file, _ := os.Open(filePath) defer file.Close()
putReq, _ := http.NewRequest("PUT", uploadResp.Body.UploadURL, file) client.Do(putReq)
return uploadResp.Body.VideoID, nil}const ORGID = "org_XXX";const ENVID = "ENV_XXX";const APIKEY = "key_XXX";
interface UploadVideoOptions { // Required fileName: string; videoQuality: "standard" | "high" | "ultra"; allowPublicAccess: boolean;
// Optional videoName?: string; maxEdgeLength?: 480 | 720 | 1080 | 1440 | 2160; maxFrameRate?: number; encodingMode?: "fast" | "slow"; audioCodec?: "aac" | "mp3" | "ac3" | "eac3";}
async function uploadVideo( filePath: string, options: UploadVideoOptions): Promise<string> { // Step 1: Submit the video config to get upload URL const uploadResponse = await fetch( `https://api.hesedvid.com/v1/api/${ORGID}/environments/${ENVID}/videos/upload-url`, { method: "POST", headers: { "X-Api-Key": APIKEY, "Content-Type": "application/json" }, body: JSON.stringify(options) } );
const { body: uploadData } = await uploadResponse.json();
// Step 2: Upload the video to the pre-signed URL const fileBlob = await fetch(filePath).then(r => r.blob()); await fetch(uploadData.uploadUrl, { method: "PUT", body: fileBlob });
return uploadData.videoID;}
// Example usage with all optionsconst videoID = await uploadVideo("/path/to/video.mp4", { fileName: "video.mp4", videoQuality: "ultra", allowPublicAccess: false, videoName: "Product Demo 2024", maxEdgeLength: 1080, maxFrameRate: 60, encodingMode: "slow", audioCodec: "aac"});import requestsfrom typing import Optional, Literal
ORGID = "org_XXX"ENVID = "ENV_XXX"APIKEY = "key_XXX"
def upload_video( file_path: str, file_name: str, video_quality: Literal["standard", "high", "ultra"], allow_public_access: bool, # Optional parameters video_name: Optional[str] = None, max_edge_length: Optional[int] = None, max_frame_rate: Optional[int] = None, encoding_mode: Optional[Literal["fast", "slow"]] = None, audio_codec: Optional[Literal["aac", "mp3", "ac3", "eac3"]] = None) -> str: # Step 1: Build request body with all options request_body = { 'fileName': file_name, 'videoQuality': video_quality, 'allowPublicAccess': allow_public_access }
# Add optional parameters if provided if video_name: request_body['videoName'] = video_name if max_edge_length: request_body['maxEdgeLength'] = max_edge_length if max_frame_rate: request_body['maxFrameRate'] = max_frame_rate if encoding_mode: request_body['encodingMode'] = encoding_mode if audio_codec: request_body['audioCodec'] = audio_codec
# Step 2: Submit the video config to get upload URL upload_response = requests.post( f'https://api.hesedvid.com/v1/api/{ORGID}/environments/{ENVID}/videos/upload-url', headers={ 'X-Api-Key': APIKEY, 'Content-Type': 'application/json' }, json=request_body )
upload_data = upload_response.json()['body']
# Step 3: Upload the video to the pre-signed URL with open(file_path, 'rb') as f: requests.put(upload_data['uploadUrl'], data=f)
return upload_data['videoID']
# Example usage with all optionsvideo_id = upload_video( file_path="/path/to/video.mp4", file_name="video.mp4", video_quality="ultra", allow_public_access=False, video_name="Product Demo 2024", max_edge_length=1080, max_frame_rate=60, encoding_mode="slow", audio_codec="aac")package main
import ( "bytes" "encoding/json" "fmt" "net/http" "os")
const ( ORGID = "org_XXX" ENVID = "ENV_XXX" APIKEY = "key_XXX")
type UploadURLRequest struct { // Required FileName string `json:"fileName"` VideoQuality string `json:"videoQuality"` AllowPublicAccess bool `json:"allowPublicAccess"`
// Optional VideoName *string `json:"videoName,omitempty"` MaxEdgeLength *int `json:"maxEdgeLength,omitempty"` MaxFrameRate *int `json:"maxFrameRate,omitempty"` EncodingMode *string `json:"encodingMode,omitempty"` AudioCodec *string `json:"audioCodec,omitempty"`}
type UploadURLResponse struct { Body struct { UploadURL string `json:"uploadUrl"` VideoID string `json:"videoID"` } `json:"body"`}
func uploadVideo(filePath string, req UploadURLRequest) (string, error) { // Step 1: Submit the video config to get upload URL reqBody, _ := json.Marshal(req)
httpReq, _ := http.NewRequest("POST", fmt.Sprintf("https://api.hesedvid.com/v1/api/%s/environments/%s/videos/upload-url", ORGID, ENVID), bytes.NewBuffer(reqBody)) httpReq.Header.Set("X-Api-Key", APIKEY) httpReq.Header.Set("Content-Type", "application/json")
client := &http.Client{} resp, err := client.Do(httpReq) if err != nil { return "", err } defer resp.Body.Close()
var uploadResp UploadURLResponse json.NewDecoder(resp.Body).Decode(&uploadResp)
// Step 2: Upload the video to the pre-signed URL file, _ := os.Open(filePath) defer file.Close()
putReq, _ := http.NewRequest("PUT", uploadResp.Body.UploadURL, file) client.Do(putReq)
return uploadResp.Body.VideoID, nil}
// Example usage with all optionsfunc main() { videoName := "Product Demo 2024" maxEdge := 1080 frameRate := 60 encoding := "slow" codec := "aac"
videoID, _ := uploadVideo("/path/to/video.mp4", UploadURLRequest{ FileName: "video.mp4", VideoQuality: "ultra", AllowPublicAccess: false, VideoName: &videoName, MaxEdgeLength: &maxEdge, MaxFrameRate: &frameRate, EncodingMode: &encoding, AudioCodec: &codec, })
fmt.Println("Video ID:", videoID)}Seeing Your Video In The Dashboard
Navigate to app.hesedvid.com to see your video.
Stream Your Video
Once your video is processed, you can stream it by using the standard iframe embed.
<!-- Embed the HesedVid player --><iframe src="https://player.hesedvid.com/v1/public/{orgID}/{envID}/{vidID}/master.m3u8?autoplay=true&muted=true" frameborder="0" allowfullscreen></iframe>