Using the Reframe API

This quickstart guide provides ready-to-use cURL commands and instructions for the features of the Reframe API.

Overview

data-variant=info

data-slots=heading, text
NOTE
There are two Reframe API endpoints currently available. The v1 API has more limited capabilities and may be deprecated soon. It's recommended to use the v2 endpoint instead.

The Reframe API automatically adjusts video content to fit different aspect ratios while maintaining visual focus on important elements. Reframe videos for various social media platforms and add dynamic overlays like GIFs and images with precise timing and positioning controls.

This guide provides cURL commands for basic reframing and advanced overlay workflows. For even more technical details and tips, see the Usage Notes.

Before you start

Use reframing and scene edit detection

Use the cURL command example below to reframe your video. For best results, input video with a 16:9 aspect ratio format.

curl --location 'https://audio-video-api.adobe.io/v2/reframe' \
--header 'Authorization: ${ACCESS_TOKEN}' \
--header 'x-api-key: ${CLIENT_ID}' \
--header 'Content-Type: application/json' \
--data '{
  "video": {
    "source": {
      "url": "<pre_signed_URL>"
    }
  },
  "analysis": {
    "sceneEditDetection": true
  },
  "output": {
    "renditions": [
      {
        "aspectRatio": {
          "x": 1,
          "y": 1
        }
      },{
        "resolution": {
          "width": 1080,
          "height": 560
        },
        "mediaDestination": {
          "url": "<pre-signed_URL_for_output_video>"
        }
      },
      {
        "aspectRatio": {
          "x": 4,
          "y": 5
        }
      }
    ]
  }
}'

In the command, be sure to:

Provide the source

Activate Semantic Subject Lock

data-variant=info

data-slots=heading, text
NOTE
This feature relies on focal point and is only available with the Reframe API v2.

The Reframe API has Semantic Subject Lock, which allows you to declare a focal subject to guide reframing around a named object or subject using plain-language keywords. These keywords persist across scene boundaries, ensuring the same subject stays locked even through cuts.

Omit focal points if:

Declare a focal point subject

Provide keywords in the focalPoints array to enable Semantic Subject Lock on an object or product:

"analysis": {
  "sceneEditDetection": true,
  "focalPoints": [
    "car",
    "people"
  ]
}

If no focal points are provided, the API defaults to saliency-based reframing.

Adjust the output

data-variant=info

data-slots=heading, text
NOTE
Some output features are only available with the Reframe API v2.
"analysis": {
    "sceneEditDetection": true
}

"output": {
    "renditions": [
        {
            "resolution": {
                "width": 1080,
                "height": 1080
            }
        }
    ]
}

"output": {
    "format": {
        "sidecar": "otio"
    }
}

When this option is enabled, you can download a .zip archive containing:

For full details, see the API Reference.

Add video overlays

Overlays enable you to add assets as dynamic layers (for example: GIFs, animated PNGs, PNG) on top of a video, customized for positioning, size, timing, and behavior.

Use the cURL command example below to extend the Reframe API payload by defining overlays. The overlays array determines how one or more overlay assets are applied.

curl --location 'https://audio-video-api.adobe.io/v2/reframe' \
--header 'Authorization: ${ACCESS_TOKEN}' \
--header 'x-api-key: ${CLIENT_ID}' \
--header 'Content-Type: application/json' \
--data '{
  "video": {
    "source": {
      "url": "<pre_signed_URL>"
    },
  },
  "analysis": {
    "sceneEditDetection": true
  },
  "composition": {
    "overlays": [
      {
        "source": {
          "url": "<pre_signed_overlay_URL>"
        },
        "startTime": "00:00:10:15",
        "duration": "00:00:05:00",
        "scale": {
          "width": 400,
          "height": 400
        },
        "position": {
          "anchorPoint": "center",
          "offsetX": 0,
          "offsetY": 0
        },
        "repeat": "loop"
      }
    ]
  },
  "output": {
    "renditions": [
        {
          "aspectRatio": {
            "x": 1,
            "y": 1
          },
          "resolution": {
            "width": 1080,
            "height": 560
          },
          "mediaDestination": {
            "url": "<pre-signed_URL_for_output_video>"
          }
        },
        {
          "aspectRatio": {
            "x": 16,
            "y": 9
          }
        }
      ]
  }
}'

In the command, be sure to:

Each overlay object has many customizable properties to adjust the result. For full details, see the API Reference.

Provide the overlay source

Indicate the source of the overlay asset in the overlay object:

Example:

"source": {
  "url": "<pre_signed_overlay_URL>"
}

Adjust overlay timing

Specify the timing of overlays with:

Use timecode format HH:mm:SS:Frames, where:

Example:

"startTime": "00:00:05:10",
"duration": "00:00:10:00"

Adjust overlay size and position

Adjust the size and position of the overlay with:

Example:

"scale": {
  "width": 300,
  "height": 300
}

Adjust overlay position

Specify the overlay's anchor point on the video and the offsets for precise placement with:

Example:

"position": {
  "anchorPoint": "top_right",
  "offsetX": 50,
  "offsetY": 50
}

Adjust overlay behavior

Determine how the overlay should behave when the source media runs longer with:

Example:

"repeat": "loop"

The job response

If successful, you'll see a response like:

{
  "jobId": "<job_ID>",
  "statusUrl": "https://<base URL>/v2/status/<job_ID>"
}

If there's an error, you'll see something like:

{
  "error_code": <error_code>,
  "message": <message>
}

For a full list of error codes, check the API Reference.

Check the job status

To check the status of a reframe job, use the cURL command below.

curl -X 'GET'
'https://audio-video-api.adobe.io/v2/status/{jobId}' \
-H 'Authorization:{ACCESS_TOKEN}' \
-H 'x-api-key:{CLIENT_ID}' \
-H 'Content-Type: application/json'

A successful response when the processing job is complete contains a secure link in url to download the reframed video output. Go to the URL in your browser to see your new processed video.

Successful response for a running job:

{
    "jobId": "<job_ID>",
    "status": "running",
    "percentCompleted": "23.0"
}

Successful response when the processing job is complete:

{
    "jobId": "<job_ID>",
    "status": "succeeded",
    "outputs": [
      {
        "mediaDestination": {
          "url": "<pre-signed_PUT_URL_to_upload_the_output_video_to_user_bucket>"
        },
        "sidecarDestination": {
          "url": "<pre-signed_PUT_URL_to_upload_the_sidecar_file_to_user_bucket>"
        }
      }
    ]
}