搜索图片
您可以使用本接口从素材库中获取广告账号下的图片素材。
最多只会返回前 10000 条数据（按照素材修改时间modify_time排序），10000 条之后的数据不支持查询。
v1.2与v1.3版本对比
以下表格概括了 v1.2与v1.3接口的变化。
xtable
|变化内容{30%}|v1.2{35%}|v1.3{35%}|
|---|---|---|
|接口路径|/v1.2/file/image/ad/search/|/v1.3/file/image/ad/search/|
|请求参数类型 |`advertiser_id`: number|`advertiser_id`: string|
|废弃返回参数|/|`id`: string|
|新增返回参数|/|`is_carousel_usable`|
请求
地址 https://business-api.tiktok.com/open_api/v1.3/file/image/ad/search/
方法 GET
请求Header
|字段|类型|描述|
|---|---|---|
|Access-Token {必填}|string|授权访问令牌。可以通过[获取访问令牌](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162)接口获取。|
请求参数
|字段|类型|描述|
|---|---|---|
|advertiser_id {必填}|string|广告账号|
|filtering |object|筛选条件。本参数是一个筛选项数组。|
#|height |number|图片高度。|
#|image_ids |string[]|图片ID列表。最多可包含100个ID。|
#|material_ids|string[]|素材ID列表。最多可包含100个ID。|
#|ratio |float[]|图片宽高比，例如 [1.7, 2.5]，输入1.7则搜索满足宽高比介于1.65-1.75之间的图片，即精度上下浮动0.05。|
#|width |number|图片宽度。 |
#|displayable|bool|期望搜索范围。枚举值：<ul><li>`False`（默认值）：在所有素材中搜索。</li><li>`True`：在平台展示的素材中搜索。</li></ul>|
|page |number|当前页数。默认值: `1`，取值范围: ≥ 1。|
|page_size |number|分页页面大小。默认值: `20`，取值范围: 1-100。|
示例
(code curl http)
curl --location --request GET 'https://business-api.tiktok.com/open_api/v1.3/file/image/ad/search/?advertiser_id={{advertiser_id}}' \
--header 'Access-Token: {{Access-Token}}'
(/code)
返回
|字段|类型|描述|
|---|---|---|
|code |number|返回码。完整返回码列表及描述，可见[附录-返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。 |
|message |string|返回信息。更多信息可见[附录-返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。|
|data |object|返回数据。 |
#|list |object[]|图片信息列表。 |
##|image_id |string|图片ID，用于广告投放中创建广告。|
##|material_id|string|素材ID。|
##| is_carousel_usable | boolean | 该图片的来源是否适用于轮播广告。 <br><p><span style="color:darkred"><b>注意</b></span>：若要在轮播广告中使用图片，需确保： <ul><li>本字段的值为`true`，<strong>且</strong></li><li>图片满足[创建轮播广告-步骤-创建一个广告](https://ads.tiktok.com/marketing_api/docs?id=1766217791987713)中列出的规格要求。 </li></ul>|
##|width |number|图片宽度。 |
##|format|string|图片格式。 |
##|url |string|图片预览URL，1小时有效期，过期后需重新获取。 |
##|height |number|图片高度。 |
##|signature |string|图片MD5。 |
##|size |number|图片大小，单位Byte。|
##|file_name |string |图片名称。|
##|create_time |string |创建时间。UTC 时间，格式：2020-06-10T07:39:14Z。 |
##|modify_time |string |修改时间。UTC 时间，格式：2020-06-10T07:39:14Z。 |
##|displayable|boolean|图片能否在平台中展示。|
#|page_info |object|分页信息。|
##|page |number|当前页数。|
##|page_size |number|分页大小。|
##|total_number |number|结果总数。|
##|total_page |number|总页数。|
|request_id |string|请求的日志id，唯一标识一个请求。 |
示例
(code Success-Response http)
HTTPS/1.1 200 OK
{
"code": 0,
"message": "OK",
"request_id": "{{request_id}}",
"data": {
"page_info": {
"page_size": 20,
"total_page": 1,
"total_number": 2,
"page": 1
},
"list": [
{
"height": 720,
"size": 118834,
"image_url": "{{image_url}}",
"modify_time": "{{modify_time}}",
"create_time": "{{create_time}}",
"image_id": "{{image_id}}",
"file_name": "{{file_name}}",
"width": 1280,
"signature": "{{signature}}",
"displayable": false,
"material_id": "{{material_id}}",
"format": "jpeg",
"is_carousel_usable": false
},
{
"height": 720,
"size": 159992,
"image_url": "{{image_url}}",
"modify_time": "{{modify_time}}",
"create_time": "{{create_time}}",
"image_id": "{{image_id}}",
"file_name": "{{file_name}}",
"width": 1280,
"signature": "{{signature}}",
"displayable": false,
"material_id": "{{material_id}}",
"format": "jpeg",
"is_carousel_usable": false
}
]
}
}
(/code);