Upload

The Streamdiver API works with an S3-compatible object storage hosted on GDPR-compliant infrastructure. For API uploads, either an S3 multipart or a PUT request procedure can be chosen. For files larger than approximately 5GB, we recommend the multipart procedure as a scalable and performant way to transfer them. We provide an endpoint and associated credentials that can be used with an S3 client of your choice. For smaller files, such as most audio or image assets, the PUT request upload is a reliable and easy-to-implement approach without the complexity of integrating an S3 client into your application.

In general the upload is performed in three steps: create, run and complete.

Create & Run Upload

Using the Bearer token from the authentication request as described in Authentication, you have to create an Upload for your Media asset using the fileName of your file as an input. Controlled by the type property, either a multipart (default) or an HTTP PUT request upload procedure can be selected.

When creating an Upload for a video or audio asset, specify the transcriptLanguageCode to set the language model for automatic transcription. Available language codes are tenant-specific and can be obtained from the transcription languages endpoint.

Continue with your chosen upload procedure!

Simple Upload

The simplest way to upload a file is with a single PUT request. To use this upload method, create a new Upload with type set to put:

curl --request POST \
    --url https://api.streamdiver.com/v2/uploads \
    --header 'Authorization: Bearer {token}' \
    --header 'Content-Type: application/json' \
    --data '{ "fileName": "myVideo.mp4", "type": "put" }'

Once you got the Upload response, retrieve the already authenticated upload URL from the url property of the input object. This URL can be used immediately to upload the source file like:

curl --request -v -X PUT -T myvideo.mp4 "https://storage-example.streamdiver.com/mytenant/videos/2022/12/65e6adcf-175a-400d-8a0c-f20a099157ce.mp4?X-Amz-Algorithm=AWS4-HMAC-SHA256&..."

Advanced upload with S3 client

For maximum speed and robustness, we also offer multipart uploading with an S3-compatible client. To use this upload method, create a new Upload (type is s3-multipart by default):

curl --request POST \
    --url https://api.streamdiver.com/v2/uploads \
    --header 'Authorization: Bearer {token}' \
    --header 'Content-Type: application/json' \
    --data '{ "fileName": "myVideo.mp4" }'

Once you got the Upload response, retrieve the credentials, the s3Endpoint target hostname and the objectKey from the input object. Any S3-compatible client can be used to perform the upload. Here is an example of how to upload your file using JavaScript and the AWS-SDK npm package.

//Initialize S3 client, credentials parameters are in the response of the CreateUpload request from step 1)
const credentials = new aws.Credentials({
    accessKeyId: {credentials.accessKey},
    secretAccessKey: {credentials.secretKey},
    sessionToken: {credentials.sessionToken},
});
var endPoint = upload.s3Endpoint; //Streamdiver storage endpoint, use property s3Endpoint in response of  of the CreateUpload request from step 1)
this.s3Client =  new aws.S3({
    credentials: credentials,
    endpoint: endPoint,
    s3BucketEndpoint: false,
    s3ForcePathStyle: true,
    signatureVersion: 'v4',
    logger: window.console,
});

//Perform upload, upload.bucket and upload.objectKey are in the response of the CreateUpload request from step 1)
const managedUpload = this.s3Client?.upload({
    Bucket: upload.bucket,
    Body: file,
    Key: upload.objectKey,
},{}, function(err, data) {
    if (err) {
        console.log("Upload ERROR", file, err);
    }
    else{
        console.log("Upload SUCCESS", file, data);
    }
});
managedUpload?.on('httpUploadProgress', function (progress) {
    console.log("PROGRESS:", file, progress.loaded / progress.total);
});

Complete Upload

After the upload has finished you have to call Complete upload to mark it as completed. This triggers further processing (transcoding and metadata extraction) of the asset. The parameter uploadId can be extracted from the id property of the Upload response provided in the first step.

Pass an optional channelId query parameter to assign the asset to a specific channel. If omitted, the asset is assigned to the default channel.

curl --request PUT \
    --url 'https://api.streamdiver.com/v2/uploads/{uploadId}/complete?channelId={channelId}' \
    --header 'Authorization: Bearer {token}' \
    --header 'Content-Type: application/json' 

In the response you get the assetId property (the ID of your Media asset), which can be used for further asset-specific requests against the Streamdiver API. You can retrieve your Media asset with a GET /media/{assetId} request.