@adobe/aio-lib-photoshop-api

v1.1.0

Published

20 days ago

Adobe Photoshop API Library

Downloads

326

Adobe Photoshop API Library

Rest API

The Rest API is documented at:

Public Documentation

Installing

$ npm install @adobe/aio-lib-photoshop-api

Usage

Initialize the SDK

const sdk = require('@adobe/aio-lib-photoshop-api')

async function sdkTest() {
  try {
    //initialize sdk
    const client = await sdk.init('<ims org id>', '<api key>', '<valid auth token>')
  } catch (e) {
    console.error(e)
  }
}

Remove the background of a photo

This is the example of using the storage type of http://host/input.jpg (External) and call the service to cutout the background, ask for JPEG output, and store the result in Adobe Creative Cloud file storage path/output.jpg.

const sdk = require('@adobe/aio-lib-photoshop-api')

async function sdkTest() {
  try {
    // initialize sdk
    const client = await sdk.init('<ims org id>', '<api key>', '<valid auth token>')

    // call methods
    const result = await client.createCutout({
      href: 'http://host/input.jpg',
      storage: sdk.Storage.EXTERNAL
    }, {
      href: 'path/output.png',
      storage: sdk.Storage.ADOBE,
      type: sdk.MimeType.PNG
    })
  } catch (e) {
    console.error(e)
  }
}

Usage with Adobe I/O Files access

Initialize the SDK with Adobe I/O Files access

Configuring the SDK like this will make plain paths reference locations in Adobe I/O Files.

const libFiles = require('@adobe/aio-lib-files')
const sdk = require('@adobe/aio-lib-photoshop-api')

async function sdkTest() {
  try {
    // initialize sdk
    const files = await libFiles.init();
    const client = await sdk.init('<ims org id>', '<api key>', '<valid auth token>', files)
  } catch (e) {
    console.error(e)
  }
}

Remove the background of a photo

This will automatically detect the storage type of http://host/input.jpg (e.g. Azure, External) and call the service to cutout the background, ask for JPEG output, and store the result in Adobe I/O Files under path/output.jpg.

const libFiles = require('@adobe/aio-lib-files')
const sdk = require('@adobe/aio-lib-photoshop-api')

async function sdkTest() {
  try {
    // initialize sdk
    const files = await libFiles.init();
    const client = await sdk.init('<ims org id>', '<api key>', '<valid auth token>', files)

    // call methods
    // auto cutout...
    const result = await client.createCutout('http://host/input.jpg', 'path/output.jpg')
    console.log(result)

    // equivalent call without FileResolver...
    const result = await client.createCutout({
      href: 'http://host/input.jpg',
      storage: sdk.Storage.EXTERNAL
    }, {
      href: 'path/output.png',
      storage: sdk.Storage.AIO,
      type: sdk.MimeType.PNG
    })
  } catch (e) {
    console.error(e)
  }
}

Classes

Functions

Typedefs

FileResolver

Resolves the storage and mime type of files referenced in the API.

The storage type storage type is resolved for input and output files using the following heuristic:

If the storage type is provided, it is used as-is
If a URL is provided, the hostname is inspected to determine Azure, Dropbox, or External (default)
If a path is provided, the path resolved to Adobe I/O Files if an instance is provided to the constructor, otherwise it's Creative Cloud

Path resolution can be overridden by the defaultAdobeCloudPaths option.

The mime-type is resolved based on the extension of the pathname of the URL or the path. If no extension can be found or the extension is unknown, the default image/png is selected.

Kind: global class

FileResolver
- new FileResolver([files], [options])
- .presignExpiryInSeconds : number
- .defaultPathStorage : Storage
- .resolveInput(input) ⇒ Input
- .resolveInputs(inputs) ⇒ Array.<Input>
- .resolveInputsDocumentOptions(options) ⇒ CreateDocumentOptions | ModifyDocumentOptions | ReplaceSmartObjectOptions
- .resolveInputsPhotoshopActionsOptions(options) ⇒ ApplyPhotoshopActionsOptions
- .resolveOutput(output) ⇒ Output
- .resolveOutputs(outputs) ⇒ Array.<Output>

new FileResolver([files], [options])

Construct a file resolver

| Param | Type | Description | | --- | --- | --- | | [files] | * | Adobe I/O Files instance | | [options] | FileResolverOptions | Options |

fileResolver.presignExpiryInSeconds : number

Expiry time of presigned urls in seconds

Kind: instance property of FileResolver

fileResolver.defaultPathStorage : Storage

Plain paths can reference either Adobe Creative Cloud or Adobe I/O Files.

If an instance of files is provided, the default is considered to be Adobe I/O Files, otherwise it's Creative Cloud. The default can be overridden using the options

Kind: instance property of FileResolver

fileResolver.resolveInput(input) ⇒ Input

Resolve input file from href to an object with href and storage

Kind: instance method of FileResolver
Returns: Input - resolved input

| Param | Type | Description | | --- | --- | --- | | input | string | Input | Input or href to resolve |

fileResolver.resolveInputs(inputs) ⇒ Array.<Input>

Resolve input files from hrefs to an array of objects with href and storage

Kind: instance method of FileResolver
Returns: Array.<Input> - resolved files

| Param | Type | Description | | --- | --- | --- | | inputs | string | Array.<string> | Input | Array.<Input> | One or more files |

fileResolver.resolveInputsDocumentOptions(options) ⇒ CreateDocumentOptions | ModifyDocumentOptions | ReplaceSmartObjectOptions

Resolve the font and layer inputs in the document options

Kind: instance method of FileResolver
Returns: CreateDocumentOptions | ModifyDocumentOptions | ReplaceSmartObjectOptions - Document options

| Param | Type | Description | | --- | --- | --- | | options | CreateDocumentOptions | ModifyDocumentOptions | ReplaceSmartObjectOptions | Document options |

fileResolver.resolveInputsPhotoshopActionsOptions(options) ⇒ ApplyPhotoshopActionsOptions

Resolve the actions, fonts, and custom presets options

Kind: instance method of FileResolver
Returns: ApplyPhotoshopActionsOptions - Photoshop Actions options

| Param | Type | Description | | --- | --- | --- | | options | ApplyPhotoshopActionsOptions | Photoshop Actions options |

fileResolver.resolveOutput(output) ⇒ Output

Resolve output from href to an object with href, storage, and type

Kind: instance method of FileResolver
Returns: Output - resolved files

| Param | Type | Description | | --- | --- | --- | | output | string | File | Output | One or more output files |

fileResolver.resolveOutputs(outputs) ⇒ Array.<Output>

Resolve outputs from href to an object with href, storage, and type

Kind: instance method of FileResolver
Returns: Array.<Output> - resolved files

| Param | Type | Description | | --- | --- | --- | | outputs | string | Array.<string> | File | Array.<File> | Output | Array.<Output> | One or more output files |

PhotoshopAPI

This class provides methods to call your PhotoshopAPI APIs. Before calling any method initialize the instance by calling the init method on it with valid values for orgId, apiKey and accessToken

Kind: global class

PhotoshopAPI
- .orgId : string
- .apiKey : string
- .accessToken : string
- .init(orgId, apiKey, accessToken, [files], [options]) ⇒ Promise.<PhotoshopAPI>
- .createCutout(input, output) ⇒ Job
- .createMask(input, output) ⇒ Job
- .straighten(input, outputs) ⇒ Job
- .autoTone(input, output) ⇒ Job
- .editPhoto(input, output, options) ⇒ Job
- .applyPreset(input, preset, output) ⇒ Job
- .applyPresetXmp(input, output, xmp) ⇒ Job
- .createDocument(outputs, options) ⇒ Job
- .getDocumentManifest(input, [options]) ⇒ Job
- .modifyDocument(input, outputs, options) ⇒ Job
- .createRendition(input, outputs) ⇒ Job
- .replaceSmartObject(input, outputs, options) ⇒ Job
- .applyPhotoshopActions(input, outputs, options) ⇒ Job
- .applyPhotoshopActionsJson(input, outputs, options) ⇒ Job

photoshopAPI.orgId : string

The IMS organization id

Kind: instance property of PhotoshopAPI

photoshopAPI.apiKey : string

The api key from your integration

Kind: instance property of PhotoshopAPI

photoshopAPI.accessToken : string

The access token from your integration

Kind: instance property of PhotoshopAPI

photoshopAPI.init(orgId, apiKey, accessToken, [files], [options]) ⇒ Promise.<PhotoshopAPI>

Initializes the PhotoshopAPI object and returns it.

Kind: instance method of PhotoshopAPI
Returns: Promise.<PhotoshopAPI> - a PhotoshopAPI object

| Param | Type | Description | | --- | --- | --- | | orgId | string | the IMS organization id | | apiKey | string | the API key for your integration | | accessToken | string | the access token for your integration | | [files] | * | Adobe I/O Files instance | | [options] | PhotoshopAPIOptions | Options |

photoshopAPI.createCutout(input, output) ⇒ Job

Create a cutout mask, and apply it to the input

Kind: instance method of PhotoshopAPI
Returns: Job - Auto cutout job

| Param | Type | Description | | --- | --- | --- | | input | string | Input | Input file | | output | string | Output | Output file |

photoshopAPI.createMask(input, output) ⇒ Job

Create a cutout mask

Kind: instance method of PhotoshopAPI
Returns: Job - Auto masking job

| Param | Type | Description | | --- | --- | --- | | input | string | Input | Input file | | output | string | Output | Output file |

photoshopAPI.straighten(input, outputs) ⇒ Job

Straighten photo

Kind: instance method of PhotoshopAPI
Returns: Job - Auto straighten job

| Param | Type | Description | | --- | --- | --- | | input | string | Input | Input file | | outputs | string | Output | Array.<Output> | Output file |

photoshopAPI.autoTone(input, output) ⇒ Job

Automatically tone photo

Kind: instance method of PhotoshopAPI
Returns: Job - Auto tone job

| Param | Type | Description | | --- | --- | --- | | input | string | Input | Input file | | output | string | Output | Output file |

photoshopAPI.editPhoto(input, output, options) ⇒ Job

Apply a set of edit parameters on an image

Kind: instance method of PhotoshopAPI
Returns: Job - Edit photo job

| Param | Type | Description | | --- | --- | --- | | input | string | Input | Input file | | output | string | Output | Output file | | options | EditPhotoOptions | Edit options |

photoshopAPI.applyPreset(input, preset, output) ⇒ Job

Apply a preset on an image

Kind: instance method of PhotoshopAPI
Returns: Job - Apply preset job

| Param | Type | Description | | --- | --- | --- | | input | string | Input | Input file | | preset | string | Input | Lightroom preset XMP file | | output | string | Output | Output file |

photoshopAPI.applyPresetXmp(input, output, xmp) ⇒ Job

Apply a preset on an image

Kind: instance method of PhotoshopAPI
Returns: Job - Apply preset job

| Param | Type | Description | | --- | --- | --- | | input | string | Input | Input file | | output | string | Output | Output file | | xmp | string | Lightroom preset XMP file contents |

photoshopAPI.createDocument(outputs, options) ⇒ Job

Create a new psd, optionally with layers, and then generate renditions and/or save as a psd

Kind: instance method of PhotoshopAPI
Returns: Job - Create document job

| Param | Type | Description | | --- | --- | --- | | outputs | string | Array.<string> | Output | Array.<Output> | Desired output | | options | CreateDocumentOptions | Document create options |

photoshopAPI.getDocumentManifest(input, [options]) ⇒ Job

Extract and return a psd file's layer information

Kind: instance method of PhotoshopAPI
Returns: Job - Get document manifest job

| Param | Type | Description | | --- | --- | --- | | input | string | Input | An object describing an input PSD file.Current support is for files less than 1000MB. | | [options] | object | available options to apply to all input files | | [options.thumbnails] | object | Include presigned GET URLs to small preview thumbnails for any renderable layer. | | [options.thumbnails.type] | MimeType | desired image format. Allowed values: "image/jpeg", "image/png", "image/tiff" |

photoshopAPI.modifyDocument(input, outputs, options) ⇒ Job

Apply (optional) psd edits and then generate renditions and/or save a new psd

Kind: instance method of PhotoshopAPI
Returns: Job - Modify document job

| Param | Type | Description | | --- | --- | --- | | input | string | Input | An object describing an input PSD file. Current support is for files less than 1000MB. | | outputs | string | Array.<string> | Output | Array.<Output> | Desired output | | options | ModifyDocumentOptions | Modify document options |

photoshopAPI.createRendition(input, outputs) ⇒ Job

Create renditions

Kind: instance method of PhotoshopAPI
Returns: Job - Create rendition job

| Param | Type | Description | | --- | --- | --- | | input | string | Input | An object describing an input file. Currently supported filetypes include: jpeg, png, psd, tiff. Current support is for files less than 1000MB. | | outputs | string | Array.<string> | Output | Array.<Output> | Desired output |

photoshopAPI.replaceSmartObject(input, outputs, options) ⇒ Job

Apply psd edits for replacing embedded smart object and then generate renditions and/or save a new psd

Kind: instance method of PhotoshopAPI
Returns: Job - Replace smart object job

| Param | Type | Description | | --- | --- | --- | | input | Input | An object describing an input PSD file. Current support is for files less than 1000MB. | | outputs | string | Output | Array.<Output> | Desired output | | options | ReplaceSmartObjectOptions | Replace smart object options |

photoshopAPI.applyPhotoshopActions(input, outputs, options) ⇒ Job

Apply Photoshop Actions and then generate renditions and/or save a new image

Kind: instance method of PhotoshopAPI
Returns: Job - Photoshop Actions job

| Param | Type | Description | | --- | --- | --- | | input | Input | An object describing an input image file. Current support is for files less than 1000MB. | | outputs | string | Output | Array.<Output> | Desired output | | options | ApplyPhotoshopActionsOptions | Apply Photoshop Actions options |

photoshopAPI.applyPhotoshopActionsJson(input, outputs, options) ⇒ Job

Apply JSON-formatted Photoshop Actions and then generate renditions and/or save a new image

Kind: instance method of PhotoshopAPI
Returns: Job - Photoshop Actions job

Job

Abstraction around the Photoshop Services Jobs

Kind: global class

Job
- new Job(response, getJobStatus)
- .url : string
- .jobId : string
- .outputs : Array.<JobOutput>
- .isDone() ⇒ boolean
- .poll() ⇒ Job
- .pollUntilDone([pollTimeMs]) ⇒ Job

new Job(response, getJobStatus)

Construct a job with the ability to acquire status updates

| Param | Type | Description | | --- | --- | --- | | response | * | Service response | | getJobStatus | function | Async function to get job status |

job.url : string

URL to request a status update of the job

Kind: instance property of Job

job.jobId : string

Job identifier

Kind: instance property of Job

job.outputs : Array.<JobOutput>

Status of each output sub job

Kind: instance property of Job

job.isDone() ⇒ boolean

Check if the job is done

A job is marked done when it has either the succeeded or failed status.

Kind: instance method of Job
Returns: boolean - True if the job is done, or false if it is still pending/running

job.poll() ⇒ Job

Poll for job status

Kind: instance method of Job
Returns: Job - Job instance

job.pollUntilDone([pollTimeMs]) ⇒ Job

Poll job until done

Kind: instance method of Job
Returns: Job - Job instance

| Param | Type | Default | Description | | --- | --- | --- | --- | | [pollTimeMs] | number | 2000 | Polling time |

Storage

Storage types

Kind: global enum
Read only: true
Properties

| Name | Default | Description | | --- | --- | --- | | AIO | aio | href is a path in Adobe I/O Files: https://github.com/adobe/aio-lib-files | | ADOBE | adobe | href is a path in Creative Cloud | | EXTERNAL | external | href is a presigned get/put url, e.g. AWS S3 | | AZURE | azure | href is an Azure SAS (Shared Access Signature) URL for upload/download | | DROPBOX | dropbox | href is a temporary upload/download Dropbox link: https://dropbox.github.io/dropbox-api-v2-explorer/ |

MimeType

Mime types

Kind: global enum
Read only: true
Properties

| Name | Default | Description | | --- | --- | --- | | DNG | image/x-adobe-dng | Digital Negative, available from autoTone, straighten, applyPreset | | JPEG | image/jpeg | JPEG, available from all operations | | PNG | image/png | PNG, available from all operations | | PSD | image/vnd.adobe.photoshop | Photoshop Document, available from createDocument, modifyDocument, createRendition, replaceSmartObject | | TIFF | image/tiff | TIFF format, available from createDocument, modifyDocument, createRendition, replaceSmartObject |

PngCompression

Compression level for PNG: small, medium or large.

Kind: global enum
Read only: true
Properties

| Name | Default | | --- | --- | | SMALL | small | | MEDIUM | medium | | LARGE | large |

Colorspace

Color space

Kind: global enum
Read only: true
Properties

| Name | Default | | --- | --- | | BITMAP | bitmap | | GREYSCALE | greyscale | | INDEXED | indexed | | RGB | rgb | | CMYK | cmyk | | MULTICHANNEL | multichannel | | DUOTONE | duotone | | LAB | lab |

StandardIccProfileNames

Standard ICC profile names

Kind: global enum
Read only: true
Properties

| Name | Default | | --- | --- | | ADOBE_RGB_1998 | Adobe RGB (1998) | | APPLE_RGB | Apple RGB | | COLORMATCH_RGB | ColorMatch RGB | | SRGB | sRGB IEC61966-2.1 | | DOTGAIN_10 | Dot Gain 10% | | DOTGAIN_15 | Dot Gain 15% | | DOTGAIN_20 | Dot Gain 20% | | DOTGAIN_25 | Dot Gain 25% | | DOTGAIN_30 | Dot Gain 30% | | GRAY_GAMMA_18 | Gray Gamma 1.8 | | GRAY_GAMMA_22 | Gray Gamma 2.2 |

CreateMaskType

Type of mask to create

Kind: global enum
Read only: true
Properties

| Name | Default | Description | | --- | --- | --- | | BINARY | binary | Binary mask | | SOFT | soft | Soft mask |

WhiteBalance

White balance enum

Kind: global enum
Read only: true
Properties

| Name | Default | | --- | --- | | AS_SHOT | As Shot | | AUTO | Auto | | CLOUDY | Cloudy | | CUSTOM | Custom | | DAYLIGHT | Daylight | | FLASH | Flash | | FLUORESCENT | Fluorescent | | SHADE | Shade | | TUNGSTEN | Tungsten |

ManageMissingFonts

Action to take if there are one or more missing fonts in the document

Kind: global enum
Read only: true
Properties

| Name | Default | Description | | --- | --- | --- | | USE_DEFAULT | useDefault | The job will succeed, however, by default all the missing fonts will be replaced with this font: ArialMT | | FAIL | fail | The job will not succeed and the status will be set to "failed", with the details of the error provided in the "details" section in the status |

BackgroundFill

Background fill

Kind: global enum
Read only: true
Properties

| Name | Default | | --- | --- | | WHITE | white | | BACKGROUND_COLOR | backgroundColor | | TRANSPARENT | transparent |

LayerType

Layer type

Kind: global enum
Read only: true
Properties

| Name | Default | Description | | --- | --- | --- | | LAYER | layer | A pixel layer | | TEXT_LAYER | textLayer | A text layer | | ADJUSTMENT_LAYER | adjustmentLayer | An adjustment layer | | LAYER_SECTION | layerSection | Group of layers | | SMART_OBJECT | smartObject | A smart object | | BACKGROUND_LAYER | backgroundLayer | The background layer | | FILL_LAYER | fillLayer | A fill layer |

BlendMode

Blend modes

Kind: global enum
Read only: true
Properties

| Name | Default | | --- | --- | | NORMAL | normal | | DISSOLVE | dissolve | | DARKEN | darken | | MULTIPLY | multiply | | COLOR_BURN | colorBurn | | LINEAR_BURN | linearBurn | | DARKER_COLOR | darkerColor | | LIGHTEN | lighten | | SCREEN | screen | | COLOR_DODGE | colorDodge | | LINEAR_DODGE | linearDodge | | LIGHTER_COLOR | lighterColor | | OVERLAY | overlay | | SOFT_LIGHT | softLight | | HARD_LIGHT | hardLight | | VIVID_LIGHT | vividLight | | LINEAR_LIGHT | linearLight | | PIN_LIGHT | pinLight | | HARD_MIX | hardMix | | DIFFERENCE | difference | | EXCLUSION | exclusion | | SUBTRACT | subtract | | DIVIDE | divide | | HUE | hue | | SATURATION | saturation | | COLOR | color | | LUMINOSITY | luminosity |

TextOrientation

Text orientation

Kind: global enum
Read only: true
Properties

| Name | Default | | --- | --- | | HORIZONTAL | horizontal | | VERTICAL | vertical |

ParagraphAlignment

Paragraph alignment

Kind: global enum
Read only: true
Properties

| Name | Default | | --- | --- | | LEFT | left | | CENTER | center | | RIGHT | right | | JUSTIFY | justify | | JUSTIFY_LEFT | justifyLeft | | JUSTIFY_CENTER | justifyCenter | | JUSTIFY_RIGHT | justifyRight |

HorizontalAlignment

Horizontal alignment

Kind: global enum
Read only: true
Properties

| Name | Default | | --- | --- | | LEFT | left | | CENTER | center | | RIGHT | right |

VerticalAlignment

Vertical alignment

Kind: global enum
Read only: true
Properties

| Name | Default | | --- | --- | | TOP | top | | CENTER | center | | BOTTOM | bottom |

JobOutputStatus

Output status

Kind: global enum
Read only: true
Properties

| Name | Default | Description | | --- | --- | --- | | PENDING | pending | request has been accepted and is waiting to start | | RUNNING | running | the child job is running | | UPLOADING | uploading | files have been generated and are uploading to destination | | SUCCEEDED | succeeded | the child job has succeeded | | FAILED | failed | the child job has failed |

shouldRetryFetch(response) ⇒ boolean

Determine if we should retry fetch due to Server errors (server busy or other application errors)

Kind: global function
Returns: boolean - true if we should retry or false if not

| Param | Type | Description | | --- | --- | --- | | response | * | Fetch response object, should at least have a status property which is the HTTP status code received |

nodeFetchRetry(options) ⇒ function

Fetch a URL, with retry options provided or default retry options otherwise By default retries will happen for 14 seconds (3 retries at 1, 2 and then 4 seconds -- there cannot be enough time for anotehr retry after that) Retry will occur if error code 429 or >= 500 occurs.

Kind: global function
Returns: function - Wrapped node fetch retry function which takes our preferred default options

| Param | Type | Description | | --- | --- | --- | | options | * | Fetch options object, which can also include retryOptions described here https://github.com/adobe/node-fetch-retry |

getFetchOptions(options) ⇒ *

Parse through options object and determine correct parameters to Swagger for desired fetch approach

Kind: global function
Returns: * - Swagger options object with relevant settings for fetch module

| Param | Type | Description | | --- | --- | --- | | options | * | Photoshop API options object |

init(orgId, apiKey, accessToken, [files], [options]) ⇒ Promise.<PhotoshopAPI>

Returns a Promise that resolves with a new PhotoshopAPI object.

Kind: global function
Returns: Promise.<PhotoshopAPI> - a Promise with a PhotoshopAPI object

| Param | Type | Description | | --- | --- | --- | | orgId | string | IMS organization id | | apiKey | string | the API key for your integration | | accessToken | string | the access token for your integration | | [files] | * | Adobe I/O Files instance | | [options] | PhotoshopAPIOptions | Options |