Asset Compute Service HTTP API

The use of the API is limited to development purposes. The API is provided as a context when developing custom applications. Adobe Experience Manager as a Cloud Service uses the API to pass the processing information to a custom application. For more information, see Use asset microservices and Processing Profiles.

Any client of the Asset Compute Service HTTP API must follow this high-level flow:

The @adobe/asset-compute-client module makes it easy to use the API in Node.js code.

Authentication and authorization

All APIs require access token authentication. The requests must set the following headers:

Scopes

Ensure the following scopes for the access token:

These require the Adobe Developer Console project to be subscribed to Asset Compute, I/O Events, and I/O Management API services. The breakdown of individual scopes is:

Registration

Each client of the Asset Compute service - a unique Adobe Developer Console project subscribed to the service - must register before making processing requests. The registration step returns the unique event journal which is required to retrieve the asynchronous events from rendition processing.

At the end of its lifecycle, a client can unregister.

Register request

This API call sets up an Asset Compute client and provides the event journal URL. This is an idempotent operation and only needs to be called once for each client. It can be called again to retrieve the journal URL.

Register response

The HTTP status codes are:

Unregister request

This API call unregisters an Asset Compute client. After this it is no longer possible to call /process. Using the API call for an unregistered client or a yet-to-be registered client returns a 404 error.

Unregister response

The status codes are:

Process request

The process operation submits a job that transforms a source asset into multiple renditions, based on the instructions in the request. Notifications about successful completion (event type rendition_created) or any errors (event type rendition_failed) are sent to an Event journal that must be retrieved using /register once before making any number of /process requests. Incorrectly formed requests immediately fail with a 400 error code.

Binaries are referenced using URLs, such as Amazon AWS S3 pre-signed URLs or Azure Blob Storage SAS URLs, for both reading the source asset (GET URLs) and writing the renditions (PUT URLs). The client is responsible for generating these pre-signed URLs.

Process request JSON

The request body of /process is a JSON object with this high-level schema:

{
    "source": "",
    "renditions" : []
}

The available fields are:

The source can either be a <string> that is seen as a URL or it can be an <object> with an additional field. The following variants are similar:

"source": "http://example.com/image.jpg"

"source": {
    "url": "http://example.com/image.jpg"
}

Source object fields

A complete process request example

{
    "source": "https://www.adobe.com/content/dam/acom/en/lobby/lobby-bg-bts2017-logged-out-1440x860.jpg",
    "renditions" : [{
            "name": "image.48x48.png",
            "target": "https://some-presigned-put-url-for-image.48x48.png",
            "fmt": "png",
            "width": 48,
            "height": 48
        },{
            "name": "image.200x200.jpg",
            "target": "https://some-presigned-put-url-for-image.200x200.jpg",
            "fmt": "jpg",
            "width": 200,
            "height": 200
        },{
            "name": "cqdam.xmp.xml",
            "target": "https://some-presigned-put-url-for-cqdam.xmp.xml",
            "fmt": "xmp"
        },{
            "name": "cqdam.text.txt",
            "target": "https://some-presigned-put-url-for-cqdam.text.txt",
            "fmt": "text"
    }]
}

Process response

The /process request immediately returns with a success or a failure based on the basic request validation. Actual asset processing happens asynchronously.

Status codes:

Most clients are likely inclined to retry the exact same request with exponential backoff on any error except configuration issues such as 401 or 403, or invalid requests like 400. Apart from regular rate limiting via 429 responses, a temporary service outage or limitation might result in 5xx errors. It would then be advisable to retry after a period of time.

All JSON responses (if present) include the requestId which is the same value as the X-Request-Id header. It is recommended to read from the header, since it is always present. The requestId is also returned in all events related to processing requests as requestId. Clients must not make any assumption about the format of this string, it is an opaque string identifier.

Opt-in to post-processing

The Asset Compute SDK supports a set of basic image post-processing options. Custom workers can explicitly opt in to post-processing by setting the field postProcess on the rendition object to true.

The supported use cases are:

Watermark assets

The Asset Compute SDK supports adding a watermark to PNG, JPEG, TIFF, and GIF image files. The watermark is added following the rendition instructions in the watermark object on the rendition.

Watermarking is done during rendition post-processing. To watermark assets, the custom worker opts into post-processing by setting the field postProcess on the rendition object to true. If the worker does not opt-in then watermarking does not applied, even if the watermark object is set on the rendition object in the request.

Rendition instructions

These are the available options for the renditions array in /process.

Common fields

Rendition specific fields

For a list of currently supported file formats, see supported file formats.

Watermark-specific fields

PNG format is used as a watermark.

Asynchronous events

Once processing of a rendition is finished or when an error occurs, an event is sent to an Adobe I/O Events Journal. Clients must listen to the journal URL provided through /register. The journal response includes an event array consisting of one object for each event, of which the event field includes the actual event payload.

The Adobe I/O Event type for all events of the Asset Compute Service is asset_compute. The journal is automatically subscribed to this event type only and there is no further requirement to filter based on the Adobe I/O Event type. The service specific event types are available in the type property of the event.

Event types

Event attributes

Metadata

Error reasons