Edit in GitHubLog an issue

Quickstart Guide

Create your first Mask with Photoshop APIs

a picture of a person golfing with a green scenic background

Image

a mask of a person golfing with a black background

Image Mask

Prerequisites

Credentials

If you don't already have a Photoshop or Firefly Services Client ID and Client Secret, retrieve them from your Adobe Developer Console project before reading further. Securely store these credentials and never expose them in client-side or public code.

Set Up Your Environment

Before we begin this tutorial, run the following in a secure terminal:

Copied to your clipboard
mkdir photoshop-api-create-mask-tutorial
cd photoshop-api-create-mask-tutorial
npm init --y
npm install axios qs
touch index.js

Pre-signed URLs

To interact with Adobe's Photoshop APIs, you'll need to generate pre-signed URLs. These URLs grant temporary access to your storage resources without exposing your credentials. For more details about pre-signed URLs, see AWS Sharing objects with presigned URLs, or Azure Storage resources using shared access signatures.

In this tutorial, you will need:

  • A pre-signed URL with a read token for the input image. Save this sample image to your cloud storage and generate a pre-signed URL: a picture of a person golfing with a green scenic background
  • A pre-signed URL with a read/write token for the output mask.

Depending on your learning style, you may prefer to walk through this tutorial step-by-step or jump immediately to the full source code.

Retrieve an Access Token

Open a secure terminal and export your Client ID and Client Secret as environment variables so that your later commands can access them:

Copied to your clipboard
export CLIENT_ID=yourClientIdAsdf123
export CLIENT_SECRET=yourClientSecretAsdf123

Generate an access token:

Copied to your clipboard
curl --location 'https://ims-na1.adobelogin.com/ims/token/v3' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode "client_id=$CLIENT_ID" \
--data-urlencode "client_secret=$CLIENT_SECRET" \
--data-urlencode 'scope=openid,AdobeID,read_organizations'

The response will look like this:

Copied to your clipboard
{"access_token":"yourAccessTokenAsdf123","token_type":"bearer","expires_in":86399}

Export this access token in your secure terminal so that the next script can conveniently access it:

Copied to your clipboard
export ACCESS_TOKEN=yourAccessTokenAsdf123

Create Mask

Next, call the Photoshop Create Mask API:

Copied to your clipboard
curl --location 'https://image.adobe.io/sensei/mask' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "x-api-key: $CLIENT_ID" \
--header "Authorization: Bearer $ACCESS_TOKEN" \
--data '{
"input":{
"href":"https://your-storage-bucket-name.blob.core.windows.net:443/images/asdf-12345?lots=of&query=params...",
"storage":"azure"
},
"output":{
"href":"https://your-storage-bucket-name.blob.core.windows.net:443/images/asdf-12345?lots=of&query=params...",
"storage":"azure"
}
}'

The response will look like this:

Copied to your clipboard
{
"_links": {
"self": {
"href": "https://image.adobe.io/sensei/status/<:jobId>"
}
}
}

Get Status - Mask

Next up, we will use the Get Status - Mask endpoint to monitor the job status until it completes.

Copied to your clipboard
curl --location 'https://image.adobe.io/sensei/status/<:jobId>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "x-api-key: $CLIENT_ID" \
--header "Authorization: Bearer $ACCESS_TOKEN"

A successful response looks like:

Copied to your clipboard
{
"jobId": "f54e0fcb-260b-47c3-b520-111111",
"created": "2024-11-28T23:07:01.264Z",
"modified": "2024-11-28T23:07:03.036Z",
"status": "succeeded",
"metadata": {
"service": {}
},
"output": {
"href": "https://your-storage-bucket-name.blob.core.windows.net:443/images/asdf-12345?lots=of&query=params...",
"storage": "azure",
"mask": {
"format": "soft"
},
"color": {
"space": "rgb"
}
},
"options": {
"optimize": "performance"
},
"errors": [
{}
],
"_links": {
"self": {}
}
}

View Created Mask

Access the mask at the output.href URL (the SIGNED_POST_URL provided earlier). 🎉

Full Example

You can review the prerequisites section to understand how to set up your environment prior to running this code. Note that this is an example only and is not production-ready and requires additional error handling, logging, security measures, and more before you can run it at scale in a live application.

Copied to your clipboard
import os
import time
import requests
# Replace with your actual pre-signed URLs and storage option
SIGNED_GET_URL = 'https://your-storage-bucket-name.blob.core.windows.net:443/images/asdf-12345?lots=of&query=params...' # Input image URL
SIGNED_POST_URL = 'https://your-storage-bucket-name.blob.core.windows.net:443/images/asdf-12345?lots=of&query=params...' # Output mask URL
STORAGE = 'azure' # e.g., 'external', 'azure'
def main():
access_token = retrieve_access_token()
job_response = create_mask(access_token)
job_id = job_response['_links']['self']['href'].split('/')[-1]
check_job_status(job_id, access_token)
def retrieve_access_token():
client_id = os.environ['CLIENT_ID']
client_secret = os.environ['CLIENT_SECRET']
token_url = 'https://ims-na1.adobelogin.com/ims/token/v3'
payload = {
'grant_type': 'client_credentials',
'client_id': client_id,
'client_secret': client_secret,
'scope': 'openid,AdobeID,read_organizations',
}
try:
response = requests.post(token_url, data=payload)
response.raise_for_status()
access_token = response.json()['access_token']
print('Access Token Retrieved')
return access_token
except requests.exceptions.RequestException as error:
print('Error retrieving access token:', error.response.text)
exit(1)
def create_mask(access_token):
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'x-api-key': os.environ['CLIENT_ID'],
'Authorization': f'Bearer {access_token}',
}
data = {
'input': {'href': SIGNED_GET_URL, 'storage': STORAGE},
'output': {'href': SIGNED_POST_URL, 'storage': STORAGE},
}
try:
response = requests.post(
'https://image.adobe.io/sensei/mask', headers=headers, json=data
)
response.raise_for_status()
print('Mask Creation Job Submitted:', response.json())
return response.json()
except requests.exceptions.RequestException as error:
print('Error during create_mask:', error.response.text)
exit(1)
def check_job_status(job_id, access_token):
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'x-api-key': os.environ['CLIENT_ID'],
'Authorization': f'Bearer {access_token}',
}
url = f'https://image.adobe.io/sensei/status/{job_id}'
try:
status = 'submitted'
while status not in ['succeeded', 'failed']:
time.sleep(5) # Wait for 5 seconds
response = requests.get(url, headers=headers)
response.raise_for_status()
status_response = response.json()
status = status_response.get('status')
print(f'Job Status: {status}')
if status == 'succeeded':
print('Mask creation completed successfully!')
print('You can access the mask at your SIGNED_POST_URL.')
else:
print('Mask creation failed.')
except requests.exceptions.RequestException as error:
print('Error checking job status:', error.response.text)
exit(1)
if __name__ == '__main__':
main()

Deepen Your Understanding

Explore more Photoshop API options in our Photoshop Tutorials 🚀

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