广告创意相关 API

提示

由于系统之间的同步机制，通过 ADX 界面查询到的广告创意审核状态，与 API 查询结果可能不同。必须 API 同步到审核通过的素材，才可用于投放。
创意素材（包括但不限于视频素材）大小限制150M，ADX 拉取素材（DSP 提供的 file_url）时间限制在90秒，超过90秒未拉取完整素材会提示601错误， DSP 需要保证素材 url 所在的 CDN 服务器的出口带宽，建议出口带宽最低限速在3MB/s 以上。
接口开发时，可登录 ADX 平台，在“运营工具”页面使用“API 测试工具”自助联调；联调后，可直接在 ADX 的线上环境做提交创意测试，但必须使用广告主“合约广告测试专用_品牌(9699840)”，且确保测试用的非正式创意，不会用于线上流量投放。（广告主需要同步到 DSP 账号后才能使用）

DSP 通过该系列 API 进行广告创意的相关工作，包括新建、修改、查询、获取创意数量、更新有效期、创意下线。

PDB/PD 接口说明：

在广告主下上传广告创意，审核通过的素材才能用来实时回复流量请求，否则系统将报错。
由于腾讯广告平台对于每个广告主下的创意总量有限制，因此 ADX 平台也需限制 DSP 提交的创意上限。详见：【通知】腾讯 PDB/PD 广告创意使用规范变更

RTB：若广告主未审核通过，则无法上传广告创意。

1. 创建

接口：adcreative/add
请求字段：

名称	类型	描述
data	数组类型	最多10个

data 内容详细：

名称	类型	必填	描述
dsp_order_id	string	Y	广告创意素材ID，DSP 需保证该ID在 DSP 侧的唯一性
advertiser_id	int	Y	广告主ID和 name 二选一，都传的话优先使用ID
advertiser_name	string	Y	同上
display_id	int	Y	广告形式ID
end_date	string	N	有效期，最长可设90天，示例：2022-05-19 （建议按实际投放需要填写，在线时间过长将持续占用创意额度；如不填写，默认设为90天）
targeting_url	string	Y	落地页，支持302
no_click	string	N	（仅支持白名单客户填充）禁止点击：当前仅支持 no_click=Y，不传该字段表示默认可点击；当值为 Y 时，点击监测链接和落地页链接均需要为空
ldp_demo_url	string	N	落地页截图，仅针对优投客户（落地页在推广日期之前不能打开的情况）
is_only_pd	int	N	是否只投放 PD (默认为0:否，1:是，即只能投放 PD)
monitor_url	数组类型	N	曝光监测地址，最多 5 个
monitor_position	数组类型	N	在设置了 monitor_url 的情况下配合使用。仅针对视频贴片素材，监测请求位置（该字段的填充值仅支持0，如需要自定义其他上报时机，请联系销售走白名单申请流程）
monitor_settle_bill	数组类型	N	在设置了 monitor_url 的情况下配合使用。（仅支持 PDB）
visible_monitor_url	数组类型	N	可见曝光监测地址（仅支持新闻 app 信息流）
click_monitor_url	数组类型	N	点击监测地址，最多3个
video_monitor_by_time_url	数组类型	N	仅针对信息流视频监测地址 video_monitor_by_time_url ，对象数组（仅 PDB、PD 支持使用，RTB 不支持）
ad_content	数组类型	Y	创意素材内容，包括视频、图片、文本等。需严格按照广告形式的定义顺序来指定上传
ad_ext	对象类型	N	高级扩展参数。详见下面请求示例
ad_ext2	对象类型	N	高级扩展参数2。详见下面请求示例
mini_program_id	string	N	小程序ID长度（字节）：最小 1，最大 512 可以为空
mini_program_path	string	N	小程序路径长度（字节）：最小 1，最大 2048 可以为空

video_monitor_by_time_url 内容详细：

名称	类型	必填	描述
url	string	Y	监测链接，最多5个
time	int	Y	上报时间点（秒）

ad_content 内容详细：

名称	类型	必填	描述
file_text	string	Y	file_text，file_url 必须指定其中一个，按照广告形式ID的定义校验，文件大小，类型，尺寸
file_url	string	Y	同上
file_md5	string	N	仅针对视频文件，如果指定了 md5值，其它两项就不再需要传了。

说明：
file_md5 字段仅针对视频文件，如果传入了该参数，则先查找该 md5值的素材以前是否传入过 adx 系统，如果已经传入过则直接使用该文件，不在拉取素材，节省了网络传输流量和时间。

ad_ext 内容详细：

名称	类型	必填	描述
app_info	对象类型	N	app 下载唤起特性
universal_link	string	N	仅支持 XQ 系流量；广告点击后，优先触发 ulink，其次是 deeplink，最后触发“推广目标”（即 product_type 中设置的目标）
share_info	对象类型	N	分享特性

app_info 内容详细：

名称	类型	必填	描述
product_type	int	Y	枚举说明： 1-普通链接（仅支持1） ~~2-android 应用下载 3-ios 应用下载（将废弃）~~
~~app_id~~	~~int~~	N	~~下载类的 app id，若 product_type=2,3为安卓或 iOS 则必填（将废弃）~~
deep_link	string	N	应用直达 URL（deep_link 包名必须与下单时设置的一致）

应用直达及跳转小程序说明：

应用直达：通过 deeplink、ulink 字段唤起 app，使用该字段时，①必须确认媒体下单时已设置了允许使用使用直达；② 素材上也需要填写该字段；③ deeplink 链接对应的包名，必须与下单时填写的一致。
跳转小程序：通过 mini_program_id、mini_program_path 字段唤起微信小程序，使用该字段时，① 必须确认媒体下单时已设置了允许使用小程序；② 素材上填写的小程序ID，必须与下单时保持一致。

share_info 内容详细：

名称	类型	必填	描述
description	string	Y	分享文案，4-28汉字
image	string	Y	分享配图，图片的 URL，尺寸114*114， jpg 格式

ad_ext2内容详细：

名称	类型	必填	描述
feed_card	数组类型	N	信息流轮卡片播放形式专用

注：信息流轮播卡片支持3-6组素材，且素材组数（ad_content）必须要与链接组数（ad_ext2.feed_card 保持严格一致）。如当前创意有6组素材，则 feed_card 数组长度为6，且对应 ad_content 数组也必须为6组（例如 display_id=200123，填6组素材时，则 ad_content 传15个元素值：广告主头像+广告主名称+横板大图文案+6组卡片素材（每组1个大图1个标题）= 15个素材元素；填3组素材时，则 ad_content 传9个元素值：广告主头像+广告主名称+横板大图文案+3组卡片素材（每组1个大图1个标题）= 9个素材元素；

feed_card 内容详细：

名称	类型	必填	描述
targeting_url	string	N	轮播卡片 targeting_url（H5落地页链接）
mini_program_path	string	N	轮播卡片 mini_program_path（小程序页面链接）
deep_link	string	N	轮播卡片 deeplink（应用直达链接）
universal_link	string	N	轮播卡片 universal_link（Ulink 通用链接）

注：以上四个字段值不能同时为空

接口返回：

名称	类型	描述
ret_code	int	返回码
ret_msg	数组类型	返回内容
error_code	int	错误补充码

ret_msg 内容详细：

名称	类型	描述
dsp_order_id	string	DSP 唯一订单号
err_code	int	需要时返回，成功时不返回，失败返回具体错误码。
err_msg	string	需要时返回，成功时不返回，错误具体描述

请求示例：

{
  "data": [
    {
      "dsp_order_id": "6001",
      "advertiser_id": 100,
      "display_id": 10389,
      "targeting_url": "http://xinwen.qq.com/adtargetpage?a=1",
      "is_only_pd": 1,
      "monitor_url": [
        "http://monitor.qq.com/monitor1",
        "http://monitor.qq.com/monitor2"
      ],
      "monitor_position": [
        2,
        5
      ],
      "monitor_settle_bill": [
        1,
        0
      ],
      "click_monitor_url": [
        "http://click.qq.com/click1"
      ],
      "video_monitor_by_time_url": [
        {
          "url": "http://tytx.m.cn.miaozhen.com/r/",
          "time": "0"
        },
        {
          "url": "http://t.cr-nielsen.com/dar?_t=r",
          "time": "0"
        }
      ],
      "ad_content": [
        {
          "file_text": "广告标题 t"
        },
        {
          "file_url": "http://cdn.qq.com/pic640x246.jpg"
        },
        {
          "file_url": "http://cdn.qq.com/pic114x114.jpg"
        },
        {
          "file_text": "摘要 c"
        },
        {
          "file_text": "广告主名称 a"
        }
      ],
      "ad_ext": {
        "app_info": {
          "product_type": 3,
          "app_id": 989673964
        }
      },
      "mini_program_id": "gh_abcdef",
      "mini_program_path": "abcdef"
    }
  ]
}

注：
ad_ext 高级扩展参数目前仅支持 app_info,如需使用请注意参数 key 值，evokeapp 已废弃不再使用。
SDK 客户端会对 deeplink 地址进行有效性校验，无效的话会自动转成非唤起的广告形式，打开落地页。

PDB/PD 模式新增参数 is_only_pd，说明：是否只投放 PD (默认为0:否，1:是，即只能投放 PD)。
PDB 模式新增参数 monitor_settle_bill 对应 monitor_url 参数设置指定哪条曝光监测地址是用于第三方结算的，用于结算的会进行 monitor_url 的强校验。
对于 PDB 必须指定一条用于结算的第三方监测 url。
例如 monitor_url 指定了 2 条 ["http://a.com","http://b.com"]，如果要设置 a.com 为用于结算的第三方监测 url，则 monitor_settle_bill 应设置为 [1,0]。

返回示例（成功）：

{
  "ret_code": 0,
  "ret_msg": [
    {
      "dsp_order_id": "6001"
    }
  ]
}

返回示例（失败）：

{
  "ret_code": 1,
  "ret_msg": [
    {
      "dsp_order_id": "6001",
      "err_code": 1107,
      "err_msg": "either file_url/file_text was needed."
    }
  ]
}

2. 修改

接口：adcreative/update
请求字段：

名称	类型	描述
data	数组类型	最多10个

说明：已下线的创意不可再修改

data 内容详细：

名称	类型	必填	描述
dsp_order_id	string	Y	广告创意素材ID，DSP 需保证该ID在 DSP 侧的唯一性
advertiser_id	int	Y	广告主ID和 name 二选一，都传的话优先使用ID
advertiser_name	string	Y	同上
display_id	int	Y	广告形式ID
targeting_url	string	Y	落地页，支持302
monitor_url	数组类型	N	曝光监测地址，最多5个
monitor_position	数组类型	N	在设置了 monitor_url 的情况下配合使用。仅针对视频素材，监测请求位置
monitor_settle_bill	数组类型	N	在设置了 monitor_url 的情况下配合使用。（仅支持 PDB）
click_monitor_url	数组类型	N	点击监测地址，最多3个
ad_content	数组类型	Y	创意素材内容，包括视频、图片、文本等。需严格按照广告形式的定义顺序来指定上传。
ad_ext	对象类型	N	高级扩展参数。详见下面请求示例

ad_content 内容详细：

名称	类型	必填	描述
file_text	string	Y	file_text，file_url 必须指定其中一个，按照广告形式ID的定义校验，文件大小，类型，尺寸
file_url	string	Y	同上
file_md5	string	N	仅针对视频文件，如果指定了 md5值，其它两项就不再需要传了。

ad_ext 内容详细：

名称	类型	必填	描述
app_info	对象类型	N	同 adcreative/add
share_info	对象类型	N	同 adcreative/add

接口返回：

名称	类型	描述
ret_code	int	返回码
ret_msg	数组类型	返回内容
error_code	int	错误补充码

ret_msg 内容详细：

名称	类型	描述
dsp_order_id	string	DSP 唯一订单号
err_code	int	需要时返回，成功时不返回，失败返回具体错误码。
err_msg	string	需要时返回，成功时不返回，错误具体描述

注：

广告主ID、名称（advertiser_id / advertiser_name）和广告形式（display_id）不允许修改。

请求示例：

{
  "data": [
    {
      "dsp_order_id": "6001",
      "advertiser_id": 100,
      "display_id": 10389,
      "deal_id": 1234567,
      "targeting_url": "http://xinwen.qq.com/adtargetpage?a=1",
      "monitor_url": [
        "http://monitor.qq.com/monitor1",
        "http://monitor.qq.com/monitor2"
      ],
      "monitor_position": [
        2,
        5
      ],
      "monitor_settle_bill": [
        1,
        0
      ],
      "click_monitor_url": [
        "http://click.qq.com/click1"
      ],
      "visible_monitor_url": [
        "http://visible.qq.com/cgi?compaign="
      ],
      "ad_content": [
        {
          "file_text": "广告标题 new"
        },
        {
          "file_url": "http://cdn.qq.com/pic640x246.jpg"
        },
        {
          "file_url": "http://cdn.qq.com/pic114x114.jpg"
        },
        {
          "file_text": "摘要 new"
        },
        {
          "file_text": "广告主名称 new"
        }
      ],
      "ad_ext": {
        "app_info": {
          "product_type": 3,
          "app_id": 989673964
        }
      },
      "mini_program_id": "gh_abcdef",
      "mini_program_path": "abcdef"
    }
  ]
}

返回示例（成功）：

{
  "ret_code": 0,
  "ret_msg": [
    {
      "dsp_order_id": "6001"
    }
  ]
}

返回示例（失败）：

{
  "ret_code": 1,
  "ret_msg": [
    {
      "dsp_order_id": "6001",
      "err_code": 503,
      "err_msg": "advertiser_id/advertiser_name can not be modified for update."
    }
  ]
}

3. 查询（包括审核状态）

接口：adcreative/list

注意：

系统同步有延迟，素材审核状态通过界面查询与 API 同步可能不同，敬请谅解。必须 API 同步到审核通过的素材，才可用于投放。

请求字段：

名称	类型	描述
data	数组类型	最多10个

data 内容详细：

名称	类型	必填	描述
dsp_order_id	string	Y	广告创意素材ID，DSP 需保证该ID在 DSP 侧的唯一性

接口返回：

名称	类型	描述
ret_code	int	返回码
ret_msg	数组类型	返回内容
error_code	int	错误补充码

ret_msg 内容详细：

名称	类型	描述
dsp_order_id	string	同新增/修改
advertiser_id	int	同新增/修改
advertiser_name	string	同新增/修改
display_id	int	同新增/修改
is_only_pd	int	同新增/修改
targeting_url	string	同新增/修改
monitor_url	数组类型	同新增/修改
monitor_position	数组类型	同新增/修改
monitor_settle_bill	数组类型	同新增/修改
click_monitor_url	数组类型	同新增/修改
status	int	审核状态（1：审核通过 2：审核未通过，3：待审核）
ott_black_channel	数组类型	ott 素材审核未通过的牌照方ID： 1. 其中443和1016为默认拒审ID，可以忽略； 2.如出现其他ID，该牌照方流量将出现368告警，请修改素材后重新送审
vinfo	string	审核意见
ad_content	数组类型	同新增/修改
ad_ext	对象类型	高级扩展参数。详见下面请求示例

ad_content 内容详细：

名称	类型	描述
file_text	string	同新增/修改
file_url	string	同新增/修改
file_md5	string	同新增/修改

ad_ext 内容详细：

名称	类型	描述
app_info	对象类型	app 下载唤起特性

app_info 内容详细：

名称	类型	描述
product_type	int	枚举说明： 1-普通链接（默认）2-android 应用下载 3-ios 应用下载
app_id	int	下载类的 app id
deep_link	string	应用直达 URL

请求示例：

{
  "data": [
    {
      "dsp_order_id": "6001"
    }
  ]
}

返回示例：

{
  "ret_code": 0,
  "ret_msg": [
    {
      "dsp_order_id": "6001",
      "advertiser_id": 100,
      "display_id": 10389,
      "is_only_pd": 1,
      "targeting_url": "http://xinwen.qq.com/adtargetpage?a=1",
      "monitor_url": [
        "http://monitor.qq.com/monitor1",
        "http://monitor.qq.com/monitor2"
      ],
      "monitor_position": [
        2,
        5
      ],
      "monitor_settle_bill": [
        1,
        0
      ],
      "click_monitor_url": [
        "http://click.qq.com/click1"
      ],
      "visible_monitor_url": [
        "http://visible.qq.com/cgi?compaign="
      ],
      "status": 1,
      "vinfo": "",
      "ad_content": [
        {
          "file_text": "广告标题 new"
        },
        {
          "file_url": "http://cdn.qq.com/pic640x246.jpg"
        },
        {
          "file_url": "http://cdn.qq.com/pic114x114.jpg"
        },
        {
          "file_text": "摘要 new"
        },
        {
          "file_text": "广告主名称 new"
        }
      ],
      "ad_ext": {
        "app_info": {
          "product_type": 3,
          "app_id": 989673964
        }
      }
    }
  ]
}

4. 获取指定广告主创意素材当前数量

接口：adcreative/count

请求字段：

名称	类型	描述
data	数组类型	最多10个

data 内容详细：

名称	类型	必填	描述
advertiser_id	int	Y	广告主ID，通过 advertiser/list 接口获取

接口返回：

名称	类型	描述
ret_code	int	返回码
ret_msg	数组类型	返回内容
error_code	int	错误补充码

ret_msg 内容详细：

名称	类型	描述
advertiser_id	int	广告主ID
advertiser_name	string	广告主名称
count	int	DSP 已创建数

请求示例：

{
  "dsp_id": 100242,
  "token": "11111111111111",
  "sig": "1111111111111111111",
  "time": 1650017461,
  "data": [
    {
      "dsp_order_id": "test-11525-0415-02",
      "end_date": "2022-05-19"
    }
  ]
}

返回示例：

{
  "ret_code": 0,
  "ret_msg": [
    {
      "advertiser_id": 78930,
      "advertiser_name": "广州高露洁棕榄有限公司_品牌(198558)",
      "count": 54
    }
  ],
  "error_code": 0
}

5. 更新创意素材有效期

接口：adcreative/extend

请求字段：

名称	类型	描述
data	数组类型	最多10个

说明：已下线的创意不可再修改有效期

data 内容详细：

名称	类型	必填	描述
dsp_order_id	string	Y	广告创意素材ID
end_date	string	Y	当前日期~未来90天

接口返回：

名称	类型	描述
ret_code	int	返回码
ret_msg	数组类型	返回内容
error_code	int	错误补充码

ret_msg 内容详细：

名称	类型	描述
dsp_order_id	string	广告创意素材ID
end_date	string	结束时间

请求示例：

{
  "dsp_id": 100242,
  "token": "1111111111111",
  "sig": "111111111111111111111",
  "time": 1650017461,
  "data": [
    {
      "dsp_order_id": "test-11525-0415-02",
      "end_date": "2022-05-19"
    }
  ]
}

返回示例：

{
  "ret_code": 0,
  "ret_msg": [
    {
      "dsp_order_id": "test-11525-0415-02",
      "end_date": "2022-05-19"
    }
  ],
  "error_code": 0
}

6. 创意删除下线

接口：adcreative/del

请求字段：

名称	类型	描述
data	数组类型	最多10个

data 内容详细：

名称	类型	必填	描述
dsp_order_id	string	Y	广告创意素材ID

接口返回：

名称	类型	描述
ret_code	int	返回码
ret_msg	数组类型	返回内容
error_code	int	错误补充码

ret_msg 内容详细：

名称	类型	描述
dsp_order_id	string	广告创意素材ID

请求示例：

{
  "dsp_id": 100242,
  "token": "1111111111111",
  "sig": "111111111111111111111",
  "time": 1650017461,
  "data": [
    {
      "dsp_order_id": "78921112"
    }
  ]
}

返回示例：

{
  "ret_code": 0,
  "ret_msg": [
    {
      "dsp_order_id": "78921112"
    }
  ],
  "error_code": 0
}

7. 自动合成标版创意绑定

接口：adcreative/binddeal

请求字段：

名称	类型	描述
data	数组类型	最多10个

data 内容详细：

名称	类型	必填	描述
dsp_order_id	string	Y	广告创意素材ID
deal_id	int	Y	程序化下单资源 deal_id

注意：

dsp_order_id 和 deal_id 为多对多 关系。
绑定的前提是 dsp_order_id 已审核通过，且 deal_id 存在有效订单 ；
如果 dsp_order_id 有更新且触发了审核，则需要在审核通过之后重新发起绑定 。
当前支持的自动合成标版广告形式有ID：200362, 200363, 200364, 200365, 200366, 200367

接口返回：

名称	类型	描述
ret_code	int	返回码
ret_msg	数组类型	返回内容
error_code	int	错误补充码

ret_msg 内容详细：

名称	类型	描述
dsp_order_id	string	广告创意素材ID
deal_id	int	程序化下单资源 deal_id
err_code	int	需要时返回，成功时不返回，失败返回具体错误码。
err_msg	string	需要时返回，成功时不返回，错误具体描述

请求示例：

{
  "dsp_id": 100242,
  "token": "1111111111111",
  "sig": "111111111111111111111",
  "time": 1650017461,
  "data": [
    {
      "dsp_order_id": "78921112",
      "deal_id": 123
    }
  ]
}

返回示例（成功）：

{
  "ret_code": 0,
  "ret_msg": [
    {
      "dsp_order_id": "78921112",
      "deal_id": 123
    }
  ]
}

返回示例（失败）：

{
  "ret_code": 1,
  "ret_msg": [
    {
      "dsp_order_id": "6001",
      "deal_id": 123,
      "err_code": 1107,
      "err_msg": "bind failed"
    }
  ]
}

注意 : 动漫标版场景在送审接口（adcreative/add）的 data.ad_content 结构体传参时，语音文件创意元素项请设置为空 （仅作为占位符）

例如 display_id=200362：

{
  "display_id": "200362",
  "ad_content": [
    {
      "file_url": "https://xxx.mp4"
    },
    {
      "file_url": "https://xxxx.png"
    },
    {
      "file_url": ""
    },
    {
      "file_text": "这是个好的语音文案这是个好的语音文案"
    },
    {
      "file_text": "timo-pro"
    },
    {
      "file_text": "yunlong-pro"
    }
  ]
}

1. 创建​

2. 修改​

3. 查询（包括审核状态）​

4. 获取指定广告主创意素材当前数量​

5. 更新创意素材有效期​

6. 创意删除下线​

7. 自动合成标版创意绑定​

1. 创建

2. 修改

3. 查询（包括审核状态）

4. 获取指定广告主创意素材当前数量

5. 更新创意素材有效期

6. 创意删除下线

7. 自动合成标版创意绑定