Edit in GitHubLog an issue

Create your first Firefly API implementation

A step-by-step guide for creating your first implementation with the Firefly APIs.

Adobe Firefly APIs offer a seamless way to integrate powerful creative workflows into your applications using a simple REST-based API. In this tutorial, you'll be guided through creating your first implementation using the Firefly Generate Images API.

Prerequisites

Before beginning, 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. This will be the script used for testing your integration with the 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

Step 2: Authentication

Next, you will initialize a few variables. Note: It's crucial to have your environment variables set up from above prior to this step, 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;

Now, these two variables will be used to make a POST request to the 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. All of this can be done in this 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 the demo, you will use Firefly to generate four images from a single prompt using the Firefly Generate Images API, which includes optional generative matching.

Based on the docs, we can see that the only required parameter is prompt. Also, the numVariations 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",
    "numVariations":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 generateImage(prompt, id, token) {


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


    let req = await fetch('https://firefly-api.adobe.io/v3/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

Next, 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 generateImage(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 url values from the result to view the images.

Step 4: Downloading Images from Firefly API

Next, you will learn how to write a quick utility to download the resulting images.

Import the Required Modules

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

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

Define the downloadFile function

Next, create a function that takes a URL and a file path as arguments, and downloads the file from the URL to the specified path.

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 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.url, fileName);
}

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

Sample output

A result of an image generated with the prompt specified above is shown here for reference.

a cat dancing on a rainbow

Complete Source 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 the 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,firefly_enterprise,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 generateImage(prompt, id, token) {


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


    let req = await fetch('https://firefly-api.adobe.io/v3/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 generateImage(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.url, fileName);
}

Next steps

Tim KimArchy PosadaHolly SchinskyNimitha Jalalcfjedimaster
Last updated 7/22/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.