Skip to main content

Process

POST 
/api/v1/assets/:asset_id/process

Assets can be processed for image transformations, video transcodes and other custom workflows using /process API.

The /process API is useful in the following scenarios:-

  • Create static image conversions that are not covered by On-demand Image Conversion
  • Re-process a static image conversion to apply a new watermark
  • Re-process an image if there are any on-demand image conversion errors
  • Generate standard video transcodes that do not exist for a video file
  • Re-apply a new watermark to existing video transcodes

Built-in Image processing keys

KeyDescription
smart_imagingUsed for on-demand images and image annotation re-processing

Also, once processing completes, Asset Data JSON will contain process state for smart_imaging as below:

"addons_info": {
    "ON_DEMAND_IMAGE": {
      "available": true
    }
  }

Built-in Video processing keys

  • Built-in keys that correspond to video quality and sizes: 360p-video, 480p-video, 720p-video, 1080p-video, hls-video
  • Watermarked transcodes: 360p-wm-video, 480p-wm-video,720p-wm-video,1080p-wm-video
warning

For hls-video transcode, the source video must be equal or greater than 360 px in height. If a source video smaller than 360 px in height, please enable UPSCALE option in Video Settings for hls-video to generate HLS transcodes. In general, you do not need a HLS video transcode for a video that is small as there is no bandwidth benefit for small videos.

Special video processing keys

KeyDescription
clip_previewGenerate a preview clip of the video using user's settings profile
storyboardGenerate a set of storyboard images for the video using user's video settings profile. STORYBOARD addon must be enabled for this.

Public or private video transcodes

By default each video transcode is stored public or private as set for that key in the account's Video Settings. Pass "public": true or "public": false to override that for the video transcodes of this request only (including hls-video and clip_preview); account settings are not changed. Public transcodes get permanent, unsigned links — public_url and embed_url in Get Data — that suit websites; private ones need Get Link signed URLs. Sending public requires asset edit permission, the same as Set Public Access.

{"keys": ["480p-video", "720p-video"], "public": true}

Note:

  1. That unknown keys and keys that do not apply to the file type will be ignored.
  2. This API returns job ID only for videos.

Note: Once a image/video conversion is processed, callbacks are issued to registered webhooks.

Video credits​

On self-serve plans (Pay as you go, Growth, Scale and the free trial) video processing is paid in credits, per minute of the uploaded (source) video, metered to the second. Each request is rounded up to a whole credit.

OutputCredits per minute of video
SD MP4 (up to 720p)2
HD MP4 (1080p)4
4K MP4 (above 1080p)8
hls-video (adaptive streaming, every quality up to 1080p)8
storyboard1

The full cost of the request is checked and taken before processing starts. If the account doesn't have enough credits, the API returns 402 with {"error": "insufficient_credits", "required": <credits>, "balance": <credits>} and nothing is queued. A rendition that fails is refunded. Processing the same keys again is charged again. Enterprise plans are billed per their agreement.

HTTP Response​

Standard HTTP Status code - 202 or 200

KeyValueDescription
statusstringStatus of the process. Can be QUEUED or ERROR
messagestringMessage describing the status
job_idintegerJob ID of the process. Can be used to query the status of job using [Job Status API]
publicbooleanPresent only when the request sent public: the visibility the video transcodes will get

Request​

Responses​

Successful operation