Image Processing API

The Image Processing API extension (image-processing-api) lets you optimize and transform images in the Cloud Storage bucket via a powerful HTTP API. The API provides more than 30 different operations to enhance and manipulate your images, including image composition, cropping, flipping, color reduction, sharpening, filtering, and much more. See the full list of available operations in the Operations documentation.

Install the extension#

To install the extension, follow the steps on the Install Firebase Extension page. In summary, do one of the following:

• Firebase console: Click the following link:

  

• CLI: Run the following command:

  Copy

  firebase ext:install invertase/image-processing-api --project=projectId-or-alias
  

During the installation of the extension, you will be prompted to specify a number of configuration parameters:

• Cloud Functions location:

  Select the location of where you want to deploy the functions created for this extension. You usually want a location close to your database. For help selecting a location, refer to the location selection guide.

• Cloud Storage bucket:

  Cloud storage bucket, where the images to be processed are located.

• Allowed CORS origins:

  A comma-delimited value of allowed CORS origins. Use the default of * to allow all origins. This is useful to lock down your API and only allow your own website to embed the images directly. Note this will not prevent non-browser requests from accessing your API.

Use the extension#

After installation, a new Cloud Function called process will be added to your project. You can make HTTP requests to this function specifying a method of GET and a single query parameter operations with a JSON array of operations you'd like to perform. For example:

curl -X GET \
  https://{LOCATION}-{PROJECT_ID}.cloudfunctions.net/ext-image-processing-api-handler/process?operations=...

• {LOCATION}: The Cloud Functions location that was specified during the installation of the extension.
• {PROJECT_ID}: The Firebase project ID.

Operation usage#

The operations query parameter is a JSON array of operations to perform. Each operation is a JSON object with an operation property specifying the operation to perform and other properties depending on the operation. The parameter follows a couple of rules:

1. The first operation in the array must be an input operation. This operation specifies the image to be processed. Read the input operation documentation for more information.
2. The last operation in the array must be an output operation. This operation specifies the format of the image to be created. Read the output operation documentation for more information.

The following example details a remote input operation and the output type:

[
  {
    operation: 'input',
    type: 'url',
    url: 'https://example.com/image.jpg',
  },
  // Other operations...
  {
    operation: 'output',
    format: 'webp',
  },
];

Additional operations can be placed between to process the image operation types outline in the documentation, for example to flip then rotate the image 90 degrees:

[
  {
    operation: 'input',
    type: 'url',
    url: 'https://example.com/image.jpg',
  },
  {
    operation: 'flip',
  },
  {
    operation: 'rotate',
    angle: 90,
  },
  {
    operation: 'output',
    format: 'webp',
  },
];

Providing the operations#

The operations query parameter accepts a stringified JSON object as a value. This should be encoded as a URI component, for example:

const operations = [
  {
    operation: 'input',
    type: 'url',
    url: 'https://example.com/image.jpg',
  },
  {
    operation: 'flip',
  },
  {
    operation: 'output',
    format: 'webp',
  },
];

const encodedOperations = encodeURIComponent(JSON.stringify(operations));
const url = `https://{LOCATION}-{PROJECT_ID}.cloudfunctions.net/ext-image-processing-api-handler/process?operations=${encodedOperations}`;

JavaScript utility library#

Additionally, a utility library exists to provide a fully typed interface for constructing options:

import { builder } from '@invertase/image-processing-api';

const output = builder()
  .input({
    source: 'https://example.com/image.jpg',
  })
  .rotate({ angle: 90 })
  .output({
    format: 'png',
  });

console.log(output.toJSON());

For more details, view the documentation.