第四章 视频管理API：从上传到数据分析

视频管理这块，说实话是抖音开放平台里最核心也最折腾人的部分。我当年第一次对接时，光分片上传就踩了三天坑。今天咱们把这四个接口讲透——上传、发布、删除、数据查询，一条龙搞定。

4.1 视频上传（分片上传）

抖音的视频上传，不是简单丢个文件就完事。它用的是分片上传机制。为什么要分片？你想想看，一个高清视频动不动几百兆，网络稍微抖一下就得重传，用户体验极差。

分片上传的核心流程分三步：

  1. 初始化上传：告诉抖音我要传个视频，拿到上传凭证
  2. 上传分片：把视频切成小块，一块一块传
  3. 合并分片：全部传完后，通知抖音合并

重要提醒：每个分片大小建议控制在4MB左右。我试过1MB和8MB，1MB太慢，8MB容易超时。4MB是个平衡点。

先看初始化上传的代码：

// 初始化分片上传
POST https://open.douyin.com/video/upload/init/
Content-Type: application/json

{
  "access_token": "your_access_token",
  "open_id": "your_open_id",
  "file_size": 104857600,  // 100MB
  "file_name": "my_video.mp4",
  "chunk_size": 4194304    // 4MB
}

// 返回示例
{
  "data": {
    "upload_id": "UPLOAD_20240315_ABC123",
    "chunk_count": 25,
    "status": "init_success"
  }
}

拿到 upload_id 后，就开始传分片。每个分片要带上序号：

// 上传单个分片
POST https://open.douyin.com/video/upload/chunk/
Content-Type: multipart/form-data

参数：
- access_token: your_access_token
- open_id: your_open_id
- upload_id: UPLOAD_20240315_ABC123
- chunk_number: 1  // 从1开始
- video: (二进制文件数据)

我的经验：上传分片时，建议用并发控制。别一口气全发出去，服务器扛不住。我一般用3-5个并发，配合重试机制。曾经有个项目并发开到10，结果抖音那边直接返回429限流了。

所有分片传完后，调用合并接口：

// 合并分片
POST https://open.douyin.com/video/upload/complete/
Content-Type: application/json

{
  "access_token": "your_access_token",
  "open_id": "your_open_id",
  "upload_id": "UPLOAD_20240315_ABC123"
}

// 返回
{
  "data": {
    "video_id": "VIDEO_987654",
    "status": "upload_success"
  }
}

4.2 视频发布

上传成功不等于发布成功。你拿到 video_id 后，还得调用发布接口。这一步很多人会忘，包括我刚开始对接时也犯过这错。

// 发布视频
POST https://open.douyin.com/video/publish/
Content-Type: application/json

{
  "access_token": "your_access_token",
  "open_id": "your_open_id",
  "video_id": "VIDEO_987654",
  "title": "我的第一个抖音API视频",
  "description": "通过开放平台发布的视频",
  "cover_url": "https://example.com/cover.jpg",
  "topics": ["技术分享", "API教程"],
  "location": {
    "longitude": 116.397128,
    "latitude": 39.916527
  }
}

注意：cover_url 必须是可公开访问的图片链接。我之前用内网地址传上去，结果封面显示不出来，排查了半天才发现是这个问题。

发布接口返回后，视频不会立刻出现在用户主页。抖音需要审核，一般几分钟到几小时不等。你可以通过视频数据查询接口看状态。

4.3 视频删除

删除接口相对简单，但有个坑——删除后视频ID就失效了，无法恢复。我建议在删除前先做一次数据备份。

// 删除视频
POST https://open.douyin.com/video/delete/
Content-Type: application/json

{
  "access_token": "your_access_token",
  "open_id": "your_open_id",
  "video_id": "VIDEO_987654"
}

// 成功返回
{
  "data": {
    "status": "delete_success"
  }
}

删除后，建议再查一次确认状态。我曾经遇到过返回成功但视频还在的情况，后来发现是网络超时导致实际没删掉。

4.4 视频数据查询

这个接口是运营同学的最爱。播放量、点赞数、评论数、分享数，全都能拿到。

// 查询单个视频数据
GET https://open.douyin.com/video/data/
?access_token=your_access_token
&open_id=your_open_id
&video_id=VIDEO_987654

// 返回示例
{
  "data": {
    "video_id": "VIDEO_987654",
    "statistics": {
      "play_count": 15234,
      "like_count": 892,
      "comment_count": 156,
      "share_count": 234,
      "forward_count": 45,
      "collect_count": 678
    },
    "status": "published",
    "create_time": 1710489600
  }
}

也可以批量查询，一次最多查10个视频：

// 批量查询
POST https://open.douyin.com/video/data/batch/
Content-Type: application/json

{
  "access_token": "your_access_token",
  "open_id": "your_open_id",
  "video_ids": ["VIDEO_111", "VIDEO_222", "VIDEO_333"]
}
字段 说明 更新频率
play_count 播放量 实时
like_count 点赞数 实时
comment_count 评论数 约5分钟延迟
share_count 分享数 约10分钟延迟

避坑指南：数据查询接口有频率限制，每分钟最多60次。我曾经写了个死循环去轮询播放量，结果被限流了整整一小时。建议用定时任务，每5-10分钟查一次就够了。

4.5 完整流程串联

嗯，到这里四个接口都讲完了。咱们串起来看看完整流程：

  1. 初始化上传 → 拿到 upload_id
  2. 循环上传分片 → 每个分片带序号
  3. 合并分片 → 拿到 video_id
  4. 调用发布接口 → 设置标题、封面等
  5. 等待审核 → 通过数据查询接口看状态
  6. 需要删除时 → 调用删除接口
  7. 日常运营 → 定时拉取播放量、点赞数

我个人习惯把这几步封装成一个服务类，对外只暴露一个 publishVideo(file, title) 方法。内部处理分片、重试、状态轮询，调用方完全不用关心细节。

最后说一句，抖音的API文档更新挺频繁的。我去年写的代码，今年再看接口地址都变了。建议定期查看官方文档，或者加个版本号在请求头里，方便排查问题。

下一章咱们聊评论管理API，那个更刺激——删除评论、置顶、回复，全是运营刚需。

← 上一章 📖 返回目录 下一章 →