Skip to main content

File import

The Streamdiver API enables importing files from several publicly available sources using:

  • direct HTTP(S) file download URLs
  • presigned URLs pointing to S3 storage
  • URLs pointing to public assets on popular online video platforms, like YouTube, Vimeo or ORF:ON

This guide will walk you through the process of creating an import, monitoring its status, and cancelling an import if needed.

Create file import​

To import files into the system, a new Import has to be created. Sending this request schedules the imports for asynchronous processing by our backend system, which will add them as new Media assets after the downloads finish. It is possible to import multiple files at once.

curl --request POST \
    --url https://api.streamdiver.com/v2/uploads/imports \
    --header 'Authorization: Bearer {token}' \
    --header 'Content-Type: application/json' \
    --data '{ 
                "files": [
                    {
                        "url": "https://example.com/file.mp4",
                        "name": "My asset name",
                        "filename": "file.mp4",
                        "transcriptionLanguageCode": "translate-en-v2"
                    },
                    {
                        "url": "https://youtube.com/samplevideo",
                        "name": "My youtube video name",
                        "transcriptionLanguageCode": "de-v2"
                    }
                ],
                "channel": "<uuid-of-target-channel>" 
            }'
info

For detailed request body parameters head to API reference

Monitor import status​

The Create a file import request will contain an id in the response body, which can be used to monitor the progress of the ongoing Import using Retrieve a file import:

curl --request GET \
    --url https://api.streamdiver.com/v2/uploads/imports/{id} \
    --header 'Authorization: Bearer {token}' \
    --header 'Content-Type: application/json'

An Import has an overall and a per-file status. The overall status is successful only when all imported files have finished with the status Success. In case an import for a particular file fails, the errorMessages may help identify the cause.

For each file in the Import an Upload entity is created and returned under uploadId in response body, which helps reference it to the newly created Media asset.

Cancel file import​

Mistakes happen, and in some cases, it might be necessary to cancel an ongoing Import.

curl --request PUT \
    --url https://api.streamdiver.com/v2/uploads/imports/{id} \
    --header 'Authorization: Bearer {token}' \
    --header 'Content-Type: application/json'
warning

The process will be cancelled only for files for which the import has not started yet.

Conclusion​

This guide provides the necessary steps to effectively use the File Import feature of the API. By following these instructions, you can create imports, monitor their statuses, and cancel them if needed. For any further questions or issues, please refer to the API documentation or contact support.