← 返回目录
📁 API Reference › Video

上传视频

您可以使用本接口上传视频到素材库，获得的视频ID可以直接进行广告投放，也可以用于新的素材的制作和生成。

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

如果您上传在广告账户下已存在的视频，接口将会返回已存在视频的信息。

注意
- 我们推荐您在上传视频时开启智能修复。智能修复 API 可以自动检测并修复您视频存在的问题，使其符合投放的素材要求。了解如何开启智能修复，请参阅智能修复。 - 自 2025 年 4 月 24 日起，智能修复将仅对 LOW_RESOLUTION 和 ILLEGAL_VIDEO_SIZE 这两种视频问题类型进行自动修复。智能修复的效果如下： - 分辨率调整： - LOW_RESOLUTION（低分辨率）：若检测到此问题，视频分辨率将自动增加至 1280x720 像素的标准分辨率，也称为 720p。 - ILLEGAL_VIDEO_SIZE（非法视频尺寸）：若检测到此问题，视频将自动调整为以下标准宽高比之一：1:1（方版），9:16（竖版），或 16:9（横版）。 - 输出限制：只会返回一个修复后的视频版本。 - 命名规则：若指定了自定义名称，修复后的视频将根据通过 file_name 参数指定的自定义名称命名。若未指定自定义名称，则遵循默认命名规则（详见 file_name 字段的描述）。

使用前需知

如果上传的视频直接用于广告投放，需要您确认视频符合投放的素材要求。

v1.2与v1.3版本对比

以下表格概括了 v1.2与v1.3接口的变化。 ``xtable |变化内容{30%}|v1.2{35%}|v1.3{35%}| |---|---|---| |接口路径|/v1.2/file/video/ad/upload/|/v1.3/file/video/ad/upload/| |请求参数类型 |advertiser_id: number|advertiser_id: string| |新增请求参数 |/|is_third_party: boolean<br>flaw_detect: boolean<br>auto_fix_enabled: boolean<br>auto_bind_enabled: boolean<br>video_id: string| |返回参数名称|poster_url<br>url|video_cover_url<br>preview_url| |废弃返回参数|/|id| |新增返回参数|/|fix_task_id:string<br>flaw_types: string[]<br>preview_url_expire_time`: string|




## 请求

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

**方法** POST

**Header**

``` xtable
|字段|类型|描述|
|---|---|---|
|Access-Token {必填}|string|授权访问令牌。可以通过[获取访问令牌](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`或`UPLOAD_BY_FILE_ID`时，使用`application/json`。  |

参数

|字段|类型|描述|
|---|---|---|
| advertiser_id {必填}  |string | 广告账户 ID。 |
| file_name | string | 视频名称。<br><br>长度限制： 1-100 个字符。<br><br>默认值： <ul><li>若未启用智能修复（`law_detect` 和 `auto_fix_enabled` 设置为`false` ）：<ul><li>上传本地文件时，默认名称将是原始文件名。</li><li>提供 URL 时，默认名称将是 URL 路径中的文件名部分。</li></ul>若原始文件名或 URL 路径中的文件名部分超过 100 个字符，将仅截取前 100 个字符。</li><li>若启用了智能修复（`law_detect` 和 `auto_fix_enabled` 设置为`true`）：<ul><li>默认名称将是原始文件名（上传本地文件时）或 URL 路径中的文件名部分（提供 URL 时）。若您通过 `file_name` 指定了自定义视频名称，`file_name` 的值将作为修复后视频的名称。 </li></ul></li></ul><br><p><span style="color:darkred"><b>注意</b></span>：同一个广告账户下的视频名称不允许重复。您可以调用[/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`，  ` UPLOAD_BY_VIDEO_ID`。<br><br><p><span style="color:darkred"><b>注意</b></span>：若本字段设置为 `UPLOAD_BY_FILE`，`UPLOAD_BY_URL` 或 `UPLOAD_BY_FILE_ID`, 则将返回新视频 ID（`video_id`）。若使用这三种方式将同一视频上传多次，每次上传均会生成新的视频 ID。 |
| video_file {+条件必填} | file | 当`upload_type`为`UPLOAD_BY_FILE` 时必填。<br><br>视频文件。<br><br>推荐设置： <br data-tomark-pass>(1) 文件大小： 最大 500 MB。<br data-tomark-pass>(2) 比例：9:16, 16:9 和 1:1。<br data-tomark-pass>(3) 格式：.mp4, .mov, .mpeg, .avi。<br><br>示例：`'video_file=@"/Users/admin/Downloads/sample-mov-file.mov"'`<br><br><p><span style="color:darkred"><b>注意</b></span>：上传视频前，请确保视频文件<b>可播放</b>且<b>格式支持</b>。 |
| video_signature {+条件必填} | string | 当`upload_type`为`UPLOAD_BY_FILE` 时必填。<br><br>视频的 MD5（用于服务端校验）。 |
| video_url {+条件必填} | string | 当 `upload_type` 为`UPLOAD_BY_URL` 时必填。<br><br>视频 URL 地址，如http://xxx.xxx。<br>(1) 文件大小：建议 10M 以内。<br>(2) 文件校验：校验返回的 header 中的`Content-Type`。常见的不支持的媒体类型为文本类型（`Content-Type` = text/*，例如text/html，text/plain）。此外，若返回的 header 中设置了`Content -MD5`，也会进行校验。<br>(3) 编码：URL需为浏览器中合法的URL。例如，URL中的空格需编码为`%20`。您可以将URL复制粘贴到浏览器的地址栏，随后URL会自动编码。<br>(4) 比例、格式、分辨率和码率限制同`video_file` 。<br><br><p><span style="color:darkred"><b>注意</b></span>：上传视频前，请确保视频URL<b>可播放</b>且<b>格式支持</b>。若URL无效或格式不支持（如txt格式），将会出现报错，或返回的视频ID无效，无法用于创建广告。</span>|
|file_id{+条件必填}| string | 当`upload_type`为`UPLOAD_BY_FILE_ID`时必填。<br><br>想上传的文件的`file_id`。<br><br>可从[文件上传](https://ads.tiktok.com/marketing_api/docs?id=1737719988918274)接口获取。|
|video_id{+条件必填}|string| 当`upload_type` 为`UPLOAD_BY_VIDEO_ID`时必填。<br><br>视频 ID。<br><br><p><span style="color:darkred"><b>注意</b></span>：您需要传入<b>TikTok广告管理平台</b>或<b>API</b>上传的视频`video_id`。若您传入其他来源的视频ID，将会出现报错，或无法用上传的视频创建广告。<br>您可以从[/file/video/ad/upload/](1737587322856449.html)接口的返回值中，或者使用[/file/video/ad/search/](1740050472224769.html)接口获取视频的`video_id`。 |
|is_third_party|boolean| 视频是否为第三方视频。|
|flaw_detect|boolean|是否自动检测视频的潜在问题。<br><br> 默认值： `false`。|
|auto_fix_enabled|boolean|是否自动修复检测到的问题。 <br><br>默认值 : `false`。<br><br>若检测到视频存在的问题，则：<ul><li>`auto_fix_enabled` 设置为 `false`时，会返回报错信息，提示问题类型 。</li><li>`auto_fix_enabled`设置为 `true`时，会仅自动修复 `LOW_RESOLUTION` 和 `ILLEGAL_VIDEO_SIZE` 类型的问题，并返回  `fix_task_id`和`flaw_types`字段。</li></ul><br><p><span style="color:darkred"><b>注意</b></span>：<ul><li>若视频中检测到 `LOW_RESOLUTION` 问题，视频分辨率将自动增加至 1280x720 像素的标准分辨率，也称为 720p。</li><li>若视频中检测到 `ILLEGAL_VIDEO_SIZE` 问题，视频将自动调整为以下标准宽高比之一：1:1（方版），9:16（竖版），或 16:9（横版）。</li></ul>|
|auto_bind_enabled|boolean|此字段只在`flaw_detect`和`auto_fix_enabled` 均设置为`true`时生效。<br><br>是否自动将修复后的视频上传至素材库。 <br><br>默认值： `false`。|

示例

通过文件上传视频且启用智能修复

(code curl http)
curl --location --request POST 'https://business-api.tiktok.com/open_api/v1.3/file/video/ad/upload/' \
--header 'Access-Token: {{Access-Token}}' \
--form 'advertiser_id="{{advertiser_id}}"' \
--form 'file_name="{{file_name}}"' \
--form 'upload_type="UPLOAD_BY_FILE"' \
--form 'video_file=@"/Desktop/Example.mp4"' \
--form 'video_signature="{{video_signature}}"' \
--form 'flaw_detect="true"' \
--form 'auto_fix_enabled="true"' \
--form 'auto_bind_enabled="true"'
(/code)

通过文件上传视频且不启用智能修复

(code curl http)
curl --location --request POST 'https://business-api.tiktok.com/open_api/v1.3/file/video/ad/upload/' \
--header 'Access-Token: {{Access-Token}}' \
--form 'advertiser_id="{{advertiser_id}}"' \
--form 'file_name="{{file_name}}"' \
--form 'upload_type="UPLOAD_BY_FILE"' \
--form 'video_file=@"/Desktop/Example.mp4"' \
--form 'video_signature="{{video_signature}}"' 
(/code)

通过 URL 上传视频且启用智能修复

(code curl http)
curl --location  --request POST 'https://business-api.tiktok.com/open_api/v1.3/file/video/ad/upload/' \
--header 'Access-Token: {{Access-Token}}' \
--data '{
    "advertiser_id":"{{advertiser_id}}",
    "file_name":"{{file_name}}",
    "upload_type":"UPLOAD_BY_URL",
    "video_url":"{{video_url}}",
    "flaw_detect":true,
    "auto_fix_enabled":true,
    "auto_bind_enabled":true
}'
(/code)

返回

|字段|类型|描述|
|---|---|---|
|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[]|返回数据。由于兼容性原因，会返回数组而不是对象，且数组中仅有一个对象。 <br><p><span style="color:darkred"><b>注意</b></span>：因为主从延迟原因，可能仅返回`video_id`信息。此情况下您可以等待 30 秒至 5 分钟，再使用[/file/video/ad/search/](1740050472224769.html)接口获取其他信息。 |
#|video_cover_url |string|视频封面临时URL。 有效期6小时，过期需重新获取。<br><br>URL中的`x-expires`参数后会包含过期时间，格式为Epoch/Unix时间戳，单位为秒。<br>示例：`http://p16-sign-sg.tiktokcdn.com/v0201/b99a388e3709470be5c~tplv-noop.image?x-expires=<strong>1671742348</strong>&x-signature=FziJhvED9NDTDmPofv3I%3D`。  |
#|format |string|视频格式。  |
#|preview_url |string|视频预览链接。有效期6小时，过期需重新获取。<br><br>若想了解本预览链接的过期时间，请查看`preview_url_expire_time`。 |
#|preview_url_expire_time|string|视频预览链接过期时间，格式为`YYYY-MM-DD HH:MM:SS`(UTC+0)。|
#|file_name |string |视频名称。|
#|displayable|boolean |视频能否在平台中展示。|
#|height |number|视频高度。  |
#|width |number|视频宽度。  |
#|bit_rate |number|码率，单位bps。  |
#|create_time |string |创建时间。UTC 时间，格式：2020-06-10T07:39:14Z。 |
#|modify_time |string |修改时间。UTC 时间，格式：2020-06-10T07:39:14Z。 |
#|signature |string|视频文件MD5。  |
#|duration |float|视频时长，单位秒。  |
#|video_id |string|视频ID，可用于创建广告。<br><br><p><span style="color:darkred"><b>注意</b></span>：<ul><li>若您通过视频 ID 上传视频（`upload_type` 为 `UPLOAD_BY_VIDEO_ID`），将返回同一视频 ID。</li><li> 若您通过文件，URL 或文件 ID 上传视频（`upload_type` 为 `UPLOAD_BY_FILE`，`UPLOAD_BY_URL` 或 `UPLOAD_BY_FILE_ID`）则将返回新视频 ID（`video_id`）。若使用这三种方式将同一视频上传多次，每次上传均会生成新的视频 ID。</li></ul>|
#|size |number|视频大小，单位Byte。  |
#|material_id|string|素材ID。|
#|allowed_placements |string[] |视频可投放版位。受音乐版权限制，创意工具工具生成的部分素材只能投放到 TikTok 版位。投放到其他版位时将会导致审核不通过。枚举值详见[枚举值-广告管理-版位](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138)。<br><p><span style="color:darkred"><b>注意</b></span>：本字段的枚举值`PLACEMENT_TOPBUZZ`和 `PLACEMENT_HELO`无法用于创建广告，且将在下个API版本中废弃。 |
#|allow_download |boolean |视频是否允许下载。受音乐版权限制，创意工具生成的部分素材只允许预览，禁止下载和传播。 |
#|fix_task_id|string|仅在请求中`flaw_detect`和 `auto_fix_enabled`都设置为`true`，且检测到视频中的问题时返回。<br><br>修复任务 ID。<br><br>若想获取修复后的视频，可使用以下方法之一：<ul><li>将本字段的值传给 [/video/fix/task/get/](1741469487859714.html) 接口的 `task_id` 字段。</li><li>若请求中已将 `auto_bind_enabled` 设置为 `true` ，可以通过调用 [/file/video/ad/search/](1740050472224769.html) 检索修复后的视频。</li></ul>|
#|flaw_types|string[]|仅在请求中`flaw_detect`和 `auto_fix_enabled`都设置为`true`，且检测到视频中的问题时返回。视频问题种类。 <br><br>枚举值：<ul><li>`LOW_RESOLUTION`：视频分辨率低于540 x 960 像素, 不符合要求。</li><li>`ILLEGAL_VIDEO_SIZE`：视频尺寸的比例不符合竖版（9:16），方版（1:1），横版（16:9）的要求。</li><li>`NO_BGM`（<span style="color:Red">已废弃</span>）：广告或视频没有背景音乐，或背景音乐不连贯/不清晰。</li><li>`BLACK_EDGE`（<span style="color:Red">已废弃</span>）：视频画面中出现影响用户体验的黑边。</li><li>`ILLEGAL_DURATION`（<span style="color:Red">已废弃</span>）：视频长度长于 60 秒或短于 5 秒，不符合要求。|

示例

通过文件上传视频且启用智能修复，最终检测到问题

(code curl http)
HTTPS/1.1 200 OK
{
    "code": 0,
    "message": "OK",
    "request_id": "{{request_id}}",
    "data": [
        {
            "fix_task_id": "{{fix_task_id}}",
            "flaw_types": [
                "LOW_RESOLUTION"
            ]
        }
    ]
}
(/code)

通过文件上传视频且不启用智能修复

注意
因为主从延迟原因，可能仅返回 video_id 信息。此情况下您可以等待 30 秒至 5 分钟，再使用/file/video/ad/search/接口获取其他信息。

(code curl http)
HTTPS/1.1 200 OK
{
    "code": 0,
    "message": "OK",
    "request_id": "{{request_id}}",
    "data": [
        {
            "video_id": "{{video_id}}"
        }
    ]
}
(/code)

通过文件上传视频且启用智能修复，最终检测到问题

(code curl http)
HTTPS/1.1 200 OK
{
    "code": 0,
    "message": "OK",
    "request_id": "{{request_id}}",
    "data": [
        {
            "fix_task_id": "{{fix_task_id}}",
            "flaw_types": [
                "ILLEGAL_VIDEO_SIZE"
            ]
        }
    ]
}
(/code)
← 获取视频推荐封面更新视频名称 →

内容来源：TikTok API for Business 官方文档 · 本地归档

在接这个接口时卡住了？
Stuck wiring this API into production? We build ad-delivery tooling on these platforms — campaign automation, reporting pipelines, error-handling and migration between API versions.
联系我们 · Talk to us 每日平台更新简报 →