通过文件 URL 上传商品库视频

您可以使用本接口以文件 URL 的方式上传商品库视频，商品库视频将通过异步任务与电商商品库绑定。您将会从接口返回中得到一个任务处理 ID（feed_log_id）。通过该ID您可以调用 /catalog/video/log/ 查看任务的处理状态和最终结果。

目前本接口只允许上传包含视频 URL 的 CSV 格式文件。 商品库视频上传的 CSV 模板为catalog_video_template。

注意
本接口只能同时处理一个文件任务，若当前任务未完成，新的任务会提交失败。请等待当前任务处理完成后再发送下一个任务。

使用前需知

您需已拥有一个包含可用于广告投放的商品的电商商品库。

若您尚未拥有符合条件的电商商品库，您可按照通过 JSON 结构向不同类型的商品库上传商品中的步骤创建商品库并上传商品。

请求

地址 https://business-api.tiktok.com/open_api/v1.3/catalog/video/file/

方法 POST

Header

|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
|Access-Token {必填}|string|授权访问令牌。可以通过[获取访问令牌](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162)接口获取。|
|Content-Type {必填}|string|请求信息类型。<br>允许格式：`application/json`。|

参数

|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
| bc_id {必填} | string | 商务中心 ID。<br><br>若想获取您有权访问的商务中心列表，可使用[/bc/get/](1737115687501826.html)。 |
| catalog_id{必填} | string | 商品库 ID。<br><br>若想获取某个商务中心中的电商商品库列表，可使用 [/catalog/get/](1740315452868610.html)，筛选对应的 `catalog_type` 为 `ECOM` 的 `catalog_id`值。<br><br>您需对商品库有商品库管理（目录管理）权限。若想获取您有商品库管理权限的商品库， 可使用[/bc/asset/get/](1739432717798401.html)。将`asset_type` 设置为 `CATALOG`，筛选对应的 `catalog_role` 为 `ADMIN` 的 `asset_id` 值。 |
| file_url {必填}| string | CSV 文件的下载地址。 <br><br>商品库视频上传的 CSV 模板为[catalog_video_template](https://bytedance.sg.larkoffice.com/sheets/PcBjsyYxahFGMqteR3jl3lv8gKh)。 <br><br>若想查看每个商品库视频参数的具体描述，请查看<a href="#item-link-商品库视频参数">商品库视频参数</a>。|
| advertiser_ids | string[] | 视频同步的目标广告账号 ID 列表。 <br>同步完成后，视频将存在于广告账号的素材库中。若您不想将商品库视频同步至广告账号中，则无需传入本字段。 <br><br>最大数量：100。<br><br>广告账号和商品库（`catalog_id`）需在同一商务中心（`bc_id`）中，且您需对广告账号有管理员或操作员权限。不合法的广告账号将被忽略。若想获取您有管理员或操作员权限的 广告账号，可使用[/bc/asset/get/](1739432717798401.html)。将 `asset_type` 设置为 `ADVERTISER`，并筛选 `advertiser_role`为 `ADMIN` 或 `OPERATOR` 的 `asset_id` 值。 |

商品库视频参数

下表列出了您可在 file_url 对应的 CSV 模板中为您的商品库视频指定的参数及其描述。

|字段{30%}|类型{15%}|描述{55%}|
|--- |--- |--- |
| video_name  {必填}  | string | 视频名称。 <br><br>长度限制：500 个字符。|
| video_link {必填} | string | 视频文件的 URL。  <br><br>文件大小限制：100 MB。<ul><li>对于 TikTok 版位：<ul><li>宽高比要求： 横版（16:9） / 方版（1:1）/ 竖版（9: 16）</li><li>分辨率： 横版（最低 960*540） / 方版（最低 640*640）/ 竖版（最低 540*960）</li><li>码率: > 516.00 kbps </li><li>时长：5-60 秒 </li><li>  安全区域：左侧 44px，右侧 140px，顶部 130px，底部 483-484px </li></ul></li><li>对于全球化应用组合和 Pangle 版位：<ul><li> 推荐时长：5-60 秒 </li></ul></li></ul><br>示例： https://www.tiktok.com/tiktok_t_shirt.mp4 |
| sku_id_list {必填} | string[] | 要与该视频（`video_link`）绑定的电商商品库商品的 SKU ID 列表。 <br><br>最大数量：20。<br><br> 若要指定多个 SKU ID，需在 ID 之间添加英文逗号。  <br><br>示例：`SKU_ID_1,SKU_ID_2,SKU_ID_3,SKU_ID_4`。 <br><br>若想获取可用于广告中的电商商品库商品，可使用[/catalog/product/get/](1740564136678402.html)。若商品返回的`ad_creation_eligible` 为 `AVAILABLE`，则您可在广告中使用该商品。 |
| category | string | 视频的商品类别。<br><br>长度限制：500 个字符。若字段值超过长度限制，则本字段值将覆盖成 null。<br><br>示例：`Apparel & Accessories> Clothing> Shirts`。 |
| brand | string | 视频的品牌名称。<br><br>长度限制：500 个字符。若字段值超过长度限制，则本字段值将覆盖成 null。<br><br>示例：TikTok. |
| creator | string | 视频的创作者。<br><br>长度限制：500 个字符。若字段值超过长度限制，则本字段值将覆盖成 null。<br><br> 示例：TikTok Creator. |
| video_type | string | 视频的类型。<br><br> 长度限制：500 个字符。若字段值超过长度限制，则本字段值将覆盖成 null。<br><br> 示例：Promotional video. |
| description | string | 视频的简短描述。<br><br> 长度限制：500 个字符。若字段值超过长度限制，则本字段值将覆盖成 null。|
| landing_page_url | string | 可浏览及购买与该视频关联的商品的落地页 URL。<br><br> 示例：https://www.landingpage.com |
| custom_label_0 | string |视频的其他信息。<br><br>无长度限制。 |
| custom_label_1 | string | 视频的其他信息。<br><br>无长度限制。 |
| custom_label_2 | string | 视频的其他信息。<br><br>无长度限制。 |
| custom_label_3 | string | 视频的其他信息。<br><br>无长度限制。 |
| custom_label_4 | string | 视频的其他信息。<br><br>无长度限制。 |

示例

(code curl http)
curl --location --request POST 'https://business-api.tiktok.com/open_api/v1.3/catalog/video/file/' \
--header 'Access-Token: {{Access-Token}}' \
--header 'Content-Type: application/json' \
--data '{
    "bc_id": "{{bc_id}}",
    "catalog_id": "{{catalog_id}}",
    "advertiser_ids": ["{{advertiser_id}}"],
    "file_url": "{{file_url}}"
}'
(/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)。 |
|request_id |string| 请求的日志ID，唯一标识一个请求。 |
|data |object| 返回数据。 |
#| feed_log_id| string | 商品库视频处理日志的 ID。<br><br>若想查询商品库视频上传的处理状态和最终结果，可使用[/catalog/video/log/](1803655061642242.html)。

示例

(code Success-Response http)
HTTPS/1.1 200 OK
{
    "code": 0,
    "message": "OK",
    "request_id": "{{request_id}}",
    "data": {
        "feed_log_id": "{{feed_log_id}}"
    }
}
(/code)