开发人员指南概述

亚马逊广告 API 概览

创建素材

素材库目前支持视频和图片创意素材。

无论哪种创意素材，您都需要进行三步调用：

  1. 生成素材上传 URL。
  2. 将您的素材上传到提供的 URL。
  3. 注册您的素材。

操作步骤

第 1 步： 创建上传 URL

使用 POST /assets/upload 获取上传 URL。确保为要上传的素材使用正确的文件名和支持的维度。使用不受支持的扩展在此步骤中不会导致错误，但以后会遇到错误。

示例： 图片

curl --location --request POST 'https://advertising-api.amazon.com/assets/upload' \
--header 'Amazon-Advertising-API-ClientId: amzn1.application-oa2-client.xxxxxxxxxxx' \
--header 'Authorization: Bearer Atza|xxxxxxxxxx' \
--header 'Amazon-Advertising-API-Scope: xxxxxxxxxxx' \
--header 'Content-Type: text/plain' \
--data-raw '{
    "filename": "logo.png"
}
'

该响应包含一个自定义 URL，您可以在步骤 2 中使用该 URL 上传文件。

{
 "url": "https://al-na-184b9306-7f8a.s3.amazonaws.com/xxxxxxxxxxxxxx"
 }

示例： 视频

curl --location --request POST 'https://advertising-api.amazon.com/assets/upload' \
--header 'Amazon-Advertising-API-ClientId: amzn1.application-oa2-client.xxxxxxxxxxx' \
--header 'Authorization: Bearer Atza|xxxxxxxxxx' \
--header 'Amazon-Advertising-API-Scope: xxxxxxxxxxx' \
--header 'Content-Type: text/plain' \
--data-raw '{
    "filename": "product_video.mov"
}
'

{
 "url": "https://al-na-184b9306-7f8a.s3.amazonaws.com/xxxxxxxxxx"
}

第 2 步： 上传您的素材

要上传您的素材，请对步骤 1 中返回的 URL 使用 PUT。

警告

请确保根据素材类型传递正确的 Content-Type。

示例： 图片

curl --location -g --request PUT 'https://al-na-184b9306-7f8a.s3.amazonaws.com/xxxxxxxxxxxxxx' \
--header 'Content-Type: image/png' \
--data-binary '@/Users/xxxxxx/desktop/logo.png'

示例： 视频

curl --location --request PUT 'https://al-na-9d5791cf-3faf.s3.amazonaws.com/xxxxxxxx' \
--header 'Content-Type: video/quicktime' \
--data-binary '@/Users/xxxxxxxxxx/Downloads/brand_video.mov'

如果素材上传正确，您将收到 200 响应。

第 3 步： 注册素材

使用 POST /assets/register 注册素材。

参数

| 参数 | 必需？ | 说明 | |--- |--- |--- | | url | 是 | 步骤 1 中为素材生成的上传 URL。 | | 名称 | 是 | 素材的名称。 | | asinList | 否 | 与素材关联的 ASIN 的可选列表，用于搜索和分类。 | | assetType | 是 | 素材的类型。目前接受 IMAGE 和 VIDEO。 | | assetSubTypeList | 是 | 素材的子类型。 | | versionInfo | 否 | 如果您要上传现有素材的新版本，请在 versionInfo 中包含 assetId。 | | tags | 否 | 一个可选参数，用于向素材添加相关标签以进行搜索和分类。 | | registrationContext | 是，适用于 DSP 素材 | 只有在 DSP 广告活动中使用素材时需要此参数。如果您将素材用于搜索广告或品牌旗舰店，则无需包含此参数。 | | associatedSubEntityList | 是，适用于亚马逊卖家 | 亚马逊卖家必须提供其品牌实体编号。您可以使用 GET /brands 接口找到这个编号。对于其他广告主，我们建议提供品牌实体编号，但不是必需的。 | | skipAssetSubTypesDetection | 否 | 默认情况下，系统会尝试自动将您的图片分类为子类型。如果您不希望系统进行此分类，请将此参数设置为 TRUE。 |

示例： 图片

curl --location --request POST 'https://advertising-api.amazon.com/assets/register' \
--header 'Amazon-Advertising-API-ClientId: amzn1.application-oa2-client.xxxxxxxxxxxx' \
--header 'Authorization: Bearer Atza|xxxxxxxxxx' \
--header 'Amazon-Advertising-API-Scope: xxxxxxxxxx' \
--header 'Content-Type: text/plain' \
--data-raw '{
  "url": "https://al-na-184b9306-7f8a.s3.amazonaws.com/xxxxxxxxx",
  "name": "logo",
  "asinList": [
    "B07XXXXXX1",
    "B07XXXXXX2",
    "B07XXXXXX3"
  ],
  "assetType": "IMAGE",
  "assetSubTypeList": [
    "LOGO"
  ],
  "associatedSubEntityList": [
    {
      "brandEntityId": "ENTITYXXXXXXXXXX"
    }
  ]
}

'

响应返回 200，其中包含 assetId，可供您在创建或编辑广告活动时使用。

{
 "assetId": "amzn1.assetlibrary.asset1.xxxxx",
 "failedSpecChecks": [],
 "programPolicyValidationsList": null,
 "versionId": "version_v1"
}

注意

素材库不检查图片的合格性。要优化审核流程，请务必遵守广告活动和图片类型设定的要求。

示例： 视频

curl --location --request POST 'https://advertising-api.amazon.com/assets/register' \
--header 'Amazon-Advertising-API-ClientId: amzn1.application-oa2-client.xxxxxxxxx' \
--header 'Authorization: Bearer Atza|xxxxxxxx' \
--header 'Amazon-Advertising-API-Scope: xxxxxxxxxx' \
--data-raw '{
  "url": "https://al-na-9d5791cf-3faf.s3.amazonaws.com/xxxxxxxxx",
  "name": "SB video asset",
  "asinList": [
    "B0XXXXXX1",
    "B0XXXXXX2",
    "B0XXXXXX3"
  ],
  "assetType": "VIDEO",
  "assetSubTypeList": [
    "BACKGROUND_VIDEO"
  ],
  "associatedSubEntityList": [
    {
      "brandEntityId": "ENTITYXXXXXXXXXX"
    }
  ]
}
'

成功的响应将返回 200，其中包含 assetId，可在管理广告活动时使用。响应返回视频素材未通过验证检查的方案类型列表。

在以下示例中，注册的视频素材不符合 DSP OLV、DSP OTT 或品牌旗舰店简介启动视频的条件。此视频适用于品牌推广活动，您会看到 failedSpecChecks 中没有提及品牌推广。

注意

创意素材库的处理不是审核流程的一部分。创意素材可能由于违反广告方案的创意素材政策而不符合展示条件。如果您需要上传新版本的创意素材，请参阅管理素材。

{
    "assetId": "amzn1.assetlibrary.asset1.xxxxxxxxxxx",
    "failedSpecChecks": [
        {
            "Program": "AMAZON_DSP",
            "specProgramName": "DEMAND_SIDE_PLATFORM_OLV",
            "specifications": [
                {
                    "actualValue": "30.0",
                    "arguments": [
                        "23.98",
                        "24.0",
                        "25.0",
                        "29.97"
                    ],
                    "failureReason": "Frame rate is not one of 23.98, 24.0, 25.0, 29.97.",
                    "isPassed": false,
                    "stringId": "al-spec-video-frame-rate"
                },
                {
                    "actualValue": "0",
                    "arguments": [
                        "2"
                    ],
                    "failureReason": "Total number of audio channels across all audio streams is less than 2.",
                    "isPassed": false,
                    "stringId": "al-spec-min-audio-channel-count"
                }
            ]
        },
        {
            "Program": "AMAZON_DSP",
            "specProgramName": "DEMAND_SIDE_PLATFORM_OTT",
            "specifications": [
                {
                    "actualValue": "30.0",
                    "arguments": [
                        "23.98",
                        "24.0",
                        "25.0",
                        "29.97"
                    ],
                    "failureReason": "Frame rate is not one of 23.98, 24.0, 25.0, 29.97.",
                    "isPassed": false,
                    "stringId": "al-spec-video-frame-rate"
                },
                {
                    "actualValue": "9.966667",
                    "arguments": [
                        "15.0",
                        "30.0"
                    ],
                    "failureReason": "Duration is not one of 15.0, 30.0 seconds.",
                    "isPassed": false,
                    "stringId": "al-spec-video-duration"
                },
                {
                    "actualValue": "0",
                    "arguments": [
                        "2"
                    ],
                    "failureReason": "Total number of audio channels across all audio streams is less than 2.",
                    "isPassed": false,
                    "stringId": "al-spec-min-audio-channel-count"
                }
            ]
        },
        {
            "Program": "STORES",
            "specProgramName": "STORES_INTRO_SPLASH",
            "specifications": [
                {
                    "actualValue": "16:9",
                    "arguments": [
                        "9:16"
                    ],
                    "failureReason": "Aspect ratio is not 9:16.",
                    "isPassed": false,
                    "stringId": "al-spec-video-aspect-ratio"
                }
            ]
        }
    ],
    "programPolicyValidationsList": null,
    "versionId": "version_v1"
}

后续步骤

注册素材后，会将其设置为 PROCESSING 状态。一旦素材处于 ACTIVE 状态，即可在广告活动中使用。

提示

根据您正在上传的文件的大小，素材最多可以处于 PROCESSING 状态 30 分钟。我们建议先轮询 GET /assets 接口，以检查状态是否设置为 ACTIVE，然后再尝试在广告活动中使用该素材。由于处理期包含视频转码过程，视频素材处于 PROCESSING 状态的时间通常会较长。如果转码过程失败，素材状态将变为 INACTIVE。

如果您的素材验证失败，可以进行更正并上传新版本的素材。有关更多信息，请参阅管理素材。

Amazon Advertising logo