Edit in GitHubLog an issue

Create your first Firefly API implementation

A step-by-step guide to creating your first implementation of the Firefly API.

The Adobe Firefly API offers a seamless way to integrate powerful creative workflows into your applications using a simple REST-based API. In this tutorial, we'll guide you through creating your first implementation of the Firefly API.

Let's get started!

Prerequisites

Before we begin, make sure you have the following:

  • Firefly API credentials. If you don't have them yet, first visit the Firefly Services Getting Started guide to obtain a client_id and client_secret.
  • Node.js or Python installed on your machine and basic familiarity with JavaScript or Python.

Step 1: Set Up Your Environment

Begin by creating a new script, named firefly.js (or firefly.py), and save it anywhere on your computer., and save it anywhere on your computer. This will be the script we use to test our integration with Firefly API endpoints.

Next, set your client_id and client_secret as environment variables. For example, on a Mac or in Windows Subsystem for Linux (WSL), you can do the following:

Copied to your clipboard
export CLIENT_ID=YOURIDHERE
export CLIENT_SECRET=YOURSECRETHERE

Note that our code is going to assume CLIENT_ID and CLIENT_SECRET - case matters!

Step 2: Authentication

Let's begin by initializing a few variables. As previously mentioned, it is crucial to set up two environment variables, as the following code relies on them:

Copied to your clipboard
/* Set our creds based on environment variables.
*/
const CLIENT_ID = process.env.CLIENT_ID;
const CLIENT_SECRET = process.env.CLIENT_SECRET;

To authenticate, we take these two variables and make a POST request to our authentication endpoint: https://ims-na1.adobelogin.com/ims/token/v3. You need to pass your credentials along with the requested scopes that allow for access to Firefly. We can wrap up the entire thing in one simple function:

Copied to your clipboard
async function getAccessToken(id, secret) {


    const params = new URLSearchParams();


    params.append('grant_type', 'client_credentials');
    params.append('client_id', id);
    params.append('client_secret', secret);
    params.append('scope', 'openid,AdobeID,session,additional_info,read_organizations,firefly_api,ff_apis');
    
    let resp = await fetch('https://ims-na1.adobelogin.com/ims/token/v3', 
        { 
            method: 'POST', 
            body: params
        }
    );


    let data = await resp.json();
    return data.access_token;
}


let token = await getAccessToken(CLIENT_ID, CLIENT_SECRET);

Step 3: Generate an Image with a Prompt

For our demo, we will use Firefly to generate four images from a single prompt.

In this case, we will focus on the generateImages functionality, which includes optional generative matching.

Based on the docs, we can see that the only required parameter is prompt. Also, the n prompt specifies how many images we want. So the simplest request body we could build would look like so:

Copied to your clipboard
{
    "prompt":"a cat dancing on a rainbow",
    "n":4
}

Now, let's create a function to generate an image using a prompt.

First, we'll build a simple function to call the REST endpoint. It requires our previous client_id value and the access_token, and our prompt:

Copied to your clipboard
async function textToImage(prompt, id, token) {


    let body = {
        "n":4,
        prompt
    }




    let req = await fetch('https://firefly-api.adobe.io/v2/images/generate', {
        method:'POST',
        headers: {
            'X-Api-Key':id, 
            'Authorization':`Bearer ${token}`,
            'Content-Type':'application/json'
        }, 
        body: JSON.stringify(body)
    });


    return await req.json();
}

Please ensure you include the authentication headers correctly. Pass the token in the Authorization header and the client ID in the X-Api-Key header. The API will return a JSON string for you to process and return to the caller.

Executing the Firefly API Call

We define a simple prompt and call the function to interact with the Firefly API, displaying the result on the screen.

Copied to your clipboard
let prompt = 'a cat dancing on a rainbow';
let result = await textToImage(prompt, CLIENT_ID, token);
console.log(JSON.stringify(result, null, '\t'));

This function sends a POST request to the Firefly API with the prompt and retrieves the generated images. Replace a cat dancing on a rainbow with your desired prompt.

You can copy and paste any of the presignedUrl values from the result to view the images.

Step 4: Downloading Images from Firefly API

Let's see how you can write a quick utility to download these images.

Import the Required Modules

First, import the necessary file-related modules and the requests module for Python:

Copied to your clipboard
import fs from 'fs';
import { Readable } from 'stream';
import { finished } from 'stream/promises';

Define the downloadFile function

Create a function that takes a URL and a file path as arguments, and downloads the file from the URL to the specified path (This step is only required for Node.js).

Copied to your clipboard
async function downloadFile(url, filePath) {
    let res = await fetch(url);
    const body = Readable.fromWeb(res.body);
    const download_write_stream = fs.createWriteStream(filePath);
    return await finished(body.pipe(download_write_stream));
}

Iterate over the results and save each image

Finally, iterate over the results (assuming result contains the response from the API call) and save each image with a unique file name using the seed value from the result:

Copied to your clipboard
for(let output of result.outputs) {
    let fileName = `./${output.seed}.jpg`;
    await downloadFile(output.image.presignedUrl, fileName);
}

After running these steps, you'll see four images output in the same directory.

Sample output

a cat dancing on a rainbow

Complete Code

Here's the entire code sample. As a reminder, feel free to modify and change the prompt.

Copied to your clipboard
import fs from 'fs';
import { Readable } from 'stream';
import { finished } from 'stream/promises';


/*
Set our creds based on environment variables.
*/
const CLIENT_ID = process.env.CLIENT_ID;
const CLIENT_SECRET = process.env.CLIENT_SECRET;




async function getAccessToken(id, secret) {


    const params = new URLSearchParams();


    params.append('grant_type', 'client_credentials');
    params.append('client_id', id);
    params.append('client_secret', secret);
    params.append('scope', 'openid,AdobeID,session,additional_info,read_organizations,firefly_api,ff_apis');
    
    let resp = await fetch('https://ims-na1.adobelogin.com/ims/token/v3', 
        { 
            method: 'POST', 
            body: params
        }
    );


    let data = await resp.json();
    return data.access_token;
}


let token = await getAccessToken(CLIENT_ID, CLIENT_SECRET);


async function textToImage(prompt, id, token) {


    let body = {
        "n":4,
        prompt
    }




    let req = await fetch('https://firefly-api.adobe.io/v2/images/generate', {
        method:'POST',
        headers: {
            'X-Api-Key':id, 
            'Authorization':`Bearer ${token}`,
            'Content-Type':'application/json'
        }, 
        body: JSON.stringify(body)
    });


    return await req.json();
}


let prompt = 'a cat dancing on a rainbow';
let result = await textToImage(prompt, CLIENT_ID, token);
console.log(JSON.stringify(result,null,'\t'));


async function downloadFile(url, filePath) {
    let res = await fetch(url);
    const body = Readable.fromWeb(res.body);
    const download_write_stream = fs.createWriteStream(filePath);
    return await finished(body.pipe(download_write_stream));
}


for(let output of result.outputs) {
    let fileName = `./${output.seed}.jpg`;
    await downloadFile(output.image.presignedUrl, fileName);
}

Next steps

Tim KimArchy PosadaHolly SchinskyNimitha Jalalcfjedimaster
Last updated 4/3/2024
Was this helpful?

Community

Support

Adobe Developer

  • Privacy
  • Terms of Use
  • Do not sell or share my personal information
  • AdChoices
Copyright © 2024 Adobe. All rights reserved.