# Image Processing API

The Image Processing API extension (`image-processing-api`) lets you optimize and transform images in the [Cloud Storage](https://firebase.google.com/docs/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](/image-processing-api/operations) documentation.

<video width="100%" controls muted autoPlay loop>
  <source
    src="https://user-images.githubusercontent.com/35961879/175304684-9bb464b6-996e-4923-b65b-cb1afd9519b4.mp4"
    type="video/mp4"
  />
  Your browser does not support the video tag.
</video>

## Install the extension

To install the extension, follow the steps on the [Install Firebase Extension](https://firebase.google.com/docs/extensions/install-extensions) page. In summary, do one of the following:

- **Firebase console:** Click the following link:

  <a
    href="https://console.firebase.google.com/project/_/extensions/install?ref=invertase/image-processing-api"
    target="_blank"
  >
    <img
      src="https://github.com/FirebaseExtended/experimental-extensions/raw/next/install-extension.png?raw=true"
      alt="Install the Image Processing API extension"
    />
  </a>

- **CLI:** Run the following command:

  ```bash
  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](https://firebase.google.com/docs/functions/locations).

- **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:

```bash
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](/image-processing-api/input) operation documentation for more information.
1. 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](/image-processing-api/output) operation documentation for more information.

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

```js
[
  {
    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](/operations), for example to flip then rotate the image 90 degrees:

```js
[
  {
    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:

```js
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:

```ts
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](https://www.npmjs.com/package/@invertase/image-processing-api).