Skip to main contentIBM Video Streaming Developers

Upload videos

To upload a file you must do the following steps:

  1. Initiate an upload process by an API call. In the response you can find the video ID for the new upload and an upload ID that you will have to send with every request.
  2. Upload the video in 1MB parts. You might need to make several requests in this stage until all the parts of the video file have been uploaded.
  3. When the upload is finished, send an “upload complete” signal, which will start the processing of your video.
  4. Call the API to check the status of processing the video.

Initialize an upload

Initiate the upload process.

POST https://api.video.ibm.com/v2/channels/{channel_id}/uploads.json

Parameters

The parameters for the POST request:

PARAMETERTYPEIMPORTANCEDESCRIPTION
titlestringOPTIONALVideo title
descriptionstringOPTIONALVideo description
protectstringOPTIONALVideo protection level. Supported values: public, private

Success response

Upon success a response with HTTP status “201 Created” is returned with the key-value pairs containing the video ID and upload ID.

Example of a success response:

{
"videoId": 1234567890,
"uploadId": "28691235606490ab81a8c0.96744426"
}

Error responses

Possible error responses:

HTTP RESPONSE CODEERROR VALUEERROR CONDITIONS
400 Bad Requestprotect_level_invalidInvalid protect level has been sent
401 Unauthorizedinvalid_tokenThe provided access token is missing, revoked, expired or malformed
403 Forbiddenlack_of_ownershipThe API user is not allowed to manage the given channel
404 Not Foundnot_foundChannel was not found
503 Service UnavailableThere is a temporary error on the server which makes it impossible to serve the request

Upload the video file

In this stage you need to upload the video file in 1MB parts. You can find an example of this in the downloadable PHP sample code: https://developers.video.ibm.com/channel-api-php-sample-code

Before you start uploading the parts, you will need to calculate the total number of parts and the total size of the file.

To upload one part send a multi-part file request to this endpoint:

POST https://api.video.ibm.com/v2/channels/{channel_id}/uploads/{video_id}/part.json

Parameters

The parameters for the POST request:

PARAMETERTYPEIMPORTANCEDESCRIPTION
uploadIdstringREQUIREDThe upload ID from the init response
partIndexintREQUIREDThe index of the current part
totalPartCountintREQUIREDThe total number of parts that will be uploaded
totalFileSizeintREQUIREDThe total size of the video file
filebinaryREQUIREDThe current file part’s content

Success response

Upon success a response with HTTP status “200 OK” is returned with the key-value pairs containing the video ID and upload ID.

Error responses

Possible error responses:

HTTP RESPONSE CODEERROR VALUEERROR CONDITIONS
400 Bad RequestInvalid parameters. Look at the returned hint value for the exact error.
401 Unauthorizedinvalid_tokenThe provided access token is missing, revoked, expired or malformed
403 Forbiddenlack_of_ownershipThe API user is not allowed to manage the given channel
404 Not Foundnot_foundChannel or video was not found
413 Payload too largefile_too_largeThe incoming file is larger than 4GB
503 Service UnavailableThere is a temporary error on the server which makes it impossible to serve the request

Send “upload completed” signal

The “upload completed” signal tells to our server that it can start to process the file.

POST https://api.video.ibm.com/v2/channels/{channel_id}/uploads/{video_id}/completed.json

Parameters

The parameters for the POST request:

PARAMETERTYPEIMPORTANCEDESCRIPTION
uploadIdstringREQUIREDThe upload ID from the init response

Success response

Upon success, a response with HTTP status “200 OK” is returned.

Error responses

Possible error responses:

HTTP RESPONSE CODEERROR VALUEERROR CONDITIONS
400 Bad RequestInvalid parameters. Look at the returned hint value for the exact error.
401 UnauthorizedThe provided access token is missing, revoked, expired or malformed
404 Not Foundnot_foundChannel or video was not found
503 Service UnavailableThere is a temporary error on the server which makes it impossible to serve the request

Check status of processing

Returns the status of processing the specific video.

GET https://api.video.ibm.com/channels/{channel_id}/uploads/{video_id}.json

Parameters

This request has no parameters.

Success response

Upon success a response with HTTP status “200 OK” is returned with a key-value pair.

KEYTYPEDESCRIPTION
statusstringThe current status. Possible values: initiated, transferred, queued, pending, transcoding, complete, error

Error responses

Possible error responses:

HTTP RESPONSE CODEERROR VALUEERROR CONDITIONS
401 UnauthorizedThe provided access token is missing, revoked, expired or malformed
404 Not Foundnot_foundChannel was not found
503 Service UnavailableThere is a temporary error on the server which makes it impossible to serve the request