Product Updates | Contact Support | System Status
Page Contents

    Overview: Image API

    The Image API allows you to retrieve a resized, cropped, or rotated version of an image.

    Introduction

    The Brightcove Image API provides a quick and easy way to resize, crop, and/or rotate an image using a simple GET request.

    Request URL

    The request URL for the Image API is:

    https://images.brightcovecdn.com/image/v1/{account_id}/{image-token}/url/{image_url}

    The required path parameters are:

    • account_id: your Video Cloud account id
    • image-token: authentication token for your account (must be generated by Brightcove Support)
    • image_url: a public URL where the image can be found

    URL parameters

    To get a transformed version of your image, use one or more of the URL parameters described below in your request. Note that you can use any combination of the 3 parameters.

    URL Params for Image API
    Parameter Description
    resize Resize the image by setting this equal to "widthxheight" - example: resize=160x90)
    fallback If true, the API will return a black image if it is unable to return the requested image.
    fillArea Keep the aspect ratio of the image filling entirely the area given by the resize parameter. Default behavior fills only one side of the same area.
    crop Crop the width and height by setting this equal to "widthxheight" - example: crop=160x90 - the origin point is the center of the image.
    rotate rotate the image clockwise by the specified number of degrees - example: rotate=90
    nocache Iftrue the API response will include a Cache-Control header with the value public, max-age=0.
    watermark If true a play button icon will be added to the image

    Best Practices

    If your transformed images will be displayed on web pages or in online apps, use the API to retrieve the images and store them on your server. Do not retrieve them at runtime, as rate-limiting on the API would cause some requests to fail on high-traffic pages or apps, and it also degrades the performance of your page/app by forcing the API requests to be made every it is loaded by a user.

    Examples

    Here is the original image for examples below:

    Original Image
    Original Image (726x985)

    Resized (using the resize parameter)

    Request

    https://images.brightcovecdn.com/image/v1/1752604059001/XXXXXXXXXX/url/https%3A%2F%2Fapis.support.brightcove.com%2Fassets%2Fimages%2Fimage-api%2Fleaf.jpg?resize=221x300
    Resized Image
    Resized Image

    Cropped

    Request

    https://images.brightcovecdn.com/image/v1/1752604059001/XXXXXXXXXX/url/https%3A%2F%2Fapis.support.brightcove.com%2Fassets%2Fimages%2Fimage-api%2Fleaf.jpg?crop=580x670
    Cropped Image
    Cropped Image

    Rotated

    Request

    https://images.brightcovecdn.com/image/v1/1752604059001/XXXXXXXXXX/url/https%3A%2F%2Fapis.support.brightcove.com%2Fassets%2Fimages%2Fimage-api%2Fleaf.jpg?rotate=-90
    Rotated Image
    Rotated Image

    Resized and Fill Area

    Request

    https://images.brightcovecdn.com/image/v1/1752604059001/XXXXXXXXXX/url/https%3A%2F%2Fapis.support.brightcove.com%2Fassets%2Fimages%2Fimage-api%2Fleaf.jpg?resize=200x300&fillArea=true
    Resized and Fill Area
    Resized and Fill Area

    Resized and Rotated

    Request

    https://images.brightcovecdn.com/image/v1/1752604059001/XXXXXXXXXX/url/https%3A%2F%2Fapis.support.brightcove.com%2Fassets%2Fimages%2Fimage-api%2Fleaf.jpg?resize=221x300&rotate=-90
    Resized and Rotated Image
    Resized and Rotated Image

    Cropped and Rotated

    Request

    https://images.brightcovecdn.com/image/v1/1752604059001/XXXXXXXXXX/url/https%3A%2F%2Fapis.support.brightcove.com%2Fassets%2Fimages%2Fimage-api%2Fleaf.jpg?crop=570x660&rotate=-90
    Cropped and Rotated Image
    Cropped and Rotated Image

    Resized, Cropped, and Rotated

    Request

    https://images.brightcovecdn.com/image/v1/1752604059001/XXXXXXXXXX/url/https%3A%2F%2Fapis.support.brightcove.com%2Fassets%2Fimages%2Fimage-api%2Fleaf.jpg?resize=221x300&crop=570x660&rotate=-90
    Resized, Cropped, Rotated Image
    Resized, Cropped, Rotated Image

    Watermarked

    Request

    https://images.brightcovecdn.com/image/v1/1752604059001/XXXXXXXXXX/url/https%3A%2F%2Fapis.support.brightcove.com%2Fassets%2Fimages%2Fimage-api%2Fleaf.jpg?watermark=true
    Watermarked
    Watermarked

    No cache

    Request

    https://images.brightcovecdn.com/image/v1/1752604059001/XXXXXXXXXX/url/https%3A%2F%2Fapis.support.brightcove.com%2Fassets%2Fimages%2Fimage-api%2Fleaf.jpg?resize=221x300&nocache=true

    Below are the response headers (returned by Insomnia).

    Response Headers
    Response Headers

    Page last updated on 25 Jul 2022