上传图片

您可以使用本接口上传图片到素材库，获得的图片ID可以直接进行广告投放。

文件上传接口超时时间为10秒，传输速度由网络带宽决定。请控制上传文件大小。

若想了解创建单图片广告的步骤，请查看创建单图片广告。

若想了解创建轮播广告的步骤，请查看创建轮播广告。

v1.2与v1.3版本对比

以下表格概括了 v1.2与v1.3接口的变化。 xtable |变化内容{30%}|v1.2{35%}|v1.3{35%}| |---|---|---| |接口路径|/v1.2/file/image/ad/upload/|/v1.3/file/image/ad/upload/| |请求参数类型 |`advertiser_id`: number|`advertiser_id`: string| |新增返回参数| / |`is_carousel_usable`| |废弃返回参数| / | `id`: string |

请求

地址 https://business-api.tiktok.com/open_api/v1.3/file/image/ad/upload/

方法 POST

请求Header

|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
|Access-Token {必填}|string|授权访问令牌。可以通过[获取Access token](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162)接口获取。|
|Content-Type {必填}|string|请求消息类型。<br>当`upload_type`为`UPLOAD_BY_FILE`时，使用`"multipart/form-data"`。<br>当`upload_type`为`UPLOAD_BY_URL`时，使用`"application/json"` 。 |

请求参数

|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
|advertiser_id {必填}|string|广告账号。|
|file_name |string |图片名称。<br><br>长度限制： 1-100 个字符。<br><br>默认值为为文件名称。如果最终长度超过 100 个字符，将会自动截断。<br><br><p><span style="color:darkred"><b>重要提示</b></span>: 同一个广告账户（`advertiser_id`）下的图片不能重名。您可以调用[/file/name/check/](https://ads.tiktok.com/marketing_api/docs?id=1759130033155073)查验文件名称是否已存在。<br>如果上传图片时返回文件名重复的错误信息，请将图片文件重命名或添加时间戳（例如，以`<filename>_<timestamp>`)，然后再重新上传图片文件。|
|upload_type{必填} |string|图片上传方式。<br><br>默认值: `UPLOAD_BY_FILE`。<br><br>枚举值: `UPLOAD_BY_FILE`，`UPLOAD_BY_URL`，`UPLOAD_BY_FILE_ID`。|
|image_file {+条件必填}|file|`upload_type`为`UPLOAD_BY_FILE`时必填。<br><br>图片文件。<br><br>推荐设置:<br><ul><li> 文件大小：小于 50 MB。</li><li>图片分辨率：图片的总像素数，即宽度和高度的乘积，不可超过3,686,400像素（1440 x 2560）。例如，分辨率为 2400 x 1256 像素的图片支持上传，但分辨率为 3600 x 1256 像素的图片将触发报错。<br>要了解特定用例的推荐图片分辨率，请查看"<a href="#item-link-图片分辨率指南及使用案例">图片分辨率指南及使用案例</a>"小节。</li><li>文件类型: JPG，JPEG，或 PNG。</li></ul>|
|image_signature {+条件必填}|string|`upload_type`为`UPLOAD_BY_FILE`时必填。<br><br>图片的MD5（用于服务端校验）。|
|image_url {+条件必填}|url|`upload_type`为`UPLOAD_BY_URL`时必填。<br><br>图片url地址，例如http://xxx.xxx。|
|file_id{+条件必填}| string | 当`upload_type`为`UPLOAD_BY_FILE_ID`时必填。<br><br>上传图片的`file_id`。<br><br>可从[文件上传](https://ads.tiktok.com/marketing_api/docs?id=1737719988918274)接口获取。|

图片分辨率指南及使用案例

下表概述了特定使用案例的推荐分辨率。请确保您上传的图片文件使用了对应用例的推荐分辨率，以避免图片在广告中投放时图片被压缩或放大（图像可能会变模糊）。

| 使用案例{40%} | 推荐分辨率{60%} |
|---|---|
| Pangle 版位的单图片广告 | <ul><li>720 像素（宽度）x 1280 像素（高度）</li><li>1200 像素（宽度）x 628 像素（高度）</li><li>640 像素（宽度）x 640 像素（高度）</li><li> 640 像素（宽度）x 100 像素（高度）</li><li>600 像素（宽度）x 500 像素（高度）</li><li>640 像素（宽度）x 200 像素（高度）</li></ul>|
| 全球化应用组合版位的单图片广告 | <ul><li>720 像素（宽度）x 1280 像素（高度）</li><li>1200 像素（宽度）x 628 像素（高度）</li><li>640 像素（宽度）x 640 像素（高度）</li></ul> |
| TikTok 单视频广告中的视频封面（即视频缩略图） | <ul><li>720 像素（宽度）x 1280 像素（高度）</li><li>1280 像素（宽度） x 720 像素（高度）</li><li>640 像素（宽度）x 640 像素（高度）</li></ul> <br><p><span style="color:darkred"><b>注意</b></span>：视频封面的分辨率需与视频本身的分辨率一致，且满足以下要求：<ul><li>宽高比为 9:16、16:9 或 1:1。</li><li>分辨率满足相应宽高比允许的区间范围：<ul><li>宽高比为 9:16 时： 960-3840 像素（宽度）× 540-2160 像素（高度）</li><li>宽高比为 16:9 时： 960-3840 像素（宽度）× 540-2160 像素（高度）</li><li>宽高比为 1:1 时： 640-1280 像素（宽度）× 640-1280 像素（高度） </li></ul></li></ul>|

示例

(code curl http)
curl --location --request POST 'https://business-api.tiktok.com/open_api/v1.3/file/image/ad/upload/' \
--header 'Access-Token: {{Access-Token}}' \
--header 'Content-Type: multipart/form-data' \
--form 'advertiser_id="{{advertiser_id}}"' \
--form 'file_name="{{file_name}}"' \
--form 'image_file=@"{{image_file}}"' \
--form 'image_signature="{{image_signature}}"'
(/code)

返回

|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
|code |number|返回码。完整返回码列表及描述，可见[附录-返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。 |
|message |string|返回信息。更多信息可见[附录-返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097) 。|
|data |object|返回数据。 |
#|image_id |string|图片 ID，用于广告投放中创建广告。|
#|material_id|string|素材 ID。|
#| is_carousel_usable | boolean | 该图片的来源是否适用于轮播广告。  <br> <br><p><span style="color:darkred"><b>注意</b></span>：<ul><li>由于图片数据写入存在时延，可能不返回本字段。在此情况下，建议您等待 10 秒后，将本接口返回的 `image_id` 传入 [/file/image/ad/info/](1740051721711618.html) 或 [/file/image/ad/search/](1740052016789506.html)，查询图片的此项信息。</li><li>若要在轮播广告中使用图片，需确保本字段的值为`true`，且图片满足[创建轮播广告-步骤-创建一个广告](https://ads.tiktok.com/marketing_api/docs?id=1766217791987713)中列出的规格要求。</li></ul>|
#|displayable|bool |图片能否在平台中展示。|
#|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。<br> <br><p><span style="color:darkred"><b>注意</b></span>：由于图片数据写入存在时延，可能不返回本字段。在此情况下，建议您等待 10 秒后，将本接口返回的 `image_id` 传入 [/file/image/ad/info/](1740051721711618.html) 或 [/file/image/ad/search/](1740052016789506.html)，查询图片的此项信息。 |
#|modify_time |string |修改时间。UTC 时间，格式：2020-06-10T07:39:14Z 。<br> <br><p><span style="color:darkred"><b>注意</b></span>：由于图片数据写入存在时延，可能不返回本字段。在此情况下，建议您等待 10 秒后，将本接口返回的 `image_id` 传入 [/file/image/ad/info/](1740051721711618.html) 或 [/file/image/ad/search/](1740052016789506.html)，查询图片的此项信息。|
|request_id |string|请求的日志id，唯一标识一个请求。 |

示例

(code Success-Response http)
HTTPS/1.1 200 OK
{
    "code": 0,
    "message": "OK",
    "request_id": "{{request_id}}",
    "data": {
        "displayable": false,
        "width": 320,
        "signature": "{{signature}},
        "height": 640,
        "create_time": "{{create_time}}",
        "file_name": "{{file_name}}",
        "image_id": "{{image_id}}",
        "format": "jpeg",
        "modify_time": "{{modify_time}}",
        "image_url": "{{image_url}}",
        "is_carousel_usable": true,
        "material_id": "{{material_id}}",
        "size": 73398
    }
}
(/code);