GithubHelp home page GithubHelp logo

lightroom-api-docs's Introduction

Welcome to Lightroom API's!

The Adobe Lightroom APIs allow you to make Lightroom like automated edits to image files. This page is meant to help you onboard with the service and get you started with some basic usage examples. This service does not support the storage that Lightroom users have access to, instead, it allows users to use any other form of storage to work on their images. The list of supported storage systems are listed further below in this documentation.

Setup

Authentication

You must pass in an OAuth 2.0 access token with every request. The APIs do not provide any API methods for authentication or authorization. Access tokens are granted by Adobe's IMS service. The APIs need an access token with the scope="openid,creative_sdk", which you pass to the IMS Login Authorization API.

The access token must never be transmitted as a URI parameter. Doing so would expose it to being captured in-the-clear by intermediaries such as proxy server logs. The API does not allow you to send an access token anywhere except the Authorization header field.

There are two scenarios that require different authentication methods:

Individual users

You will be emailed your Client ID and Client Secret required for the IMS endpoint after you've been accepted to the PreRelease program. Once you've received your email...

  • Do a quick test:

  • Browse to https://ps-prerelease-us-east-1.cloud.adobe.io/

  • Add your Client ID and Client Secret sent in email

  • Enter your Adobe credentials when prompted

  • Use the access token to try the example calls further down this README

Additional instructions regarding the Adobe IMS endpoints can be found at Generating Access Tokens

Additional instructions can be found at Setting up OAuth authentication

Complete examples for OAuth endpoints can be found at OAuth endpoint examples

Service-to-service clients

For service-to-service clients you'll need to set up an Adobe I/O Console Integration and create a JSON Web Token (JWT) to retrieve your access token for API's. It is assumed your organization already has an Adobe IMS Org ID and you have added the required users to it.

Assets stored on Adobe's Creative Cloud

The Adobe Lightroom APIs currently have a limitation that Service clients must store their assets externally to Adobe's Creative Cloud.

Assets stored externally to Adobe

This applies to assets stored outside of Adobe's Creative Cloud and accessed via preSigned URL's

To retrieve your access token see additional instructions at Setting up JWT Authentication

API Keys

Also known as the client_id. You must pass in your Adobe API key in the x-api-key header field.

Retries

  • You should only retry requests that have a 5xx response code. A 5xx error response indicates there was a problem processing the request on the server.
  • You should implement an exponential back-off retry strategy with 3 retry attempts.
  • You should not retry requests for any other response code.

Rate Limiting

We have not put a throttle limit on requests to the API at this time.

General Workflow

The typical workflow involves specifying an image and the operation to be applied to it. The endpoint is asynchronous so the response will contain the /status endpoint to poll for job status and results

Input and Output file storage

Clients can use assets stored on one of the following storage types:

  1. Adobe: by referencing the path to the files on Creative Cloud
  2. External: (like AWS S3) by using a presigned GET/PUT URL
  3. Azure: By generating a SAS (Shared Access Signature) for upload/download
  4. Dropbox: Generate temporary upload/download links using https://dropbox.github.io/dropbox-api-v2-explorer/

Input and Output file formats

Any input image format that is supported by Lightroom is also supported by the APIs. To look at the list of these formats in more detail, please refer to: https://helpx.adobe.com/lightroom-classic/help/supported-file-formats.html

At this point the output formats supported are JPG, DNG and PNG.

Supported Features

This is a list of currently supported features

AutoTone

Automatically tone an image to correct exposure/contrast/sharpness/etc

/autoTone

The API is documented here

Example: Initiate a job to auto tone an image

curl -X POST \

-H "authorization: Bearer $token" \

-H "Content-Type:application/json" \

-H "x-api-key:$x-api-key" \

-d '{
    "inputs": {
        "href": "<href>",
        "storage": "<storage>"
    },
    "outputs": [
        {
            "href": "<href>",
            "type": "<type>",
            "storage": "<storage>",
            "overwrite": <boolean>
        }
    ]
}'

https://image.adobe.io/lrService/autoTone

This initiates an asynchronous job and returns a request body containing the href to poll for job status.

{
    "_links": {
        "self": {
            "href": "https://image.adobe.io/lrService/status/<:jobId>"
        }
    }
}

To check the status of the job completion, use the /status API. An example usage of the API can be found here.

AutoStraighten

Applies the Auto Upright transformation on an image

/autoStraighten

The API is documented here

Example: Initiate a job to auto straighten an image

curl -X POST \

-H "authorization: Bearer $token" \

-H "Content-Type:application/json" \

-H "x-api-key:$x-api-key" \

-d '{
    "inputs": {
        "href": "<href>",
        "storage": "<storage>"
    },
    "outputs": [
        {
            "href": "<href>",
            "type": "<type>",
            "storage": "<storage>",
            "overwrite": <boolean>
        }
    ]
}'

https://image.adobe.io/lrService/autoStraighten

This initiates an asynchronous job and returns a request body containing the href to poll for job status.

{
    "_links": {
        "self": {
            "href": "https://image.adobe.io/lrService/status/<:jobId>"
        }
    }
}

To check the status of the job completion, use the /status API. An example usage of the API can be found here.

Presets

Apply one or more XMP Lightroom presets to an image, by referencing preset file(s) stored on cloud. The preset file can be created by editing an image in lightroom and exporting it as a .xmp file. The details on how to create a preset can be found here. If the use case would be to be able to create an .xmp file from a set of slider values obtained directly from a user, there are 2 ways to achieve this workflow:

  1. Start with the empty .xmp file from here and add the corresponding slider values
  2. Or please look ahead in this documentation page at the /edit API

/presets

The API is documented here

Example : Initiate a job to apply presets to an image

curl -X POST \

-H "authorization: Bearer $token" \

-H "Content-Type:application/json" \

-H "x-api-key:$x-api-key" \

-d '{
    "inputs": {
        "source": {
            "href": "<href>",
            "storage": "<storage>"
        },
        "presets": [
            {
                "href": "<href1>",
                "storage": "<storage>"
            },
            {
                "href": "<href2>",
                "storage": "<storage>"
            }
        ]
    },
    "outputs": [
        {
            "href": "<href>",
            "type": "<type>",
            "storage": "<storage>",
            "overwrite": <boolean>
        }
    ]
}'

https://image.adobe.io/lrService/presets

This initiates an asynchronous job and returns a request body containing the href to poll for job status.

{
    "_links": {
        "self": {
            "href": "https://image.adobe.io/lrService/status/<:jobId>"
        }
    }
}

To check the status of the job completion, use the /status API. An example usage of the API can be found here.

Edit

Apply one or more Lightroom edits to an image.

/edit

The API is documented here The options section shown in the sample curl command below also indicates the set of Lightroom edits and the corresponding values that can be applied to the input image.

Example : Initiate a job to apply edits to an image

curl -X POST \

-H "authorization: Bearer $token" \

-H "Content-Type:application/json" \

-H "x-api-key:$x-api-key" \

-d '{
    "inputs": {
        "source": {
            "href": "<href>",
            "storage": "<storage>"
        }
    },
    "options": {
        "Exposure": -5.00 to 5.00,
        "Contrast": -100 to 100,
        "Sharpness": 0 10 150,
        "WhiteBalance": <"As Shot", "Auto", "Cloudy", "Custom", "Daylight", "Flash", "Fluorescent", "Shade", "Tungsten">
        "Saturation": -100 to 100,
        "ColorNoiseReduction": 0 to 100,
        "NoiseReduction": 0 to 100,
        "VignetteAmount": -100 to 100,
        "Vibrance": -100 to 100,
        "Highlights": -100 to 100,
        "Shadows": -100 to 100,
        "Whites": -100 to 100,
        "Blacks": -100 to 100,
        "Clarity": -100 to 100,
        "Dehaze": -100 to +100,
        "SharpenRadius": 0.5 to 3.0,
        "SharpenDetail": 0 to 100,
        "SharpenEdgeMasking": 0 to 100,
        "Texture": -100 t0 100
    },
    "outputs": [
        {
            "href": "<href>",
            "type": "<type>",
            "storage": "<storage>",
            "overwrite": <boolean>
        }
    ]
}'

https://image.adobe.io/lrService/edit

This initiates an asynchronous job and returns a request body containing the href to poll for job status.

{
    "_links": {
        "self": {
            "href": "https://image.adobe.io/lrService/status/<:jobId>"
        }
    }
}

To check the status of the job completion, use the /status API. An example usage of the API can be found here.

XMP

Apply a Lightroom preset to an image, by passing in the preset XMP contents inline through the API.

/xmp

The API is documented here

Example : Initiate a job to apply xmp to an image

curl -X POST \

-H "authorization: Bearer $token" \

-H "Content-Type:application/json" \

-H "x-api-key:$x-api-key" \

-d '{
    "inputs": {
        "href": "<href>",
        "storage": "<storage>"
    },
    "options": {
        "xmp": "<xmp>"
    },
    "outputs": [
        {
            "href": "<href>",
            "storage": "<storage>",
            "type": "<type>"
        }
    ]
}'

https://image.adobe.io/lrService/xmp

This initiates an asynchronous job and returns a request body containing the href to poll for job status.

{
    "_links": {
        "self": {
            "href": "https://image.adobe.io/lrService/status/<:jobId>"
        }
    }
}

To check the status of the job completion, use the /status API. An example usage of the API can be found here.

Job Status

/status

Check the status of job completion using the JobID returned from a call to one of the Lightroom APIs listed above.

Example: Poll for status and results

Use the JobID to poll on the href that is returned in the response from one of the Lightroom APIs.

  1. Upon successful job completion, the output file will be available at the specified output href.
  2. If the job failed due to an error, the errorDetails field in the response will contain the details of the failure.
curl -X GET \
  https://image.adobe.io/lrService/status/<jobId> \
  -H 'Authorization: Bearer <auth_token>' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: <YOUR_API_KEY>'

And this will return a request body containing the job status for each requested output and eventually either errors or the hrefs to the requested outputs

{
  "jobId":"<jobId>",
  "created":"2018-01-04T12:57:15.12345:Z",
  "modified":"2018-01-04T12:58:36.12345:Z",
  "outputs":[
  {
      "input":"<input_file_href>",
      "status":"succeeded",
      "_links":{
        "self":
        {
          "href":"<output_file_href>",
          "storage":"adobe"
        }
      }
    }
  ],
  "_links":{
    "self":{
      "href":"https://image.adobe.io/lrService/status/<jobId>"
    }
  }
}

Current Limitations

 

Release Notes

lightroom-api-docs's People

Contributors

alshamma avatar johnleetran avatar khound avatar macdonst avatar shayanc1985 avatar svarma123 avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.