
- Overview
- Resources
- API summary
- List policies
- Get a policy
- Create or modify a policy
- Remove a policy
- Get policy history
- List images
- Get an image
- List image collections
- Create a new image collection
- Get an image collection
- Update an image collection
- Remove an image collection
- Get image collection history
- List log details
- List error details
- Data
- Policy
- Image
- ImageCollection
- Video
- Spin360
- History
- Acknowledgement
- Transformation
- Append
- BackgroundColor
- Blur
- Composite
- Compound
- Contrast
- Crop
- FaceCrop
- FeatureCrop
- FitAndFill
- Goop
- Grayscale
- HLS
- HSV
- MaxColors
- Mirror
- Opacity
- RegionOfInterestCrop
- RelativeCrop
- Resize
- Rotate
- Scale
- Shear
- Trim
- UnsharpMask
- IfDimension
- IfOrientation
- BoxImageType
- TextImageType
- UrlImageType
- CircleShapeType
- PointShapeType
- PolygonShapeType
- RectangleShapeType
- UnionShapeType
- Variable
- Log
- Errors
Image and Video Manager API v2
Maintain a catalog of source images, organize and transform the images, and make them available for delivery by the Akamai Intelligent Platform.
Learn more:
Download this API’s RAML and JSON schema descriptors.
Overview
Image and Video Manager transforms a website’s images by creating derivative images of various sizes and formats, and dynamically selecting the best image when requested by an end user.
The API offers an end-to-end solution to archive, manage, and deliver transformed images based on customer defined policies.
Get started
To get started with this API:
Contact your Akamai representative to enable Image and Video Manager for your account.
Review Get Started with APIs for details on how to set up client tokens to access any Akamai API. These tokens appear as custom hostnames that look like this:
https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net
.To enable this API, choose the API service named Image and Video Manager, and set the access level to read-write.
Enable Image and Video Manager on a property in Property Manager, then use the Policy Set Name (API key) in the behavior for the
Luna-Token
header. In this API you need to pass in an additionalLuna-Token
header with each request, which may look something like this:default-022335
.If you want to generate a custom API token to apply a corresponding policy, use the imageManager behavior in PAPI.
Disable any behaviors that are incompatible with Image and Video Manager, like adaptiveImageCompression and edgeImageConversion.
If using Front-End Optimization, disable the Optimize Images, Optimize CSS: Image Compression, and Optimize CSS: Use Web Resolution optimizations.
For on-demand transformations and testing, apply optional query string parameters to image requests.
Test images on-demand
For on-demand transformations and testing, you can add these optional query string parameters to a website’s image URLs:
Parameter | Type | Description |
---|---|---|
imformat |
Enumeration | Requests a specific browser type. Supported browser types are chrome , ie , safari , generic . By default, Image and Video Manager detects the browser and returns the appropriate image. |
imwidth |
Integer | Requests an image with a specific width. |
impolicy |
String | Requests to apply a specific image policy. |
You can combine the impolicy
, imwidth
and imformat
query
parameters in a single request to perform several transformations.
Here are some examples of using these query strings individually and
grouped together:
www.example.com/assets/images/image001.jpg?imformat=safari
: Returns the best image, in these format types: JPEG, PNG, GIF, and JPEG 2000 for the Safari browser.www.example.com/assets/images/image001.jpg?imwidth=300
: Returns an image the next size up from the 300px width defined in the query parameter. In this case, assuming the.auto
policy is used, Image Manager returns the 320px image.www.example.com/assets/images/image001.jpg?impolicy=watermark
: Combinesimage001.jpg
with an image the policy provides and returns a composite image.www.example.com/assets/images/image001.jpg?impolicy=watermark&imwidth=300&imformat=safari
: Returns an 320px image with the company logo added, and in the format best for Safari.
Image and Video Manager concepts
This section provides information about common concepts.
Preset Transformations: Image and Video Manager automatically transforms a website’s images by creating derivative images of various sizes and formats, and dynamically selecting the appropriate image when requested by an end user. You can create policies to modify how a website’s images are transformed.
On-Demand Transformations: Image and Video Manager also supports on-demand transformations, using query string parameters. These parameters allow you to specify which derivative image to select, force the selection of a particular output format, or specify a different policy.
API Key: Like other Akamai APIs, this API uses hostname tokens to authenticate requests. However, in this API you need to pass in an additional
Luna-Token
header with each request. You get this key from the Image and Video Manager behavior in your Property Manager configuration that applies to the set of images you’re working on.Policy: A policy is a set of specifications applied to a derivative image. Policies may contain information about the image sizes to use for various screens, desired output formats (WebP, JPEG, and PNG), and image manipulations like watermarks. After a policy is applied to a derivative image, Image and Video Manager transforms the image based on the information in that policy.
Default Policy: Image and Video Manager automatically applies the default
.auto
policy unless a request includes a parameter indicating a valid custom policy name. It provides the baseline settings that determine how the policy generates derivatives. You can modify the.auto
policy to select different image transformations, but you can’t delete it. The.auto
policy is always active on both the staging and production networks. By default, the.auto
policy has aquality
setting of85
. The default image widths in pixels are320
,640
,1024
,2048
, and5000
.Cache Key: Image and Video Manager adds the policy name and version to an image’s cache key. Be aware that any policy modification invalidates any images using the policy. For the default policy, this may cause an unexpected surge in traffic to your origin image content. You should test out any policy changes in the Akamai staging network. Once you complete testing, activate the policy in production.
Transformations: Each policy specifies a set of transformations to perform on a source image. Some transformations are only performed if certain conditions are met. See the Transformation object type for more information.
Variables: Within a policy, you can define a set of variables that supply the values to use with transformations.
Image Collections: Image, or media, collections let you organize images and other media assets into logical groups, which is useful for viewing these assets together on a website. A collection might represent a particular product on an e-commerce site or a set of images related to a news article.
Quality (default): Using a
quality
value from 1–100 resembles JPEG quality across output formats. The default is 85.Perceptual Quality: Dynamically tunes the quality parameter for each image format based on the human-perceived quality of the output image. For better byte savings without compromising perception of the image, use
perceptualQuality
instead ofquality
to encode many images at a much lower quality. For certain images that need to maintain human-perceived quality, encode them at a slightly higher quality.
Transformation types
Transformations are tools for modifying images. You can include many transformations in a policy. Transformations can be any of these specialized object types:
Transformation | Description |
---|---|
Append | Specifies an image or text to affix beside the image you’re transforming, also referred to as the source image. The API places the appended image on a major dimension, then aligns the image on the minor dimension. When you append to a source image, there might be an area created that’s not covered by either image. Transparent pixels fill this area. |
BackgroundColor | Places a transparent image on a set background color. Color is specified in the typical CSS hexadecimal format. |
Blur | Applies a Gaussian blur to the image. |
Composite | Applies another image to the source image, either as an overlay or an underlay. The image that’s underneath is visible in areas that are beyond the edges of the top image or that are less than 100% opaque. A common use of an overlay composite is to add a watermark. |
Compound | An ordered combination of transformations to perform. Use to represent a sequence of transformations as a single transformation. |
Contrast | Adjusts both the contrast and brightness of an image. |
Crop | Cuts the image down to an area you specify. Use this transformation to describe the size and position of a box indicating the portion of the image to preserve. |
FaceCrop | Detects faces in an image, then crops them to position the faces in the center of the image. |
FeatureCrop | Identifies prominent features of an image such as strong corners, then crops around those features. |
FitAndFill | Uses aspect fitting to resize an image to the exact dimensions specified. This transformation then uses aspect fill on any remaining areas of the image. |
Goop | Distorts an image. For example, think of your image printed on a rubber sheet of paper with a grid of pins, also referred to as control points, in the rubber. Goop shifts the pins a random distance in a random direction, distorting the image on the rubber. The results look like a goopy version of the image. You can use this to create non-deterministic watermarks for security purposes. |
Grayscale | Renders the image in shades of black, white, and gray. |
HLS | Adjusts the hue, saturation, and lightness (HSL) of an image. Hue is the number of degrees that colors rotate around the color wheel. Saturation is a multiplier to increase or decrease color saturation. Lightness is a multiplier to increase or decrease the lightness of an image. Other transformations can also affect color, such as Grayscale and Max Colors . If you’re using more than one, consider the order to apply them for the desired results. |
HSV | Identical to HSL except it replaces lightness with value . For example, if you reduce the lightness of a light green, almost white, image, the color turns a vibrant green. Reducing the value , turns the image a darker color, close to gray. This is because the original image color is very close to white. |
MaxColors | Sets the maximum number of color in the image’s palette. Reducing the number of colors in an image can help reduce file size. |
Mirror | Flips an image horizontally, vertically, or both. |
Opacity | Changes the opacity of an image. Use this transformation to make an image more transparent. Values below 1.0 increase transparency; 0.0 is invisible. For images that have some transparency, values above 1.0 increase the opacity of the transparent portions. |
RegionOfInterestCrop | Crops to a region around a specified area of interest. |
RelativeCrop | Shrinks or expands the four sides of an image relative to its current dimensions. Transparent pixels fill this expanded area. |
Resize | Resizes an image to a particular, absolute dimension. If you don’t enter a width or a height , the image is resized with the fit aspect preservation mode, which selects a value for the missing dimension that preserves the image’s aspect. |
Rotate | Rotates the image around its center by indicating the degrees of rotation. Positive values rotate clockwise and negative values rotate counter-clockwise. |
Scale | Changes the image size relative to the starting size, expressed as a percentage of the width and height. You can scale width and height independently. |
Shear | Slants an image into a parallelogram, as a percent of starting dimension as represented in decimal format. You need to specify at least one axis property. Transparent pixels fill empty areas around the sheared image as needed. It’s useful to use backgroundColor transformation for these areas. |
Trim | Automatically crops uniform backgrounds from the edges of an image. |
UnsharpMask | Emphasizes edges and details in source images without distorting the colors. Although this effect is often referred to as sharpening an image, it actually creates a blurred, inverted copy of the image, or unsharp mask. Image and Video Manager combines the unsharp mask with the source image to create a clearer image. |
These transformations operate conditionally based on qualities of the source image:
Transformation | Description |
---|---|
IfDimension | Chooses a transformation depending on the dimensions of the source image. You need to select a dimension for comparison, which is either width and height or both . |
IfOrientation | Chooses a transformation depending on the orientation of the source image. |
Several transformations may specify these types of images:
Transformation | Description |
---|---|
BoxImageType | A rectangular box, with a specified color and applied transformation. |
TextImageType | A snippet of text. Defines font family and size, fill color, and outline stroke width and color. |
UrlImageType | An image loaded from a URL. |
Several transformations may specify these types of shapes:
Transformation | Description |
---|---|
CircleShapeType | Defines a circle with a specified radius from its center point. |
PointShapeType | Defines coordinates for a single point, to help define polygons and rectangles. Each point may be an object with x and y members, or a two-element array. |
PolygonShapeType | Defines a polygon from a series of connected points. |
RectangleShapeType | Defines a rectangle’s width and height relative to an anchor point. |
UnionShapeType | Identifies a combined shape based on a set of other shapes. You can use a full JSON object to represent a union or an array of shapes that describe it. |
Many of these object types also allow you to specify a Variable object as an alternative to a string, number, or boolean value. These correspond to the name of any variable defined within the policy, and optionally passed in as image URL query parameters.
Resources
The Image and Video Manager API allows you to create, list, and modify policies, and organize images.
Follow this basic workflow to create a custom policy:
Enable Image and Video Manager on a property in Property Manager.
Get the
Luna-Token
header generated once Image and Video Manager is enabled on a property. This header, or API key, is needed for all API calls and may look something like this:default-022335
.Determine which image transformations you want to include in the policy.
Run the List policies operation to get a list of all current policies.
Review the list of policy IDs (
policyId
) returned.Create a Policy object.
Run the Create or modify a policy operation, making sure to provide a new, unique
policyId
value. Otherwise you may overwrite an existing policy.Before going live with a policy, activate the policy on the staging network. To activate a policy, add
-staging
to the hostname used for the request. For example, to activate a custom policy with an ID ofmobile-policy
on staging, you’d use this URL:https://akab-xxxxx-xxxxxxxxxx.imaging-staging.akamaiapis.net/imaging/v2/policies/mobile-policy
To activate the default policy on staging, use this hostname:
https://akab-xxxxx-xxxxxxxxxx.imaging-staging.akamaiapis.net/imaging/v2/policies/.auto
Test the policy on the staging network, then activate the policy using the regular hostname. For example:
https://akab-xxxxx-xxxxxxxxxx.imaging.akamaiapis.net/imaging/v2/policies/mobile-policy.
API summary
Download the RAML descriptors for this API.
Operation | Method | Endpoint |
---|---|---|
Policies | ||
List policies | GET | /imaging/ |
Get a policy | GET | /imaging/ |
Create or modify a policy | PUT | /imaging/ |
Remove a policy | DELETE | /imaging/ |
Get policy history | GET | /imaging/ |
Images | ||
List images | GET | /imaging/ |
Get an image | GET | /imaging/ |
Image Collections | ||
List image collections | GET | /imaging/ |
Create a new image collection | PUT | /imaging/ |
Get an image collection | GET | /imaging/ |
Update an image collection | POST | /imaging/ |
Remove an image collection | DELETE | /imaging/ |
Get image collection history | GET | /imaging/ |
Log error details | ||
List log details | GET | /imaging/ |
List error details | GET | /imaging/ |
List policies
Returns a list of all policies using a specific instance of the Image and Video Manager behavior.
GET /imaging/
Headers:
Luna-Token: default-022335
Status 200
application/json
Object type: Policy
Download schema: get-policies.json
Response body:
{
"totalItems": 2,
"itemKind": "POLICY",
"items": [
{
"id": ".auto"
},
{
"id": "watermark"
}
]
}
Get a policy
Returns a specific policy assigned to the selected API key.
GET /imaging/
Sample: /imaging/
Headers:
Luna-Token: default-022335
Parameter | Type | Sample | Description |
---|---|---|---|
URL path parameters | |||
policyId |
String | thumbnail_policy |
Unique identifier for a policy. |
Status 200
application/json
Object type: Policy
Download schema: policy.json
Response body:
{
"id": "watermark",
"breakpoints": {
"widths": [
500,
300
]
},
"output": {
"quality": 90
},
"transformations": [
{
"transformation": "Composite",
"xPosition": 0,
"yPosition": 0,
"gravity": "SouthWest",
"image": {
"url": "www.customer.com/watermark.png"
}
}
]
}
Run the List policies operation and store the policy ID (
id
).Make a GET request to
/
.imaging/ v2/ policies/ {policyId}
The response includes the Policy object.
Create or modify a policy
Create a policy or update the policy definition for a given ID.
When creating a new policy, make sure the policyId
doesn’t already exist.
PUT /imaging/
Sample: /imaging/
Headers:
Luna-Token: default-022335
Content-Type: application/json
Object type: Policy
Download schema: policy.json
Request body:
{
"breakpoints": {
"widths": [
240,
120,
60
]
}
}
Parameter | Type | Sample | Description |
---|---|---|---|
URL path parameters | |||
policyId |
String | thumbnail_policy |
Unique identifier for a policy. |
Status 200
application/json
Object type: Acknowledgement
Download schema: operation-performed.json
Response body:
{
"operationPerformed": "UPDATED",
"description": "Policy thumbnail_policy updated.",
"id": "thumbnail_policy"
}
Run the List policies operation and store the
policyId
.Review the list of policy IDs (
policyId
) returned.Create a Policy object.
Run the Create or modify a policy operation, making sure to provide a new, unique
policyId
value. Otherwise you may overwrite an existing policy.
The response includes the Policy object.
Remove a policy
Delete a specific policy ID.
DELETE /imaging/
Sample: /imaging/
Headers:
Luna-Token: default-022335
Parameter | Type | Sample | Description |
---|---|---|---|
URL path parameters | |||
policyId |
String | thumbnail_policy |
Unique identifier for a policy. |
Status 200
application/json
Object type: Acknowledgement
Download schema: operation-performed.json
Response body:
{
"operationPerformed": "DELETED",
"description": "Policy thumbnail_policy deleted.",
"id": "thumbnail_policy"
}
Run the List policies operation and store the policy ID (
id
).Make a DELETE request to
/
.imaging/ v2/ policies/ {policyId}
Get policy history
Returns the policy history by policy ID. This operation returns the full state of the policy at various points in time. Time stamps are in ISO 8601 extended notation format.
GET /imaging/
Sample: /imaging/
Headers:
Luna-Token: default-022335
Parameter | Type | Sample | Description |
---|---|---|---|
URL path parameters | |||
policyId |
String | thumbnail_policy |
Unique identifier for a policy. |
Status 200
application/json
Object type: History
Download schema: get-policy-history.json
Response body:
{
"itemKind": "POLICIESLOG",
"totalItems": 1,
"items": [
{
"id": "thumbnail_policy",
"dateCreated": "2015-06-09 15:41:37+0000",
"policy": "{\"id\":\"grayscale\",\"transformations\":[{\"transformation\":\"Grayscale\"}],\"resolutions\":{\"widths\":[500]},\"currentVersion\":1}",
"action": "UPSERT",
"user": "jsmith"
}
]
}
Run the List policies operation and store the policy ID (
id
).Make a GET request to
/
.imaging/ v2/ policies/ history/ {policyId}
The response includes the History object.
List images
List a policy’s images.
GET /imaging/
Sample: /imaging/
Headers:
Luna-Token: default-022335
Parameter | Type | Sample | Description |
---|---|---|---|
Optional query parameters | |||
limit |
Integer | 2 |
Specifies maximum number of images to get. |
policyId |
String | thumbnail_policy |
The policy to list images for. |
url |
String | http://www.example.com/image2.png |
URL to search for. |
Status 200
application/json
Object type: Image
Download schema: get-images.json
Response body:
{
"totalItems": 1,
"itemKind": "IMAGE",
"items": [
{
"id": "/images/image2.png",
"url": "http://www.example.com/images/image2.png",
"policies": {
"watermark": {
"sizes": {
"200": {
"date": "2016-03-23 13:05:59+0000",
"policyVersion": 1,
"status": "PASSED"
}
}
}
}
}
]
}
Run the List policies operation and store the
policyId
.Optionally, to specify the number of results to return, use the
limit
query parameter. If you want 10 results, add?limit=10
to the URL.Optionally, to return images contained within a specific URL path, use the
url
query parameter.Make a GET request to
/
.imaging/ v0/ images/ {?limit, url, policyId}
The response includes the Image object.
Get an image
Returns a specific image.
GET /imaging/
Sample: /imaging/
Headers:
Luna-Token: default-022335
Parameter | Type | Sample | Description |
---|---|---|---|
URL path parameters | |||
imageId |
String | /images/image.jpg?imageId=format/jpg |
The ID of the image. This ID usually represents the part of the URL after the scheme, host, and port. |
Status 200
application/json
Object type: Image
Download schema: image.json
Response body:
{
"id": "/house/image1.jpg",
"url": "http://www.example.com/house/image1.jpg",
"policies": {
".auto": {
"sizes": {
"50": {
"date": "2016-03-22 13:05:59+0000",
"policyVersion": 1,
"status": "PASSED"
}
}
}
}
}
Run the List images operation and store the
imageId
.Make a GET request to
/
.imaging/ v0/ images/ {imageId}
The response includes the Image object.
List image collections
Lists all image collections, unless you set a limit.
GET /imaging/
Sample: /imaging/
Parameter | Type | Sample | Description |
---|---|---|---|
Optional query parameters | |||
limit |
Integer | 2 |
Specifies maximum number image collections to get. |
Status 200
application/json
Object type: ImageCollection
Download schema: image-collection-definition-array-response.json
Response body:
{
"itemKind": "IMAGECOLLECTION",
"totalItems": 2,
"items": [
{
"id": "product-1",
"user": "johndoe",
"lastModifiedTimestamp": 1509418397284,
"definition": {
"version": 1,
"items": [
{
"type": "image",
"url": "http://example.com/img1.jpg",
"mime": "image/jpeg"
},
{
"type": "image",
"url": "http://example.com/img2.jpg",
"mime": "image/jpeg"
}
]
}
},
{
"id": "product-2",
"user": "janedoe",
"lastModifiedTimestamp": 1509418397284,
"definition": {
"version": 1,
"items": [
{
"type": "video",
"url": "http://example.com/vid1.mp4",
"mime": "video/mp4"
},
{
"type": "video",
"url": "http://example.com/vid2.webm",
"mime": "video/webm"
}
]
}
}
]
}
Optionally, to specify the number of results to return, use the
limit
query parameter. If you want 10 results, add?limit=10
to the URL.Make a GET request to
/
.imaging/ v0/ imagecollections/ {?limit}
The response includes the ImageCollection object.
Create a new image collection
Create a new image collection.
PUT /imaging/
Content-Type: application/json
Object type: ImageCollection
Download schema: image-collection.json
Request body:
{
"id": "api_sample_collection",
"definition": {
"items": [
{
"type": "image",
"url": "http://productdemo.akaimaging.com/samples/sample01.png"
},
{
"type": "image",
"url": "http://productdemo.akaimaging.com/samples/sample02.png"
},
{
"type": "spin360",
"urls": [
"http://productdemo.akaimaging.com/samples/sample03.png",
"http://productdemo.akaimaging.com/samples/sample04.png",
"http://productdemo.akaimaging.com/samples/sample05.png"
]
}
]
}
}
Status 200
application/json
Object type: Acknowledgement
Download schema: operation-performed.json
Response body:
{
"operationPerformed": "CREATED",
"description": "Image Collection SKU-26684355 was created",
"id": "SKU-26684355"
}
Run the List image collections operation.
Review the list of IDs (
imageCollectionId
) returned.Create a unique
imageCollectionId
for the new collection.Create an ImageCollection object.
Make a PUT request to
/
.imaging/ v0/ imagecollections/
The response includes the ImageCollection object.
Get an image collection
Returns the values for the image collection you specify.
GET /imaging/
Sample: /imaging/
Parameter | Type | Sample | Description |
---|---|---|---|
URL path parameters | |||
imageCollectionId |
String | MyId123 |
Unique identifier for each image collection. |
Status 200
application/json
Object type: ImageCollection
Download schema: image-collection-definition.json
Response body:
{
"id": "api_sample_collection",
"definition": {
"items": [
{
"type": "image",
"url": "http://productdemo.akaimaging.com/samples/sample01.png"
},
{
"type": "image",
"url": "http://productdemo.akaimaging.com/samples/sample02.png"
},
{
"type": "spin360",
"urls": [
"http://productdemo.akaimaging.com/samples/sample03.png",
"http://productdemo.akaimaging.com/samples/sample04.png",
"http://productdemo.akaimaging.com/samples/sample05.png"
]
}
]
}
}
Run the List image collections operation and store the
imageCollectionId
.Make a GET request to
/
.imaging/ v0/ imagecollections/ {imageCollectionId}
The response includes the ImageCollection object.
Update an image collection
Update an image collection.
POST /imaging/
Sample: /imaging/
Content-Type: application/json
Object type: ImageCollection
Download schema: image-collection.json
Request body:
{
"id": "api_sample_collection",
"definition": {
"items": [
{
"type": "image",
"url": "http://productdemo.akaimaging.com/samples/sample01.png"
},
{
"type": "image",
"url": "http://productdemo.akaimaging.com/samples/sample02.png"
},
{
"type": "spin360",
"urls": [
"http://productdemo.akaimaging.com/samples/sample03.png",
"http://productdemo.akaimaging.com/samples/sample04.png",
"http://productdemo.akaimaging.com/samples/sample05.png"
]
}
]
}
}
Parameter | Type | Sample | Description |
---|---|---|---|
URL path parameters | |||
imageCollectionId |
String | MyId123 |
Unique identifier for each image collection. |
Status 200
application/json
Object type: Acknowledgement
Download schema: operation-performed.json
Response body:
{
"operationPerformed": "UPDATED",
"description": "Image Collection api_sample_collection was updated",
"id": "api_sample_collection"
}
Run the List image collections operation and store the
imageCollectionId
you want to update.Create an ImageCollection object.
Make a POST request to
/
.imaging/ v0/ imagecollections/ {imageCollectionId}
The response includes the ImageCollection object.
Remove an image collection
Delete a specific image collection.
DELETE /imaging/
Sample: /imaging/
Parameter | Type | Sample | Description |
---|---|---|---|
URL path parameters | |||
imageCollectionId |
String | MyId123 |
Unique identifier for each image collection. |
Status 200
application/json
Object type: Acknowledgement
Download schema: operation-performed.json
Response body:
{
"operationPerformed": "DELETED",
"description": "Item was deleted",
"id": "MyId123"
}
Run the List image collections operation and store the
imageCollectionId
.Make a DELETE request to
/
.imaging/ v0/ imagecollections/ {imageCollectionId}
Get image collection history
Get a history of a specific image collection and all updates to it over the last three months.
GET /imaging/
Sample: /imaging/
Parameter | Type | Sample | Description |
---|---|---|---|
URL path parameters | |||
imageCollectionId |
String | MyId123 |
Unique identifier for each image collection. |
Optional query parameters | |||
limit |
Integer | 2 |
Specifies maximum number of image collections to get. |
Status 200
application/json
Object type: ImageCollection
Download schema: image-collection-definition-array-response.json
Response body:
{
"itemKind": "IMAGECOLLECTIONHISTORY",
"totalItems": 2,
"items": [
{
"id": "product-1",
"user": "janedoe",
"lastModifiedTimestamp": 1509418397300,
"definition": {
"version": 1,
"items": [
{
"type": "image",
"url": "http://url.com/img1.jpg",
"mime": "image/jpeg"
},
{
"type": "image",
"url": "http://url.com/img2.jpg",
"mime": "image/jpeg"
}
]
}
},
{
"id": "product-1",
"user": "johndoe",
"lastModifiedTimestamp": 1509418397284,
"definition": {
"version": 1,
"items": [
{
"type": "image",
"url": "http://url-bad.com/img1.jpg",
"mime": "image/jpeg"
},
{
"type": "image",
"url": "http://url-bad.com/img2.jpg",
"mime": "image/jpeg"
}
]
}
}
]
}
Run the List image collections operation and store the
imageCollectionId
.Optionally, to specify the number of results to return, use the
limit
query parameter. If you want 10 results, add?limit=10
to the URL.Make a GET request to
/
.imaging/ v0/ imagecollections/ {imageCollectionId}/ history{?limit}
The response includes the ImageCollection object.
List log details
Returns a list of image or video logs for the transformations requested in the past three days.
GET /imaging/
Sample: /imaging/
Headers:
Luna-Token: default-022335
Parameter | Type | Sample | Description |
---|---|---|---|
Optional query parameters | |||
limit |
Integer | 10 |
Specifies the maximum number of logs per day. |
policyId |
String | image_video_policy |
Filters the policy to a specific image or video policy. To get a specific policy identifier, run the List policies operation. |
size |
Integer | 5000 |
Size breakpoint, in pixels, configured in the policy. |
transformationType |
Enumeration | REALTIME |
Filters results to include transformations done in REALTIME or queued for OFFLINE processing. |
url |
String | http://www.example.com/video.mp4 |
Limits search results to a specific image or video URL. |
Status 200
application/json
Object type: Log
Download schema: get-image-video-logs.json
Response body:
{
"itemKind": "LOGDETAILS",
"totalItems": 2,
"items": [
{
"url": "http://www.customer.com/video.mp4",
"policyId": "videoPolicy",
"size": 854,
"transformationType": "REALTIME",
"status": "PASSED",
"startTime": "2020-01-29 02:45:34",
"completeTime": "2020-01-29 02:45:36"
},
{
"url": "http://www.customer.com/video.mp4",
"policyId": "videoPolicy",
"size": 854,
"transformationType": "OFFLINE",
"status": "PASSED",
"startTime": "2020-01-29 02:45:37",
"completeTime": "2020-01-29 02:45:39",
"pendingTime": "2020-01-29 02:45:36"
}
]
}
List error details
Returns a list of image or video errors for the transformations requested in the past three days.
GET /imaging/
Sample: /imaging/
Headers:
Luna-Token: default-022335
Parameter | Type | Sample | Description |
---|---|---|---|
Optional query parameters | |||
limit |
Integer | 10 |
Specifies the maximum number of logs per day. |
policyId |
String | image_video_policy |
Filters the policy to a specific image or video policy. To get a specific policy identifier, run the List policies operation. |
size |
Integer | 5000 |
Size breakpoint, in pixels, configured in the policy. |
transformationType |
Enumeration | REALTIME |
Filters results to include transformations done in REALTIME or queued for OFFLINE processing. |
url |
String | http://www.example.com/video.mp4 |
Limits search results to a specific image or video URL. |
Status 200
application/json
Object type: Log
Download schema: get-image-video-errors.json
Response body:
{
"itemKind": "LOGDETAILS",
"totalItems": 1,
"items": [
{
"url": "http://www.customer.com/video.mp4",
"policyId": "videoPolicy",
"size": 854,
"transformationType": "REALTIME",
"reason": "BYTES",
"threshold": 268435456,
"actual": 276134947,
"status": "FAILED",
"startTime": "2020-04-13 06:20:06",
"completeTime": "2020-04-13 06:20:07"
}
]
}
Data
This section provides details for each type of data object the API exchanges.
Data values follow these general conventions:
Any radial degree value outside the range of
0
to360
has the expected rotational equivalence.For any color, CSS hex values follow
#RGB
,#RGBA
,#RRGGBB
, or#RRGGBBAA
syntax.
Download the JSON schemas for this API.
This section’s data schema tables list membership requirements as follows:
✓ | Member is required in requests, or always present in responses, even if its value is empty or null . |
○ | Member is optional, and may be omitted in some cases. |
Policy
Specifies details for each policy, such as transformations to apply and variations in image size and formats.
Download schema:
policy.json
Sample GET response:
{
"id": "watermark",
"breakpoints": {
"widths": [
500,
300
]
},
"output": {
"quality": 90
},
"transformations": [
{
"transformation": "Composite",
"xPosition": 0,
"yPosition": 0,
"gravity": "SouthWest",
"image": {
"url": "www.customer.com/watermark.png"
}
}
]
}
Policy members
Member | Type | Required | Description |
---|---|---|---|
Policy : Specifies details for each policy, such as transformations to apply and variations in image size and formats. |
|||
breakpoints |
Policy. |
○ | The breakpoint widths to use to create derivative images. |
hosts |
Array | ○ | Hosts that are allowed for Composite image URLs. |
id |
String | ○ | Unique identifier for a policy, up to 64 alphanumeric characters including underscores or dashes. |
output |
Policy. |
○ | Dictates the output quality (either quality or perceptualQuality ) and formats that are created for each resized image. If unspecified, image formats are created to support all browsers at the default quality level (85 ), which includes formats such as WEBP, JPEG2000 and JPEG-XR for specific browsers. |
post |
Transformation array | ○ | Transformations applied to the source image after the images for the carousel’s main image view are created. |
transformations |
Transformation array | ○ | Transformations applied to the source image. |
variables |
Policy. |
○ | Declares variables for use within the policy. Any variable declared here can be invoked throughout transformations as a Variable object, so that you don’t have to specify values separately. You can also pass in these variable names and values dynamically as query parameters in the image’s request URL. |
Policy.breakpoints : The breakpoint widths to use to create derivative images. |
|||
widths |
Array | ○ | Specifies each integer breakpoint width value. |
Policy.output : Dictates the output quality (either quality or perceptualQuality ) and formats that are created for each resized image. If unspecified, image formats are created to support all browsers at the default quality level (85 ), which includes formats such as WEBP, JPEG2000 and JPEG-XR for specific browsers. |
|||
allowedFormats |
Array | ○ | The values of the allowed graphics file formats. |
forcedFormats |
Array | ○ | The values of the forced extra formats. |
perceptual |
Object, Enumeration | ○ | The perceptual quality to use when comparing resulting images, which overrides the quality setting. Perceptual quality tunes each image format’s quality parameter dynamically based on the human-perceived quality of the output image. This can result in better byte savings (as compared to using regular quality) as many images can be encoded at a much lower quality without compromising perception of the image. In addition, certain images may need to be encoded at a slightly higher quality in order to maintain human-perceived quality. Values are tiered high , mediumHigh , medium , mediumLow , or low . Allows Variable substitution. |
quality |
Object, Integer | ○ | The chosen quality of the output images. Using a quality value from 1–100 resembles JPEG quality across output formats. Allows Variable substitution. |
Policy.variables[] : Declares variables for use within the policy. Any variable declared here can be invoked throughout transformations as a Variable object, so that you don’t have to specify values separately. You can also pass in these variable names and values dynamically as query parameters in the image’s request URL. |
|||
defaultValue |
String | ✓ | The default value of the variable if no query parameter is provided. It needs to be one of the enumOptions if any are provided. |
enumOptions |
Policy. |
○ | Optionally limits the set of possible values for a variable. References to an enum id insert a corresponding value . |
name |
String | ✓ | The name of the variable, also available as the query parameter name to set the variable’s value dynamically. Use up to 50 alphanumeric characters. |
postfix |
String | ○ | A postfix added to the value provided for the variable, or to the default value. |
prefix |
String | ○ | A prefix added to the value provided for the variable, or to the default value. |
type |
Enumeration | ✓ | The type of variable, either bool , number , url , color , gravity , placement , scaleDimension , grayscaleType , aspect , resizeType , dimension , or perceptualQuality . |
Policy.variables[].enumOptions[] : Optionally limits the set of possible values for a variable. References to an enum id insert a corresponding value . |
|||
id |
String | ✓ | The unique identifier for each enum value, up to 50 alphanumeric characters. |
value |
String | ✓ | The value of the variable when the id is provided. |
Image
Collects information that describes an image.
Download schema:
image.json
Sample GET response:
{
"id": "/house/image1.jpg",
"url": "http://www.example.com/house/image1.jpg",
"policies": {
".auto": {
"sizes": {
"50": {
"date": "2016-03-22 13:05:59+0000",
"policyVersion": 1,
"status": "PASSED"
}
}
}
}
}
Image members
Member | Type | Required | Description |
---|---|---|---|
Image : Collects information that describes an image. |
|||
description |
String | ○ | A description of the action performed on the image. |
id |
String | ○ | The ID of the image. |
ordinal |
Integer | ○ | The ordinal of the image. |
policies |
Policy map | ○ | The policies applied to this image. |
url |
String | ○ | The URL of the image. |
ImageCollection
Provides data about the types of items included in an image collection.
Download schema:
image-collection-definition.json
Sample GET response:
{
"totalItems": 2,
"itemKind": "IMAGE",
"items": [
{
"id": "/images/image1.png",
"url": "http://www.example.com/images/image1.png",
"policies": {
".auto": {
"sizes": {
"50": {
"date": "2016-03-22 13:05:59+0000",
"policyVersion": 1,
"status": "PASSED"
}
}
}
}
},
{
"id": "/images/image2.png",
"url": "http://www.example.comimages/image2.png",
"policies": {
"watermark": {
"sizes": {
"200": {
"date": "2016-03-23 13:05:59+0000",
"policyVersion": 1,
"status": "PASSED"
}
}
}
}
}
]
}
ImageCollection members
Member | Type | Required | Description |
---|---|---|---|
ImageCollection : Provides data about the types of items included in an image collection. |
|||
items |
Object | ✓ | Array of Image, Video, and Spin360 objects. |
version |
Number | ✓ | The version of the collection. |
Video
Information about a video that’s included in the collection.
Download schema:
video.json
Video members
Member | Type | Required | Description |
---|---|---|---|
Video : Information about a video that’s included in the collection. |
|||
mime |
String | ✓ | The MIME type of the video. |
poster |
String | ✓ | The URL of the image to display while the video is downloading. |
tags |
Array | ○ | Additional keywords to describe the object. |
type |
Enumeration | ✓ | The type of item in the collection, video in this case. |
url |
String | ✓ | The URL of the video. |
Spin360
Information about a 360 degree image spin that’s included in the collection.
Download schema:
spin-360.json
Spin360 members
Member | Type | Required | Description |
---|---|---|---|
Spin360 : Information about a 360 degree image spin that’s included in the collection. |
|||
tags |
Array | ○ | Additional keywords to describe the object. |
type |
Enumeration | ✓ | The type of item in the collection, spin360 in this case. |
urls |
Array | ✓ | The URL of the 360 spin file. |
History
Provides date, user, and version information for your policies.
Download schema:
get-policy-history.json
Sample GET response:
{
"itemKind": "POLICIESLOG",
"totalItems": 1,
"items": [
{
"id": "thumbnail_policy",
"dateCreated": "2015-06-09 15:41:37+0000",
"policy": "{\"id\":\"grayscale\",\"transformations\":[{\"transformation\":\"Grayscale\"}],\"resolutions\":{\"widths\":[500]},\"currentVersion\":1}",
"action": "UPSERT",
"user": "jsmith"
}
]
}
History members
Member | Type | Required | Description |
---|---|---|---|
History : Provides date, user, and version information for your policies. |
|||
itemKind |
Enumeration | ○ | The type of policy, in this case the POLICIESLOG . |
items |
History. |
○ | An array showing a history of your policy changes. |
totalItems |
Integer | ○ | The total number of policies returned. |
History.items[] : An array showing a history of your policy changes. |
|||
action |
Enumeration | ○ | The action logged, either UPSERT or DELETE . |
dateCreated |
String | ○ | Date of the log entry in ISO 8601 extended notation format. |
id |
String | ○ | The ID of the policy. |
policy |
String | ○ | The policy’s state as a result of the change, represented as a JSON string. |
user |
String | ○ | The user who made the modification. |
version |
Integer | ○ | The version of the policy. |
Acknowledgement
The type of operation performed on an Image and Video Manager resource.
Download schema:
operation-performed.json
Sample DELETE response:
{
"operationPerformed": "DELETED",
"description": "Policy thumbnail_policy deleted.",
"id": "thumbnail_policy"
}
Acknowledgement members
Member | Type | Required | Description |
---|---|---|---|
Acknowledgement : The type of operation performed on an Image and Video Manager resource. |
|||
description |
String | ○ | The description of the resource. |
id |
String | ○ | Unique identifier for a resource. |
operation |
Enumeration | ○ | The action performed on the resource, either CREATED , UPDATED , DELETED , or CANCELLED . |
Transformation
Transformations are tools that let you change images. For example, you can rotate an image, adjust its color, and add a watermark to it. Depending on the image’s size or orientation, you can apply different transformations. For example, if the image is either portrait, landscape, or square, you can crop it to an exact width and height. You can include many transformations within a policy. See Transformation types for available object types.
Append
Places a specified image
beside the source image. The API places the image
on a major dimension, then aligns it on the minor dimension. Transparent pixels fill any area not covered by either image.
Download schema:
append.json
Sample that places an image horizontally at the top-right of the source image:
{
"transformation": "Append",
"gravity": "NorthEast",
"gravityPriority": "horizontal",
"preserveMinorDimension": false,
"image": {
"url": "https://www.example.com/someImage.jpg"
}
}
Append members
Member | Type | Required | Description |
---|---|---|---|
Append : Places a specified image beside the source image. The API places the image on a major dimension, then aligns it on the minor dimension. Transparent pixels fill any area not covered by either image. |
|||
gravity |
Object, Enumeration | ○ | Specifies where to place the image relative to the source image. The available values represent the eight cardinal directions (North , South , East , West , NorthEast , NorthWest , SouthEast , SouthWest ) and a Center by default. Allows Variable substitution. |
gravityPriority |
Object, Enumeration | ○ | Determines the exact placement of the image when gravity is Center or a diagonal. The value is either horizontal or vertical . Use horizontal to append an image east or west of the source image. This aligns the image on the vertical gravity component, placing Center gravity east. Use vertical to append an image north or south of the source image. This aligns the image on the horizontal gravity component, placing Center gravity south. Allows Variable substitution. |
image |
Object | ○ | The image type, either a BoxImageType, TextImageType, or UrlImageType. |
preserve |
Object, Boolean | ○ | Whether to preserve the source image’s minor dimension, false by default. The minor dimension is the dimension opposite the dimension that the appending image is placed. For example, the dimensions of the source image are 100 × 100 pixels. The dimensions of the appending image are 50 × 150 pixels. The gravity is set to East . This makes the major dimension horizontal and the source image’s minor dimension vertical. To preserve the source image’s minor dimension at 100 pixels, the preserveMinorDimension is set to true . As a result of the append, the major dimension expanded with the appended image to 150 pixels. The source image’s minor dimension was maintained at 100 pixels. The total combined dimension of the image is 150 × 100 pixels. Allows Variable substitution. |
transformation |
Enumeration | ✓ | Identifies this type of transformation, Append in this case. |
BackgroundColor
Places a transparent image on a set background color. Color is specified in the typical CSS hexadecimal format.
Download schema:
background-color.json
Sample that changes background color:
{
"transformation": "BackgroundColor",
"color": "#ff00ff"
}
BackgroundColor members
Member | Type | Required | Description |
---|---|---|---|
BackgroundColor : Places a transparent image on a set background color. Color is specified in the typical CSS hexadecimal format. |
|||
color |
Object, String | ✓ | The hexadecimal CSS color value for the background. Allows Variable substitution. |
transformation |
Enumeration | ✓ | Identifies this type of transformation, BackgroundColor in this case. |
Blur
Applies a Gaussian blur to the image.
Download schema:
blur.json
Blur members
Member | Type | Required | Description |
---|---|---|---|
Blur : Applies a Gaussian blur to the image. |
|||
sigma |
Object, Number | ○ | The number of pixels to scatter the original pixel by to create the blur effect. Resulting images may be larger than the original as pixels at the edge of the image might scatter outside the image’s original dimensions. Allows Variable substitution. |
transformation |
Enumeration | ✓ | Identifies this type of transformation, Blur in this case. |
Composite
Applies another image to the source image, either as an overlay or an underlay. The image that’s underneath is visible in areas that are beyond the edges of the top image or that are less than 100% opaque. A common use of an overlay composite is to add a watermark.
Download schema:
composite.json
Sample that places one image on top of another:
{
"transformation": "Composite",
"xPosition": 0,
"yPosition": 0,
"gravity": "NorthWest",
"placement": "Over",
"scale": 0.5,
"scaleDimension": "width",
"image": [
{
"id": "/house/image1.jpg",
"url": "http://www.example.com/house/image1.jpg",
"policies": {
".auto": {
"sizes": {
"50": {
"date": "2016-03-22 13:05:59+0000",
"policyVersion": 1,
"status": "PASSED"
}
}
}
}
}
]
}
Composite members
Member | Type | Required | Description |
---|---|---|---|
Composite : Applies another image to the source image, either as an overlay or an underlay. The image that’s underneath is visible in areas that are beyond the edges of the top image or that are less than 100% opaque. A common use of an overlay composite is to add a watermark. |
|||
gravity |
Object, Enumeration | ○ | The placement or region within an image. The available values represent the eight cardinal directions (North , South , East , West , NorthEast , NorthWest , SouthEast , SouthWest ) and a Center by default. Allows Variable substitution. |
image |
Composite. |
✓ | The image you want to apply to the source image. |
placement |
Object, Enumeration | ○ | Where to place the specified image, either Over or Under the existing image. The default is Over . Allows Variable substitution. |
scale |
Object, Number | ○ | A multiplier to resize the applied image relative to the source image and preserve aspect ratio, 1 by default. Set the scaleDimension to calculate the scale from the source image’s width or height. Allows Variable substitution. |
scaleDimension |
Object, Enumeration | ○ | The dimension, either width or height , of the source image to scale. Allows Variable substitution. |
transformation |
Enumeration | ✓ | Identifies this type of transformation, Composite in this case. |
xPosition |
Object, Integer | ○ | The x-axis position of the image to apply. Allows Variable substitution. |
yPosition |
Object, Integer | ○ | The y-axis position of the image to apply. Allows Variable substitution. |
Composite.image : The image you want to apply to the source image. |
|||
transformation |
Transformation | ○ | If desired, the transformation to perform on the incoming image before adding it to the source image. |
url |
Object, String | ✓ | The URL of the image to apply to the source image. Allows Variable substitution. |
Compound
An ordered combination of transformations to perform. Use to represent a sequence of transformations as a single transformation.
Download schema:
compound.json
Sample that combines a sequence of transformations into a single transformation:
{
"transformation": "Compound",
"transformations": [
{
"color": "#ff00ff",
"transformation": "BackgroundColor"
},
{
"colours": 256,
"transformation": "MaxColors"
}
]
}
Compound members
Member | Type | Required | Description |
---|---|---|---|
Compound : An ordered combination of transformations to perform. Use to represent a sequence of transformations as a single transformation. |
|||
transformation |
Enumeration | ✓ | Identifies this type of transformation, Compound in this case. |
transformations |
Transformation array | ○ | Lists transformations to perform. Valid transformation types are BackgroundColor, Composite, Crop, MaxColors, Resize, Rotate, and Scale. |
Contrast
Adjusts both the contrast and brightness of an image.
Download schema:
contrast.json
Sample that adjusts both the contrast and brightness of an image:
{
"transformation": "Contrast",
"contrast": 0.2,
"brightness": -0.3
}
Contrast members
Member | Type | Required | Description |
---|---|---|---|
Contrast : Adjusts both the contrast and brightness of an image. |
|||
brightness |
Object, Number | ○ | Adjusts the brightness of the image. Positive values increase brightness and negative values decrease brightness. A value of 1 produces a white image. A value of -1 produces a black image. The default value is 0 , which leaves the image unchanged. The acceptable value range is -1.0 to 1.0 . Values outside of the acceptable range clamp to this range. Allows Variable substitution. |
contrast |
Object, Number | ○ | Adjusts the contrast of the image. Expressed as a range from -1 to 1 , positive values increase contrast, negative values decrease it, while 0 leaves the image unchanged. Values outside of the -1 to 1 range clamp to this range. Allows Variable substitution. |
sloppy |
Object, Boolean | ○ | Whether to sacrifice image fidelity for faster performance, true by default. Allows Variable substitution. |
transformation |
Enumeration | ✓ | Identifies this type of transformation, Contrast in this case. |
Crop
Crops an image.
Download schema:
crop.json
Sample that crops an image:
{
"transformation": "Crop",
"width": 100,
"height": 100,
"xPosition": 0,
"yPosition": 0,
"gravity": "NorthWest"
}
Crop members
Member | Type | Required | Description |
---|---|---|---|
Crop : Crops an image. |
|||
allowExpansion |
Object, Boolean | ○ | If cropping an area outside of the existing canvas, expands the image canvas. Allows Variable substitution. |
gravity |
Object, Enumeration | ○ | The placement or region within an image. The available values represent the eight cardinal directions (North , South , East , West , NorthEast , NorthWest , SouthEast , SouthWest ) and a Center by default. Allows Variable substitution. |
height |
Object, Integer | ✓ | The number of pixels to crop along the y-axis. Allows Variable substitution. |
transformation |
Enumeration | ✓ | Identifies this type of transformation, Crop in this case. |
width |
Object, Integer | ✓ | The number of pixels to crop along the x-axis. Allows Variable substitution. |
xPosition |
Object, Integer | ○ | The x-axis position of the image to crop from. Allows Variable substitution. |
yPosition |
Object, Integer | ○ | The y-axis position of the image to crop from. Allows Variable substitution. |
FaceCrop
Applies a method to detect faces in the source image and applies the rectangular crop on either the biggest
face or all
of the faces detected. Image and Video Manager tries to preserve faces in the image instead of using specified crop coordinates.
Download schema:
face-crop.json
Sample that detects a face in an image, then crops the image to position the face in the center of the image:
{
"transformation": "FaceCrop",
"focus": "allFaces",
"style": "zoom",
"width": 400,
"height": 400,
"padding": 0.2,
"gravity": "North",
"failGravity": "Center"
}
FaceCrop members
Member | Type | Required | Description |
---|---|---|---|
FaceCrop : Applies a method to detect faces in the source image and applies the rectangular crop on either the biggest face or all of the faces detected. Image and Video Manager tries to preserve faces in the image instead of using specified crop coordinates. |
|||
algorithm |
Object, Enumeration | ○ | Specifies the type of algorithm used to detect faces in the image, either cascade for the cascade classifier algorithm or dnn for the deep neural network algorithm, cascade by default. Allows Variable substitution. |
confidence |
Object, Number | ○ | With algorithm set to dnn , specifies the minimum confidence needed to detect faces in the image. Values range from 0 to 1 for increased confidence, and possibly fewer faces detected. Allows Variable substitution. |
debug |
Object, Boolean | ○ | Outlines the faces detected, the specified point of interest, and crop area of the source image, false by default. Use this as an alternative to cropping faces in the image. Allows Variable substitution. |
failGravity |
Object, Enumeration | ○ | If no faces are detected, this specifies the placement and size of the crop area relative to the source image and the specified style value. The available values represent the eight cardinal directions (North , South , East , West , NorthEast , NorthWest , SouthEast , SouthWest ) and a Center by default. Allows Variable substitution. |
focus |
Object, Enumeration | ○ | Distinguishes the faces detected, either biggest or all to place the crop rectangle around the full set of faces, all by default. Allows Variable substitution. |
gravity |
Object, Enumeration | ○ | The placement of the crop area relative to the faces detected plus the padding value. The available values represent the eight cardinal directions (North , South , East , West , NorthEast , NorthWest , SouthEast , SouthWest ) and a Center by default. Allows Variable substitution. |
height |
Object, Integer | ✓ | The height of the output image in pixels relative to the specified style value. Allows Variable substitution. |
padding |
Object, Number | ○ | The padding ratio based on the dimensions of the biggest face detected, 0.5 by default. Larger values increase padding. Allows Variable substitution. |
sloppy |
Object, Boolean | ○ | Whether to sacrifice image fidelity for faster performance, false by default. Allows Variable substitution. |
style |
Object, Enumeration | ○ | Specifies how to crop or scale a crop area for the faces detected in the source image, zoom by default. The output image resizes to the specified width and height values. A value of crop places a raw crop around the faces, relative to the specified gravity value. A value of fill scales the crop area to include as much of the image and faces as possible, relative to the specified width and height values. A value of zoom scales the crop area as small as possible to fit the faces, relative to the specified width and height values. Allows Variable substitution. |
transformation |
Enumeration | ✓ | Identifies this type of transformation, FaceCrop in this case. |
width |
Object, Integer | ✓ | The width of the output image in pixels relative to the specified style value. Allows Variable substitution. |
FeatureCrop
Identifies prominent features of the source image, then crops around as many of these features as possible relative to the specified width
and height
values.
Download schema:
feature-crop.json
Sample that identifies the main features of an image, then crops around those features:
{
"transformation": "FeatureCrop",
"width": 400,
"height": 300,
"featureRadius": 10,
"maxFeatures": 50,
"minFeatureQuality": 0.3,
"style": "zoom",
"padding": 0.1,
"gravity": "Center",
"failGravity": "Center"
}
FeatureCrop members
Member | Type | Required | Description |
---|---|---|---|
FeatureCrop : Identifies prominent features of the source image, then crops around as many of these features as possible relative to the specified width and height values. |
|||
debug |
Object, Boolean | ○ | Outlines the features identified, the specified point of interest, and crop area of the source image, false by default. Use this as an alternative to cropping features in the image. Allows Variable substitution. |
failGravity |
Object, Enumeration | ○ | If no features are identified, this specifies the placement of the crop area relative to the source image and the specified style value. The available values represent the eight cardinal directions (North , South , East , West , NorthEast , NorthWest , SouthEast , SouthWest ) and a Center by default. Allows Variable substitution. |
featureRadius |
Object, Number | ○ | The size in pixels of the important features to search for. If identified, two features never appear closer together than this value, 8.0 by default. Allows Variable substitution. |
gravity |
Object, Enumeration | ○ | The placement of the crop area relative to the features identified plus the specified padding value. The available values represent the eight cardinal directions (North , South , East , West , NorthEast , NorthWest , SouthEast , SouthWest ) and a Center by default. Allows Variable substitution. |
height |
Object, Integer | ✓ | The height in pixels of the output image relative to the specified style value. Allows Variable substitution. |
maxFeatures |
Object, Integer | ○ | The maximum number of features to identify as important features, 32 by default. The strongest features are always chosen. Allows Variable substitution. |
min |
Object, Number | ○ | Determines the minimum quality level of the feature identified. To consider a feature important, the feature needs to surpass this value. Image and Video Manager measures quality on a scale from 0 for the lowest quality to 1 for the highest quality, .1 by default. Allows Variable substitution. |
padding |
Object, Number | ○ | Adds space around the region of interest. The amount of padding added is directly related to the size of the bounding box of the selected features. Specifically, the region of interest is expanded in all directions by the largest dimension of the bounding box of the selected features multiplied by this value. Allows Variable substitution. |
sloppy |
Object, Boolean | ○ | Whether to sacrifice image fidelity for faster performance, false by default. Allows Variable substitution. |
style |
Object, Enumeration | ○ | Specifies how to crop or scale a crop area for the features identified in the source image, fill by default. The output image resizes to the specified width and height values. A value of crop performs a raw crop around the features, relative to the specified gravity value. A value of fill scales the crop area to include as much of the image and features as possible, relative to the specified width and height values. A value of zoom scales the crop area as small as possible to fit the features, relative to the specified width and height values. Allows Variable substitution. |
transformation |
Enumeration | ✓ | Identifies this type of transformation, FeatureCrop in this case. |
width |
Object, Integer | ✓ | The width in pixels of the output image relative to the specified style value. Allows Variable substitution. |
FitAndFill
Use aspect fitting to resize an image to the exact dimensions specified. This transformation then uses aspect fill on any remaining areas of the image.
Download schema:
fit-and-fill.json
FitAndFill members
Member | Type | Required | Description |
---|---|---|---|
FitAndFill : Use aspect fitting to resize an image to the exact dimensions specified. This transformation then uses aspect fill on any remaining areas of the image. |
|||
fill |
Transformation | ○ | The fill settings to use on the image. |
height |
Object, Integer | ✓ | The height value of the resized image. Allows Variable substitution. |
transformation |
Enumeration | ✓ | Identifies this type of transformation, FitAndFill in this case. |
width |
Object, Integer | ✓ | The width value of the resized image. Allows Variable substitution. |
Goop
Distorts an image by randomly repositioning a set of control points along a specified grid. The transformed image appears goopy. Adjust the density of the grid and the degree of randomity. You can use this transformation to create watermarks for use in security.
Download schema:
goop.json
Sample that distorts an image.:
{
"transformation": "Goop",
"chaos": 0.4,
"density": 3,
"seed": 31415926
}
Goop members
Member | Type | Required | Description |
---|---|---|---|
Goop : Distorts an image by randomly repositioning a set of control points along a specified grid. The transformed image appears goopy. Adjust the density of the grid and the degree of randomity. You can use this transformation to create watermarks for use in security. |
|||
chaos |
Object, Number | ○ | Specifies the greatest distance control points may move from their original position. A value of 1.0 shifts control points over as far as the next one in the original grid. A value of 0.0 leaves the image unchanged. Values under 0.5 work better for subtle distortions, otherwise control points may pass each other and cause a twisting effect. Allows Variable substitution. |
density |
Object, Integer | ○ | Controls the density of control points used to distort the image. The largest dimension of the input image is divided up to fit this number of control points. A grid of points is extended on the smaller dimension such that each row and column of control points is equidistant from each adjacent row or column. This parameter strongly affects transformation performance. Be careful choosing values above the default if you expect to transform medium to large size images. |
power |
Object, Number | ○ | By default, the distortion algorithm relies on inverse squares to calculate distance but this allows you to change the exponent. You shouldn’t need to vary the default value of 2.0 . |
seed |
Object, Integer | ○ | Specifies your own seed value as an alternative to the default, which is subject to variability. This allows for reproducible and deterministic distortions. If all parameters are kept equal and a constant seed is used, Goop distorts an input image consistently over many transformations. By default, this value is set to the current Epoch Time measured in milliseconds, which provides inconsistent transformation output. Allows Variable substitution. |
sloppy |
Object, Boolean | ○ | Whether to sacrifice image fidelity for faster performance, false by default. Allows Variable substitution. |
transformation |
Enumeration | ✓ | Identifies this type of transformation, Goop in this case. |
Grayscale
Restricts image color to shades of gray only.
Download schema:
grayscale.json
Sample that restricts image color to shades of gray only:
{
"transformation": "Grayscale",
"type": "Rec601Luma"
}
Grayscale members
Member | Type | Required | Description |
---|---|---|---|
Grayscale : Restricts image color to shades of gray only. |
|||
transformation |
Enumeration | ✓ | Identifies this type of transformation, Grayscale in this case. |
type |
Object, Enumeration | ○ | The algorithm used to transform colors to grays, either Brightness , Lightness , Rec601 , or the default Rec709 . Allows Variable substitution. |
HLS
Adjusts the hue, saturation, and lightness (HSL) of an image. Hue is the number of degrees that colors rotate around the color wheel. Saturation is a multiplier to increase or decrease color saturation. Lightness is a multiplier to increase or decrease the lightness of an image. Other transformations can also affect color, such as Grayscale
and MaxColors
. If you’re using more than one, consider the order to apply them for the desired results.
Download schema:
hsl.json
Sample that alters the hue, saturation, and lightness of an image:
{
"transformation": "HSL",
"hue": 0.0,
"saturation": 1.0,
"lightness": 1.0
}
HLS members
Member | Type | Required | Description |
---|---|---|---|
HLS : Adjusts the hue, saturation, and lightness (HSL) of an image. Hue is the number of degrees that colors rotate around the color wheel. Saturation is a multiplier to increase or decrease color saturation. Lightness is a multiplier to increase or decrease the lightness of an image. Other transformations can also affect color, such as Grayscale and MaxColors . If you’re using more than one, consider the order to apply them for the desired results. |
|||
hue |
Object, Number | ○ | The number of degrees to rotate colors around the color wheel, 0 by default. Allows Variable substitution. |
lightness |
Object, Number | ○ | A multiplier to adjust the lightness of colors in the image. Note that lightness is distinct from brightness. For example, reducing the lightness of a light green might give you a lime green whereas reducing the brightness of a light green might give you a darker shade of the same green. Values less than 1.0 decrease the lightness of colors in the image. Values greater than 1.0 increase the lightness of colors in the image. Allows Variable substitution. |
saturation |
Object, Number | ○ | A multiplier to adjust the saturation of colors in the image. Values less than 1.0 decrease saturation and values greater than 1.0 increase the saturation. A value of 0.0 removes all color from the image. Allows Variable substitution. |
transformation |
Enumeration | ✓ | Identifies this type of transformation, HSL in this case. |
HSV
Identical to HSL except it replaces lightness
with value
. For example, if you reduce the lightness
of a light green, almost white, image, the color turns a vibrant green. Reducing the value
turns the image a darker color, close to grey. This happens because the original image color is very close to white.
Download schema:
hsv.json
HSV members
Member | Type | Required | Description |
---|---|---|---|
HSV : Identical to HSL except it replaces lightness with value . For example, if you reduce the lightness of a light green, almost white, image, the color turns a vibrant green. Reducing the value turns the image a darker color, close to grey. This happens because the original image color is very close to white. |
|||
hue |
Object, Number | ○ | The number of degrees to rotate colors around the color wheel, 0.0 by default. Allows Variable substitution. |
saturation |
Object, Number | ○ | A multiplier to adjust the saturation of colors in the image. Values less than 1.0 decrease saturation and values greater than 1.0 increase the saturation. A value of 0.0 removes all color from the image. Allows Variable substitution. |
transformation |
Enumeration | ✓ | Identifies this type of transformation, HSV in this case. |
value |
Object, Number | ○ | A multiplier to adjust the lightness or darkness of the image’s base color. Values less than 1.0 decrease the base colors in the image, making them appear darker. Values greater than 1.0 increase the base colors in the image, making them appear lighter. Allows Variable substitution. |
MaxColors
Set the maximum number of colors in the image’s palette. Reducing the number of colors in an image can help to reduce file size.
Download schema:
max-colors.json
Sample that reduces the number of unique colors in an image:
{
"transformation": "MaxColors",
"colors": 256
}
MaxColors members
Member | Type | Required | Description |
---|---|---|---|
MaxColors : Set the maximum number of colors in the image’s palette. Reducing the number of colors in an image can help to reduce file size. |
|||
colours |
Object, Integer | ○ | The value representing the maximum number of colors to use with the source image. Allows Variable substitution. |
transformation |
Enumeration | ✓ | Identifies this type of transformation, MaxColors in this case. |
Mirror
Flips an image horizontally, vertically, or both.
Download schema:
mirror.json
Sample that flips an image horizontally and vertically:
{
"transformation": "Mirror",
"horizontal": true,
"vertical": true
}
Mirror members
Member | Type | Required | Description |
---|---|---|---|
Mirror : Flips an image horizontally, vertically, or both. |
|||
horizontal |
Object, Boolean | ○ | Flips the image horizontally. Allows Variable substitution. |
transformation |
Enumeration | ✓ | Identifies this type of transformation, Mirror in this case. |
vertical |
Object, Boolean | ○ | Flips the image vertically. Allows Variable substitution. |
Opacity
Adjusts the level of transparency of an image. Use this transformation to make an image more or less transparent.
Download schema:
opacity.json
Sample that affects the transparency of an image:
{
"transformation": "Opacity",
"opacity": 0.5
}
Opacity members
Member | Type | Required | Description |
---|---|---|---|
Opacity : Adjusts the level of transparency of an image. Use this transformation to make an image more or less transparent. |
|||
opacity |
Object, Number | ✓ | Represents alpha values on a scale of 0 to 1 . Values below 1 increase transparency, and 0 is invisible. For images that have some transparency, values above 1 increase the opacity of the transparent portions. Allows Variable substitution. |
transformation |
Enumeration | ✓ | Identifies this type of transformation, Opacity in this case. |
RegionOfInterestCrop
Crops to a region around a specified area of interest relative to the specified width
and height
values.
Download schema:
region-of-interest-crop.json
Sample that captures a specific area of the image:
{
"transformation": "RegionOfInterestCrop",
"width": 500,
"height": 500,
"style": "zoom",
"gravity": "North",
"regionOfInterest": {
"radius": 20,
"center": [
100,
175
]
}
}
RegionOfInterestCrop members
Member | Type | Required | Description |
---|---|---|---|
RegionOfInterestCrop : Crops to a region around a specified area of interest relative to the specified width and height values. |
|||
gravity |
Object, Enumeration | ○ | The placement of the crop area relative to a specified area of interest. The available values represent the eight cardinal directions (North , South , East , West , NorthEast , NorthWest , SouthEast , SouthWest ) and a Center by default. Allows Variable substitution. |
height |
Object, Integer | ✓ | The height in pixels of the output image relative to the specified style value. Allows Variable substitution. |
regionOfInterest |
Circle |
✓ | The shape that determines how to crop the source image. |
sloppy |
Object, Boolean | ○ | Whether to sacrifice image fidelity for faster performance, false by default. Allows Variable substitution. |
style |
Object, Enumeration | ○ | Specifies how to crop or scale a crop area for the specified area of interest in the source image, zoom by default. The output image resizes to the specified width and height values. A value of crop places raw crop around the point of interest, relative to the specified gravity value. A value of fill scales the crop area to include as much of the image and point of interest as possible, relative to the specified width and height values. A value of zoom scales the crop area as small as possible to fit the point of interest, relative to the specified width and height values. Allows Variable substitution. |
transformation |
Enumeration | ✓ | Identifies this type of transformation, RegionOfInterestCrop in this case. |
width |
Object, Integer | ✓ | The width in pixels of the output image relative to the specified style value. Allows Variable substitution. |
RelativeCrop
Shrinks or expands an image relative to the image’s specified dimensions. Image and Video Manager fills the expanded areas with transparency. Positive values shrink the side, while negative values expand it.
Download schema:
relative-crop.json
Sample that expands the four sides of an image:
{
"transformation": "RelativeCrop",
"north": 10,
"east": 15,
"south": 10,
"west": 15
}
RelativeCrop members
Member | Type | Required | Description |
---|---|---|---|
RelativeCrop : Shrinks or expands an image relative to the image’s specified dimensions. Image and Video Manager fills the expanded areas with transparency. Positive values shrink the side, while negative values expand it. |
|||
east |
Object, Integer | ○ | The number of pixels to shrink or expand the right side of the image. Allows Variable substitution. |
north |
Object, Integer | ○ | The number of pixels to shrink or expand the top side of the image. Allows Variable substitution. |
south |
Object, Integer | ○ | The number of pixels to shrink or expand the bottom side of the image. Allows Variable substitution. |
transformation |
Enumeration | ✓ | Identifies this type of transformation, RelativeCrop in this case. |
west |
Object, Integer | ○ | The number of pixels to shrink or expand the left side of the image. Allows Variable substitution. |
Resize
Resizes an image to a particular, absolute dimension. If you don’t enter a width
or a height
, the image is resized with the fit
aspect preservation mode, which selects a value for the missing dimension that preserves the image’s aspect.
Download schema:
resize.json
Sample that resizes an image to a particular, absolute dimension:
{
"transformation": "Resize",
"width": 100,
"height": 100,
"aspect": "fit",
"type": "normal"
}
Resize members
Member | Type | Required | Description |
---|---|---|---|
Resize : Resizes an image to a particular, absolute dimension. If you don’t enter a width or a height , the image is resized with the fit aspect preservation mode, which selects a value for the missing dimension that preserves the image’s aspect. |
|||
aspect |
Object, Enumeration | ○ | Preserves the aspect ratio. Select fit to make the image fit entirely within the selected width and height. When using fit , the resulting image has the largest possible size for the specified dimensions. Select fill to size the image so it both completely fills the dimensions and has the smallest possible file size. Otherwise ignore changes the original aspect ratio to fit within an arbitrarily shaped rectangle. Allows Variable substitution. |
height |
Object, Integer | ○ | The height to resize the source image to. Allows Variable substitution. |
transformation |
Enumeration | ✓ | Identifies this type of transformation, Resize in this case. |
type |
Object, Enumeration | ○ | Sets constraints for the image resize. Select normal to resize in all cases, either increasing or decreasing the dimensions. Select downsize to ignore this transformation if the result would be larger than the original. Select upsize to ignore this transformation if the result would be smaller. Allows Variable substitution. |
width |
Object, Integer | ○ | The width to resize the source image to. Allows Variable substitution. |
Rotate
Rotate the image around its center by indicating the degrees of rotation.
Download schema:
rotate.json
Sample that rotates an image clockwise some arbitrary number of degrees:
{
"transformation": "Rotate",
"degrees": 45.3
}
Rotate members
Member | Type | Required | Description |
---|---|---|---|
Rotate : Rotate the image around its center by indicating the degrees of rotation. |
|||
degrees |
Object, Number | ✓ | The value to rotate the image by. Positive values rotate clockwise, while negative values rotate counter-clockwise. Allows Variable substitution. |
transformation |
Enumeration | ✓ | Identifies this type of transformation, Rotate in this case. |
Scale
Changes the image’s size to different dimensions relative to its starting size.
Download schema:
scale.json
Sample that resizes an image to particular dimensions relative to the input image:
{
"transformation": "Scale",
"width": 0.5,
"height": 0.5
}
Scale members
Member | Type | Required | Description |
---|---|---|---|
Scale : Changes the image’s size to different dimensions relative to its starting size. |
|||
height |
Object, Number | ✓ | Scaling factor for the input height to determine the output height of the image, where values between 0 and 1 decrease size. Image dimensions need to be non-zero positive numbers. Allows Variable substitution. |
transformation |
Enumeration | ✓ | Identifies this type of transformation, Scale in this case. |
width |
Object, Number | ✓ | Scaling factor for the input width to determine the output width of the image, where 1 leaves the width unchanged. Values greater than 1 increase the image size. Image dimensions need to be non-zero positive numbers. Allows Variable substitution. |
Shear
Slants an image into a parallelogram, as a percent of the starting dimension as represented in decimal format. You need to specify at least one axis property. Transparent pixels fill empty areas around the sheared image as needed, so it’s often useful to use a backgroundColor
transformation for these areas.
Download schema:
shear.json
Sample that slants an image into a parallelogram, as a portion of starting dimension:
{
"transformation": "Shear",
"xShear": 0.2,
"yShear": 0.1
}
Shear members
Member | Type | Required | Description |
---|---|---|---|
Shear : Slants an image into a parallelogram, as a percent of the starting dimension as represented in decimal format. You need to specify at least one axis property. Transparent pixels fill empty areas around the sheared image as needed, so it’s often useful to use a backgroundColor transformation for these areas. |
|||
transformation |
Enumeration | ✓ | Identifies this type of transformation, Shear in this case. |
xShear |
Object, Integer | ○ | The amount to shear along the x-axis, measured in multiples of the image’s width. Use a decimal value from –5 to 5. The transformation fails if the range is exceeded. Allows Variable substitution. |
yShear |
Object, Integer | ○ | The amount to shear along the y-axis, measured in multiples of the image’s height. Use a decimal value from –5 to 5. Allows Variable substitution. |
Trim
Automatically crops uniform backgrounds from the edges of an image.
Download schema:
trim.json
Trim members
Member | Type | Required | Description |
---|---|---|---|
Trim : Automatically crops uniform backgrounds from the edges of an image. |
|||
fuzz |
Object, Number | ○ | The fuzz tolerance of the trim, a value between 0 and 1 that determines the acceptable amount of background variation before trimming stops. Allows Variable substitution. |
padding |
Object, Integer | ○ | The amount of padding in pixels to add to the trimmed image. Allows Variable substitution. |
transformation |
Enumeration | ✓ | Identifies this type of transformation, Trim in this case. |
UnsharpMask
Emphasizes edges and details in source images without distorting the colors. Although this effect is often referred to as sharpening an image, it actually creates a blurred, inverted copy of the image known as an unsharp mask. Image and Video Manager combines the unsharp mask with the source image to create an image perceived as clearer.
Download schema:
unsharp-mask.json
UnsharpMask members
Member | Type | Required | Description |
---|---|---|---|
UnsharpMask : Emphasizes edges and details in source images without distorting the colors. Although this effect is often referred to as sharpening an image, it actually creates a blurred, inverted copy of the image known as an unsharp mask. Image and Video Manager combines the unsharp mask with the source image to create an image perceived as clearer. |
|||
gain |
Object, Number | ○ | The amount of emphasis to add to edges and details. A value of 0 adds no emphasis. A value of 1.0 adds a common, clearly visible amount of emphasis. Values greater than 1.0 are allowed but may be considered more extreme or artistic. |
sigma |
Object, Number | ○ | The standard deviation of the Gaussian distribution used in the in unsharp mask, measured in pixels, 1.0 by default. High values emphasize large details and low values emphasize small details. Allows Variable substitution. |
threshold |
Object, Number | ○ | Adjusts how strong a detail needs to be to have any emphasis applied. A minimum value of 0 means the entire image gets some emphasis applied. A maximum value of 1 means none of the image will have emphasis applied no matter how strong its details are. You’ll probably never need to change this from the default value of 0.05 . Allows Variable substitution. |
transformation |
Enumeration | ✓ | Identifies this type of transformation, UnsharpMask in this case. |
IfDimension
Chooses a transformation depending on the dimensions of the source image. You need to select a dimension for comparison, which is either width
and height
or both
.
Download schema:
if-dimension.json
IfDimension members
Member | Type | Required | Description |
---|---|---|---|
IfDimension : Chooses a transformation depending on the dimensions of the source image. You need to select a dimension for comparison, which is either width and height or both . |
|||
default |
Transformation | ○ | A no-op transformation, by default. |
dimension |
Object, Enumeration | ○ | The dimension to use to select the transformation, either height , width , or both . Allows Variable substitution. |
equal |
Transformation | ○ | The transformation performed only if the source image’s dimension is equal to the value listed. |
greaterThan |
Transformation | ○ | The transformation performed if the source image’s dimension is greater than the value listed. |
lessThan |
Transformation | ○ | The transformation performed if the source image’s dimension is less than the value listed. |
transformation |
Enumeration | ✓ | Identifies this type of transformation, IfDimension in this case. |
value |
Object, Integer | ✓ | The value to compare against the source image dimension. Allows Variable substitution. |
IfOrientation
Chooses a transformation depending on the orientation of the source image.
Download schema:
if-orientation.json
IfOrientation members
Member | Type | Required | Description |
---|---|---|---|
IfOrientation : Chooses a transformation depending on the orientation of the source image. |
|||
default |
Transformation | ○ | A no-op transformation, by default. |
landscape |
Transformation | ○ | The transformation performed if the source image uses landscape orientation. |
portrait |
Transformation | ○ | The transformation performed if the source image uses portrait orientation. |
square |
Transformation | ○ | The transformation performed if the source image uses a square orientation. |
transformation |
Enumeration | ✓ | Identifies this type of transformation, IfOrientation in this case. |
BoxImageType
A rectangular box, with a specified color and applied transformation.
Download schema:
box-image-type.json
Sample that represents a box image:
{
"type": "Box",
"color": "#81c119",
"width": 200,
"height": 150
}
BoxImageType members
Member | Type | Required | Description |
---|---|---|---|
BoxImageType : A rectangular box, with a specified color and applied transformation. |
|||
color |
Object, String | ○ | The fill color of the box, not the edge of the box. The API supports hexadecimal representation and CSS hexadecimal color values. Allows Variable substitution. |
height |
Object, Integer | ○ | The height of the box in pixels. Allows Variable substitution. |
transformation |
Transformation | ○ | The Transformation type applied to the box. For example, you can Rotate the box. |
type |
Enumeration | ✓ | Identifies the type of image, Box in this case. |
width |
Object, Integer | ○ | The width of the box in pixels. Allows Variable substitution. |
TextImageType
A snippet of text. Defines font family and size, fill color, and outline stroke width and color.
Download schema:
text-image-type.json
Sample that renders a string of text to an image:
{
"type": "Text",
"text": "Sample text to make an image from!",
"typeface": "https://www.example.com/fonts/someFont.woff",
"size": 50,
"fill": "#000",
"stroke": "#fff",
"strokeSize": 1.5
}
TextImageType members
Member | Type | Required | Description |
---|---|---|---|
TextImageType : A snippet of text. Defines font family and size, fill color, and outline stroke width and color. |
|||
fill |
Object, String | ○ | The main fill color of the text. Allows Variable substitution. |
size |
Object, Number | ○ | The size in pixels to render the text. Allows Variable substitution. |
stroke |
Object, String | ○ | The color for the outline of the text. Allows Variable substitution. |
strokeSize |
Object, Number | ○ | The thickness in points for the outline of the text. Allows Variable substitution. |
text |
Object, String | ✓ | The line of text to render. To format center-justifying text blocks, include \n sequences where you want lines to break. To search for these newlines in query parameter values, specify the URL-encoded %0A sequence. Allows Variable substitution. |
transformation |
Transformation | ○ | The Transformation type applied to the text. For example, you can Rotate the text. |
type |
Enumeration | ✓ | Identifies the type of image, Text in this case. |
typeface |
Object, String | ○ | The font family to apply to the text image. This may be a URL to a TrueType or WOFF (v1) typeface, or a string that refers to one of the standard built-in browser fonts. Allows Variable substitution. |
UrlImageType
An image loaded from a URL.
Download schema:
url-image-type.json
Sample that specifies an image from a URL:
{
"type": "URL",
"url": "https://www.example.com/someImage.jpg"
}
UrlImageType members
Member | Type | Required | Description |
---|---|---|---|
UrlImageType : An image loaded from a URL. |
|||
type |
Enumeration | ○ | Identifies the type of image, URL in this case. |
url |
Object, String | ✓ | The URL of the image. For details on supported image format types and several transformations, see Test images on-demand. Allows Variable substitution. |
CircleShapeType
Defines a circle with a specified radius
from its center
point.
Download schema:
circle-shape-type.json
Sample that represents a circle shape:
{
"radius": 5,
"center": [
10,
20
]
}
CircleShapeType members
Member | Type | Required | Description |
---|---|---|---|
CircleShapeType : Defines a circle with a specified radius from its center point. |
|||
center |
Object, String | ✓ | The point of the center of the circle. Allows Variable substitution. |
radius |
Object, String | ✓ | The radius of the circle measured in pixels. Allows Variable substitution. |
PointShapeType
Defines coordinates for a single point, to help define polygons and rectangles. Each point may be an object with x
and y
members, or a two-element array.
Download schema:
point-shape-type.json
Sample that represents a single point shape:
{
"x": 10,
"y": 20
}
Sample that represents the same data as a two-element array:
[
10,
20
]
PointShapeType members
Member | Type | Required | Description |
---|---|---|---|
PointShapeType : Defines coordinates for a single point, to help define polygons and rectangles. Each point may be an object with x and y members, or a two-element array. |
|||
x |
Object, Number | ✓ | The horizontal position of the point, measured in pixels. Allows Variable substitution. |
y |
Object, Number | ✓ | The vertical position of the point, measured in pixels. Allows Variable substitution. |
PolygonShapeType
Defines a polygon from a series of connected points.
Download schema:
polygon-shape-type.json
Sample that represents a polygon shape:
{
"points": [
[
0,
0
],
[
10,
10
],
[
20,
0
]
]
}
PolygonShapeType members
Member | Type | Required | Description |
---|---|---|---|
PolygonShapeType : Defines a polygon from a series of connected points. |
|||
points |
Polygon |
○ | Series of PointShapeType objects. The last and first points connect to close the shape automatically. |
PolygonShapeType.points[] : Series of PointShapeType objects. The last and first points connect to close the shape automatically. |
|||
x |
Object, Number | ✓ | The horizontal position of the point, measured in pixels. Allows Variable substitution. |
y |
Object, Number | ✓ | The vertical position of the point, measured in pixels. Allows Variable substitution. |
RectangleShapeType
Defines a rectangle’s width
and height
relative to an anchor
point.
Download schema:
rectangle-shape-type.json
Sample that represents a rectangle shape:
{
"width": 100,
"height": 50,
"anchor": [
10,
20
]
}
RectangleShapeType members
Member | Type | Required | Description |
---|---|---|---|
RectangleShapeType : Defines a rectangle’s width and height relative to an anchor point. |
|||
anchor |
Rectangle |
✓ | PointShapeType that specifies where the rectangle’s top left corner appears relative to that of the image in which it appears. |
height |
Object, Number | ✓ | Extends the rectangle down from the anchor point. Allows Variable substitution. |
width |
Object, Number | ✓ | Extends the rectangle right from the anchor point. Allows Variable substitution. |
RectangleShapeType.anchor : PointShapeType that specifies where the rectangle’s top left corner appears relative to that of the image in which it appears. |
|||
x |
Object, Number | ✓ | The horizontal position of the point, measured in pixels. Allows Variable substitution. |
y |
Object, Number | ✓ | The vertical position of the point, measured in pixels. Allows Variable substitution. |
UnionShapeType
Identifies a combined shape based on a set of other shapes. You can use a full JSON object to represent a union or an array of shapes that describe it.
Download schema:
union-shape-type.json
Sample that represents a shape composed of a RectangleShapeType
and a CircleShapeType
:
{
"shapes": [
{
"width": 200,
"height": 150,
"anchor": [
10,
20
]
},
{
"radius": 50,
"center": [
50,
175
]
}
]
}
Sample that represents the same data as an array:
[
{
"width": 200,
"height": 150,
"anchor": [
10,
20
]
},
{
"radius": 50,
"center": [
50,
175
]
}
]
UnionShapeType members
Member | Type | Required | Description |
---|---|---|---|
UnionShapeType : Identifies a combined shape based on a set of other shapes. You can use a full JSON object to represent a union or an array of shapes that describe it. |
|||
shapes |
Array | ✓ | The full set of component shapes to combine into the unified shape, either CircleShapeType, PolygonShapeType, or RectangleShapeType. |
Variable
References the name of a variable defined by the policy. Use this object to substitute preset values within transformations, or to pass in values dynamically using image URL query parameters.
Download schema:
variable.json
Variable members
Member | Type | Required | Description |
---|---|---|---|
Variable : References the name of a variable defined by the policy. Use this object to substitute preset values within transformations, or to pass in values dynamically using image URL query parameters. |
|||
var |
String | ✓ | Corresponds to the name of the variable declared by the policy, to insert the corresponding value. |
Log
Lists the image or video logs pertaining to transformation tasks in the last 3 days.
Download schema:
get-image-video-logs.json
Sample GET response:
{
"itemKind": "LOGDETAILS",
"totalItems": 2,
"items": [
{
"url": "http://www.customer.com/video.mp4",
"policyId": "videoPolicy",
"size": 854,
"transformationType": "REALTIME",
"status": "PASSED",
"startTime": "2020-01-29 02:45:34",
"completeTime": "2020-01-29 02:45:36"
},
{
"url": "http://www.customer.com/video.mp4",
"policyId": "videoPolicy",
"size": 854,
"transformationType": "OFFLINE",
"status": "PASSED",
"startTime": "2020-01-29 02:45:37",
"completeTime": "2020-01-29 02:45:39",
"pendingTime": "2020-01-29 02:45:36"
}
]
}
Log members
Member | Type | Required | Description |
---|---|---|---|
Log : Lists the image or video logs pertaining to transformation tasks in the last 3 days. |
|||
itemKind |
Enumeration | ✓ | The type of item returned. In this case, the itemKind is LOGDETAILS . |
items |
Log. |
○ | Lists image or video logs pertaining to transformation tasks. |
totalItems |
Integer | ✓ | The total number of logs returned. |
Log.items[] : Lists image or video logs pertaining to transformation tasks. |
|||
actual |
Integer | ○ | The actual value of the metric mentioned in the reason. Present only for error logs. |
completeTime |
String | ✓ | Time when the transformation task was completed. |
pendingTime |
String | ○ | Time when the transformation task was added to queue. Present only for queued offline images or videos. |
policyId |
String | ✓ | The ID of the policy used for the image or video transformation. |
reason |
Enumeration | ○ | Provides a reason for an Image and Video Manager failure. The possible values are: DURATION when the pristine video exceeds the maximum duration of 5 minutes, BYTES when the pristine video exceeds the maximum size of 256 MB, PIXEL when the pristine video pixels exceed 3,686,400 (1920×1920), SAMPLERATE when the pristine video exceeds maximum sample rate of 60 Hz, UNPARSEABLE when the pristine video is not a recognized or supported video format, PRISTINE_TOO_WIDE when the pristine image width exceeds 9999 pixels, PRISTINE_TOO_TALL when the pristine image height exceeds 9999 pixels, PROCESS_FAILED_INTERNALLY when the image or video could not be fetched from the origin or the policy is outdated, or INVALID_POLICY when the policy parameters are invalid. |
size |
Integer | ✓ | The size breakpoint width in pixels, configured in the policy. |
startTime |
String | ✓ | Time when the transformation task execution started. |
status |
Enumeration | ✓ | The status of the transformation task. The status is PASSED when the image or video processing succeeds, FAILED when the image or video processing fails, or QUEUED when the image or video processing is queued for offline processing. |
threshold |
Integer | ○ | The threshold value of metric mentioned in the reason. Present only for error logs. |
transformation |
Enumeration | ✓ | The type of transformation requested. The transformation type is OFFLINE if the image processing is queued for offline processing, or REALTIME if the image processing is performed in realtime. |
url |
String | ✓ | The URL of the image. |
Errors
This section shows you how to handle various kinds of errors the Image and Video Manager API generates, and lists the range of HTTP status codes along with their likely causes.
Error responses
The format of error response objects follows the JSON Problem
Details standard, and uses the
application/api-problem+json
content type.
This example shows an error response when the property name exceeds the maximum length of 30 characters. The type
value may be empty in some cases.
{
"type": "",
"title": "Validation Exception",
"detail": "The value 'abcdefghijklmnopqrstuvwxyz0123456789' of property 'name' is too long. Max length is 30 characters.",
"instance": "PUT - https://imaging.api.akamai.com/imaging/v2/policies/abcdefghijklmnopqrstuvwxyz0123456789",
"httpStatus": 400
}
HTTP status codes
This section lists the full range of response codes the API may generate.
Code | Description |
---|---|
200 | The operation was successful. |
201 | The resource was created successfully. |
400 | Invalid or missing required parameters. |
401 | API authentication failure. See Get started for guidance on how to correctly set up your API hostname token. |
403 | The client is not authorized to invoke the service. See Get started for information on API authorization. |
404 | Couldn’t find the requested resource. |