@adobe/firefly-apis

Adobe Firefly Services library for consuming Firefly Service APIs.


Keywords
adobe, firefly services, services, firefly, apis, sdk
License
Adobe-Glyph
Install
npm install @adobe/firefly-apis@0.2.0

Documentation

Firefly Services SDK for Javascript

This repository hosts the Firefly Services SDK, offering developers a unified framework for accessing Firefly service APIs. The Firefly Services SDK for JavaScript is designed for Node.js and web environments. It features libraries for various Firefly services, including services like Firefly, Photoshop, and Lightroom, and a common library for tasks like authentication. The SDK enhances developer productivity by facilitating seamless interaction with the product API services.

Key features

  1. Unified API Access: The SDK follow consistent design pattern across all Product APIs, making it easier for developers to understand and use them without having to learn the nuances of each API service.

  2. TypeScript Support: Developed in TypeScript, the JavaScript SDK enables you to harness TypeScript's capabilities, including static type-checking and code autocomplete, for a more robust development experience.

  3. Common Utility Package: This API package offers a range of utility APIs, including authentication APIs, to facilitate interaction with various product services.

  4. Comprehensive Documentation: SDK is accompanied by guides, API references documentation and code examples to help you get started quickly.

Getting Started

Be sure to check out the documentation for Firefly Services and watch this video.

Prerequisites

You'll need:

  • Node v18.0 or better
  • NPM v9.0 or better
  • Any Text Editor (example, VSCode, SublimeText)
  • To get started, you'll need your credentials, such as Client ID, Client Secret, and the scopes to access to Firefly Services. Follow the guide to access Developer Console.

Adding Firefly Services SDK packages into the project

You can include SDK in your existing NodeJS project or a new project. Once you have a NodeJS project, use the commands below to add the required packages to your project.

  1. Authentication is a mandatory step for using any of the Firefly Service APIs. The common package provides utility APIs, such as server-to-server authentication, to help retrieve the access token for interacting with Firefly Service APIs. To add this package, use the command below.
npm install @adobe/firefly-services-common-apis
  1. For Firefly APIs, add the Firefly package.
npm install @adobe/firefly-apis
  1. For Lightroom APIs, add the Lightroom package.
npm install @adobe/lightroom-apis
  1. For Photoshop APIs, add the Photoshop package.
npm install @adobe/photoshop-apis

Alternatively, you can install all the packages with a single command like the one below.

npm install @adobe/firefly-apis @adobe/photoshop-apis @adobe/lightroom-apis @adobe/firefly-services-common-apis

Authentication

Firefly Services SDK provides authentication via token provider. With v2, authentication is simplified with a ClientCredentials on each of the client classes. This can be directly passed at the time of Client Initialization.

Authentication example

  1. Authentication via TokenProvider
const serverToServerAuthDetails = {
    clientId: "<clientId>",
    clientSecret: "<clientSecret>",
    scopes: "<scopes>",
};

// create auth provider
// ServerToServerTokenProvider implements the TokenProvider interface that returns the access token.
const authProvider = new ServerToServerTokenProvider(serverToServerAuthDetails);
const config = {
    tokenProvider: authProvider,
    clientId: "<clientId>",
};

// create the product client
const firefly = new FireflyClient(config);
  1. v2 Authentication via Credentials
// Create client Credentials 
const clientCredentials = {
    clientId: "<clientId>",
    clientSecret: "<clientSecret>"
}

const firefly = await FireflyClient(clientCredentials);

Making your first API call

Each package, installed in the previous step, has a main client class: FireflyClient, PhotoshopClient, LightroomClient. Use these classes to invoke the corresponding service APIs.

The example below demonstrates two use cases:

  1. Generating images from Firefly APIs and removing the backgrounds using Photoshop APIs.
  2. Generating images from Firefly APIs and applying auto-tone using Lightroom APIs.

Note: Photoshop and Lightroom services in the sample below require Pre-Signed URLs. Guide to generate Pre-Signed URL.

Create a new file named index.js in your project with the below content.

const { PhotoshopClient } = require("@adobe/photoshop-apis");
const { FireflyClient } = require("@adobe/firefly-apis");
const { LightroomClient, StorageType } = require("@adobe/lightroom-apis");
const { ServerToServerTokenProvider } = require("@adobe/firefly-services-common-apis");

/**
 * Helper function that performs server-to-server authentication to fetch the access token.
 * @param {string} clientId
 * @param {string} clientSecret
 * @param {string} scopes
 * @returns {ServerToServerTokenProvider}
 */
function getAuthProvider(clientId, clientSecret, scopes) {
    const serverToServerAuthDetails = {
        clientId,
        clientSecret,
        scopes, // example: "openid,AdobeID,read_organizations,firefly_api,ff_apis"
    };
    const serverToServerAuthOptions = {
        autoRefresh: true,
    };
    return new ServerToServerTokenProvider(serverToServerAuthDetails, serverToServerAuthOptions);
}

// create auth config
const authProvider = getAuthProvider("<clientId>", "<clientSecret>", "<scopes>"); // Update the "<clientId>", "<clientSecret>", "<scopes>"
const config = {
    tokenProvider: authProvider,
    clientId: "<clientId>" // Update the "<clientId>"
};

// create the product clients
const firefly = new FireflyClient(config);
const photoshop = new PhotoshopClient(config);
const lightroom = new LightroomClient(config);

/**
 * Generate an image and remove background
 */
async function generateImageAndRemoveBackground() {
    const fireflyResponse = await firefly.generateImages({ prompt: "<Prompt>" }); // provide a `prompt` value
    const firstImageUrl = fireflyResponse.result.outputs[0].image.url;

    console.log("Successfully generated a Firefly Image");

    // Prepare for Photoshop operation
    const psInput = {
        href: firstImageUrl,
        storage: StorageType.EXTERNAL,
    };

    const psOutput = {
        href: "<psOutputHref>", // Update with generated Pre-signed PUT URL for output file. 
        storage: "<psOutputStorage>", // example: StorageType.DROPBOX or StorageType.EXTERNAL or StorageType.AZURE
    };

    const psRequestBody = {
        input: psInput,
        output: psOutput
    };

    const removeBg = await photoshop.removeBackground(psRequestBody); // Remove Background
    console.log("Successfully removed background");
}

/**
 * Generate an image and apply auto-tone
 */
async function generateAndAutoToneImage() {

    const fireflyResponse = await firefly.generateImages({ prompt: "<prompt>" }); // Update the "<prompt>"
    const firstImageUrl = fireflyResponse.result.outputs[0].image.url;

    console.log("Successfully generated the Firefly Image");

    // Prepare for Lightroom operation
    const lrInput = {
        href: firstImageUrl,
        storage: StorageType.EXTERNAL,
    };

    const lrOutput = {
        href: "<lrOutputHref>", // Update with generated pre-signed PUT URL for output file. 
        storage: "<lrOutputStorage>", // example -> "dropbox" or "external" or "azure"
        type: "<imageType>" // example -> "image/jpeg" or "image/png"
    };

    const lrRequestBody = {
        inputs: lrInput,
        outputs: [lrOutput]
    };

    const applyAutoTone = await lightroom.applyAutoTone(lrRequestBody); // Apply Auto Tone
    console.log("Successfully applied auto tone to the Image");
}

generateImageAndRemoveBackground();
generateAndAutoToneImage();

Build & Run

  • Update the file with necessary information, such as client id, prompt, pre-signed URL for output file and more
  • Run the command node index.js.
  • Go to your respective output storage location to find the final image.

Samples

Sample Projects for reference.

Firefly Services SDK Packages

SDK Package Name Product API Guides SDK API reference SDK Package Change Log
@adobe/firefly-apis Firefly API API Reference Firefly Change Log
@adobe/photoshop-apis Photoshop API API Reference Photoshop Change Log
@adobe/lightroom-apis Lightroom API API Reference Lightroom Change Log
@adobe/firefly-services-common-apis Authorization API Reference Common Package Change Log

For more details on the packages in the SDK refer to