OCT-103 Gumlet outreach
POST/video/assets/upload

Create a video asset for direct upload

Creates a video asset for local-file upload and media processing. Supply workspace_id and any optional asset settings; the response provides an upload_url for uploading the file with a PUT request. After creating the asset, send the file to that URL to complete the upload.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

27 body fields

Settings for creating an asset for direct upload. workspace_id is required; the body does not take an input URL.

additional_tracksarray<object>optional

Add additional Audio / Subtitle tracks to Gumlet for transcoding and delivery along with video asset track.

animated_gifobjectoptional

Create an animated GIF from the video.

audio_onlybooleanoptional

This flag allows Gumlet to transcode and deliver audio-only in the specified format. In this case, video transformation and thumbnails/animated GIFs would not be created. Default: false

call_to_actionsarray<object>optional

A CTA is an explicit prompt within the video content encouraging viewers to take a particular action.

collection_idstringdeprecatedoptional

Deprecated. Use workspace_id instead. Still accepted for backwards compatibility.

cropobjectoptional

This transformation can be used to crop the video by defining a rectangular area within the dimensions of the output video.

descriptionstringoptional

Attach some textual data with the asset. This field is neither searchable nor filterable.

enable_drmbooleanoptional

Enable DRM encryption for transcoded videos. Gumlet supports Widevine and FairPlay DRMs.

folderstringoptional

Add this asset to an existing folder by folder_id.

formatstringoptional

Transcode and deliver the asset in the requested format. The options can be one of ABR (HLS + DASH) and MP4.

Allowed:ABRMP4
generate_subtitlesobjectoptional

Gumlet allows you to generate subtitles from the audio stream (use <a href='https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes'> ISO 639-1 </a> Language Codes)

heightstringoptional

Resize video with the given height. Can be an absolute value in pixels or a percentage value with the % suffix. Specified values greater than the original asset height will be ignored. Applicable only when specified format is MP4.

image_overlayobjectoptional

Image overlay can be used to brand a video or add a visual label in the form of an image.

metadataobjectoptional

Add your metadata you want to associate with this asset.<br/> Example: <br/> <code> { "internal_video_id" : "123Abc" } </code>

mp4_accessbooleanoptional

Creates MP4 version for download purpose in case of MPEG-DASH or HLS delivery format. Default: false

padobjectoptional

This transformation can be used to add padding to the video.

per_title_encodingbooleanoptional

Gumlet analyzes each input video on a wide range of visual aspects. Based on the analysis, it chooses a unique set of transcoding options for processing the video. This ensures that the output video is of optimal size and best quality. Default: true

playlist_idstringoptional

Add this asset to a playlist.

process_low_resolution_inputbooleanoptional

Currently, the minimum supported frame size is 57600 (240x240) pixels for HLS/DASH and 21025 (145x145) pixels for MP4 format. However, enabling this flag will allow Gumlet to simply put your video asset into the specified delivery format without transcoding and optimization. Enabling this flag will cause any kind of specified video transformation to be ignored if you input video asset frame size is lower than the minimum supported frame size for the specified format. Default: false

profile_idstringoptional

Provide profile_id of the previously created video profile. This parameter will override all the parameters (except input and workspace_id) from the video profile.

resolutionstringoptional

Required resolutions of the transformed asset in case of HLS or MPEG-DASH delivery format. Can be a comma-separated string out of the following values: 240p, 360p, 480p, 540p, 720p, and 1080p. Resized rendition will retain the input aspect ratio.

tagarray<string>optional

Specify a text string or identifier which can identify an asset or bunch of assets later.

text_overlayobjectoptional

Text overlay can be used to brand a video or add a label in the form of text.

titlestringoptional

Specify a text string or identifier which can be used for filtering or searching the asset.

trimobjectoptional

Trim transformation can be used to trim videos based on time duration.

widthstringoptional

Resize video with the given width. Can be an absolute value in pixels or a percentage value with the % suffix. Specified values greater than the original asset width will be ignored. Applicable only when specified format is MP4.

workspace_idstringrequired

Gumlet video workspace ID. Preferred over deprecated collection_id / source_id (same ID).

7 status codes
200Returns the created asset object, including its asset_id, processing status, progress, and upload_url for uploading the video file with a PUT request.
asset_idstringoptional

Asset ID of the created asset

created_atintegeroptional

Created at timestamp in milliseconds since epoch

Default:0
inputobjectoptional
outputobjectoptional

Output data information

playlistsarray<string>optional

Information about playlists

progressintegeroptional

Processing progress percentage number between 0 and 100

Default:0
statusstringoptional

Status of asset

tagarray<string>optional
updated_atintegeroptional

Updated at timestamp in milliseconds since epoch

Default:0
upload_urlstringoptional

Upload URL on which you need to send actual file using PUT request

workspace_idstringoptional

Workdspace ID

400Returned when parameters are missing or invalid.

One documented failure

  • source_not_found

    Could not find any video source with specified source ID.

errorobjectrequired
401Returned when the API key or bearer token is missing or invalid.

One documented failure

  • source_not_found

    Could not find any video source with specified source ID.

errorobjectoptional
402Returned when the plan limit is exhausted.

One documented failure

  • plan_limit_exhausted

    You have consumed resources of your plan, please upgrade your plan to resuming it.

errorobjectrequired
403Returned when the account is unpaid or the authenticated user lacks the required role permissions.

One documented failure

  • unauthorized

    You don't have access to this feature. Please contact your organization owner.

errorobjectrequired
422Returned when request validation fails.

One documented failure

  • invalid_parameter

    body must have required property '<field>'

errorobjectrequired
500Returned when an internal server error occurs.

One documented failure

  • internal_server_error

    We have encountered some server error. We have been notified and will fix it soon.

errorobjectrequired

Error handling

A 400 is returned when parameters are missing or invalid, a 401 when the API key or bearer token is missing or invalid, a 402 when the plan limit is exhausted, a 403 for an unpaid account or insufficient role permissions, a 422 when request validation fails, and a 500 for an internal server error. workspace_id is required, and format must be ABR or MP4 when supplied.