Creative Assets

https://d3a0d0y2hgofx6.cloudfront.net/openapi/en-us/creative-asset-library/creative-asset-library-openapi.yaml

Advertisers can use creative assets to store, organize and reuse brand content, such as logos and images. Stored content can be used for Amazon Ads and on Amazon shopping pages, so a brand can carry the same material across its campaigns.

class ad_api.api.CreativeAssets(account: str = 'default', marketplace: Marketplaces = Marketplaces.EU, credentials: Dict[str, str] | None = None, proxies: Dict[str, str] | None = None, verify: bool = True, timeout: int | None = None, debug: bool = False, access_token: str | None = None, verify_additional_credentials: bool = True)

Note

The contract is version 3.0 and carries no beta marker: no x-beta, no x-amz-* and no deprecation notice. The page is listed as stable because of that.

### Endpoint map

:header-rows: 1
Path	Method	Version	Answer
`POST /assets/search`	`search_assets`	v3	`200`
`GET /assets`	`get_asset`	v3	`200`
`POST /assets/upload`	`upload_asset`	v3	`200`
`POST /assets/register`	`register_asset`	v3	`200`
`POST /assets/batchRegister`	`batch_register_assets`	v1	`200`
`GET /assets/batchRegister/{requestId}`	`get_batch_register_status`	v3	`200`

batchRegister is the one route on v1 rather than v3. Its request and answer both carry vnd.assetsbatchregisterrequest.v1, which is what the method sends.

### About the media types

The contract names a media type on every route, and the service serves the current version when a call arrives without one. search_assets and get_asset send no Accept and answer 200 all the same. That is not the case everywhere in this package: the Insights routes answer 415 when the version is wrong, so the difference is worth knowing when a call surprises you.

The two batchRegister methods do send their types, because their version does not follow the module’s default.

### The upload, register, batch chain

Assets arrive in three steps, and each one hands the next its input.

:header-rows: 1
Step	Call	Hands over
1	`upload_asset({"fileName": "x.jpeg"})`	a signed S3 `url`, valid for 15 minutes
2	`PUT` the file to that url	the stored file
3	`register_asset({"url": ..., "name": ...})`	the registered `assetId`

batch_register_assets replaces step 3 when there are several files: it takes the list of urls and answers a requestId instead of the assets.

### search_assets body

Every member is optional. An empty object returns the library.

:header-rows: 1
Field	Type	Meaning
`text`	string	Free text to match against asset names.
`filterCriteria.valueFilters`	array	Each carries `values` and a `valueField`, such as `ASIN`.
`sortCriteria`	object	`field` and `order`, such as `CREATED_TIME` and `ASC`.
`size`	integer	Page size, default 25, between 1 and 500.
`token`	string	Token from a previous answer.

The answer carries assetList, token and totalRecords.

### get_asset

assetId is required. Without it the service answers 400 Request input is required to get asset.

:header-rows: 1
Field	Type	Meaning
`assetId`	string	Required. The asset to read.
`version`	string	A version id such as `version_v3`. Omit it and every version comes back.

The answer carries assetGlobal and assetVersionList.

### register_asset body

:header-rows: 1
Field	Type	Meaning
`url`	string	Required. The signed location from `upload_asset`. It expires in 15 minutes.
`name`	string	Required. The name given to the asset.
`assetType`	string	`IMAGE`.
`assetSubTypeList`	array	`LOGO`, `PRODUCT_IMAGE`, `AUTHOR_IMAGE`, `LIFESTYLE_IMAGE` or `OTHER_IMAGE`.
`asinList`	array	Tags the asset with ASINs so it can be found by product later.
`versionInfo`	object	`linkedAssetId` and `versionNotes`, to register this file as a new version of an existing asset.
`associatedSubEntityList`	array	Each carries `brandEntityId`. Required for sellers, not for vendors.
`registrationContext`	object	Associates the asset with a DSP advertiser.
`tags`	array	Tags for the asset.
`skipAssetSubTypesDetection`	boolean	Keep the subtype as given instead of letting the service reclassify it.

### batch_register_assets

Asynchronous. It answers a requestId and nothing else, so the result is read with get_batch_register_status.

:header-rows: 1
Field	Type	Meaning
`assetDetailsList`	array	Between 1 and 50 entries, each shaped like the `register_asset` body above.
`batchRegistrationContext`	object	The context applied to the whole batch.

### Example searching the library

from ad_api.api import CreativeAssets

client = CreativeAssets(account='my_account', debug=False)

res = client.search_assets(body={})
payload = res.payload

print(payload["totalRecords"])
for asset in payload["assetList"]:
    print(asset["assetId"], asset.get("name"))

### Example reading one asset

from ad_api.api import CreativeAssets

client = CreativeAssets(account='my_account', debug=False)

res = client.get_asset(
    assetId="amzn1.assetlibrary.asset1.c560c6b3fd3b38f93df58c01ffcc86bc")
print(res.payload["assetGlobal"])
print(res.payload["assetVersionList"])

### Example uploading and registering one file

from ad_api.api import CreativeAssets
from requests import put

client = CreativeAssets(account='my_account', debug=False)

# 1. ask where to put it
res = client.upload_asset(body={"fileName": "Logo-1000x1000.jpeg"})
url = res.payload["url"]

# 2. put the bytes there, outside this package
put(url, data=open("Logo-1000x1000.jpeg", "rb"))

# 3. register it
res = client.register_asset(body={
    "url": url,
    "name": "PRODUCT-IMAGE-NAME",
    "assetType": "IMAGE",
    "assetSubTypeList": ["PRODUCT_IMAGE"],
    "skipAssetSubTypesDetection": True,
})
print(res.payload)

### Example registering several files at once

import time
from ad_api.api import CreativeAssets

client = CreativeAssets(account='my_account', debug=False)

res = client.batch_register_assets(body={
    "assetDetailsList": [
        {
            "url": "https://.../one.jpeg",
            "name": "ONE",
            "assetType": "IMAGE",
            "assetSubTypeList": ["PRODUCT_IMAGE"],
        },
        {
            "url": "https://.../two.jpeg",
            "name": "TWO",
            "assetType": "IMAGE",
            "assetSubTypeList": ["PRODUCT_IMAGE"],
        },
    ]
})
request_id = res.payload["requestId"]

# the batch runs in the background, so poll it
while True:
    status = client.get_batch_register_status(request_id)
    print(status.payload)
    time.sleep(5)

### A note on an unknown requestId

get_batch_register_status with an id the service does not know answers 400, not 404:

AARServiceBadRequestException while executing registration workflow:
No request exists for the requestId 00000000-0000-0000-0000-000000000000

The route answered, so the message is about the id rather than the path.

register_asset(body: dict, str, file) → ApiResponse

Registers an uploaded asset with the creative assets library with optional contextual and tagging information. The API should be called once the asset is uploaded to the location provided by the /asset/upload API endpoint.

body: | REQUIRED {‘description’: ‘A caSearchRequestCommon}’

url | string | Required The url to upload the asset. The url expires in 15 minutes.

name | string | Required The name to be given to the asset being registered.

asinList | list | Optional Tagging assets with ASIN, promotes asset discoverability downstream. If ASIN is provided at the time of upload/during asset registration, it is applied as a tag on that asset. This allows for that asset to be searchable using that ASIN#. For e.g., An advertiser may want to search for assets tagged with ASIN BC10001, so they can create a store spotlight ad with product images for that ASIN.

assetType | string | The asset type you are registering [IMAGE]

assetSubTypeList | list | For assetType IMAGE acceptable assetSubTypes are LOGO, PRODUCT_IMAGE, AUTHOR_IMAGE, LIFESTYLE_IMAGE, OTHER_IMAGE.

versionInfo | string | The asset type you are registering [IMAGE]

linkedAssetId | string | The registering asset will be created as a new version of this linkedAssetId.

versionNotes | string | The version notes that client can associate to the asset.Versioning enables users to update an old asset, so that you can ensure the latest asset is being used. You can upload a new version of an existing asset along with version notes. Any tags/ASINs from previous version, will be retained on the new version too.

tags | list |

registrationContext | caRegistrationContext | This is used on registration of an asset, to associate DSP assets to a specific advertiser. This is required for assets being uploaded for use in DSP. | associatedPrograms | caAssociatedProgramcaAssociatedProgram |

metadata | string | Include key-value pairs related to the asset. For DSP use “dspAdvertiserId” = “ID”. Include program as AMAZON_DSP.

programName | string | Use this field to specify which program you are uploading an asset for. Currently, the accepted value here on registration is to associate an asset with a DSP advertiser. [ AMAZON_DSP ]

associatedSubEntityList | caAssociatedSubEntityList | This field is required for sellers, but not required for vendors. The brandEntityId is required for sellers uploading assets for use in Sponsored Brands. As a best practice, ensure to include brandEntityId when uploading assets for sellers.

caAssociatedSubEntity |

brandEntityId | string | The entity id of brand, which can be retrieved using GET /brands.

skipAssetSubTypesDetection | boolean | Select true if you want to set an asset to a specific assetSubType, if this is not included the system may reclassify your asset based on specifications.

upload_asset(body: dict, str, file) → ApiResponse: body: | REQUIRED

{

‘fileName’: string The fileName of the asset. pattern: [w]+.jpg|png|mp4|mov|wmv|avi

}

search_assets(body: dict, str, file) → ApiResponse

Search the creative asset library.

body: | REQUIRED {‘description’: ‘A caSearchRequestCommon}’

text | string | The text used for searching assets, it matches asset name, asset name prefix, tags and ASINs associated with the assets

filterCriteria Optional this is used to filter results, we support two types of filters, valueFilter and rangeFilter

valueFilters | list | Filter for certain values of asset attributes

values | list |

valueField | string | [ TAG, ASIN, CAMPAIGN_NAME, CAMPAIGN_ID, PROGRAM, ASSET_TYPE, ASSET_SUB_TYPE, APPROVED_AD_POLICY, ASSET_EXTENSION ]

rangeFilters

range | list | Filter assets which have certain ranges of asset attributes. For example, filter assets which have file size in the range of [10,20] or [40,50].

start | string |

end | string |

sortCriteria Optional this is used to get sorted results

field | string | Enum [ CREATED_TIME, SIZE, NAME, IMAGE_HEIGHT, IMAGE_WIDTH, EXTENSION ]

order | string | Enum [ ASC, DESC ]

pageCriteria Optional this is used for pagination when searching for the first page, no need to put anything, otherwise, use the token returned from previous search call

identifier | dict |

pageNumber | int |

token | string |

size | int | default: 25 minimum: 1 maximum: 500

get_asset(assetId: str, version: str) → ApiResponse

Retrieves an asset along with the metadata

query assetId:string | Required. The assetId

query version:string | Optional. The versionId of the asset, if not included all versions will return.

batch_register_assets(**kwargs) → ApiResponse

Registers several uploaded assets in one call.

This route is asynchronous. It answers a requestId and nothing else, so the result has to be read with get_batch_register_status.

Request Body (required)

assetDetailsList (array): between 1 and 50 entries, each one shaped like the body register_asset accepts:
- url (string): where the file sits, from upload_asset.
- name (string): the name to give the asset.
- assetType (string): IMAGE.
- assetSubTypeList (array): LOGO, PRODUCT_IMAGE, AUTHOR_IMAGE, LIFESTYLE_IMAGE or OTHER_IMAGE.
- asinList (array): tags the asset with ASINs, so it can be found by product later.
- associatedPrograms (array): up to 100 entries, one per program the asset belongs to.
- otherMetadata (object): free key-value pairs of strings.
- tagList (array): tags for the asset.
- versionInfo (object): linkedAssetId and versionNotes, to register this file as a new version of an existing asset.
- skipAssetSubTypesDetection (boolean): keep the subtype as given instead of letting the service reclassify it.
batchRegistrationContext (object): the context applied to the whole batch.

Returns: ApiResponse with requestId, which get_batch_register_status takes.

get_batch_register_status(requestId, **kwargs) → ApiResponse

Reports whether a batch registration has finished.

The requestId comes from batch_register_assets. An id the service does not know answers 400 with AARServiceBadRequestException ... No request exists for the requestId, not a 404: the route answers either way, and the message says the id was not found.

Path

requestId (string): required. The identifier the batch call returned.

Returns: ApiResponse with the state of that batch.