面向开发者的YouTube Data API上传指南（2026）
YouTubeAPI开发者

面向开发者的YouTube Data API上传指南（2026）

videos.insert 如何工作、为什么未验证的项目只能上传私享视频、 可续传上传的具体流程，以及一次 videos.insert 消耗多少配额。

YouTube Data API通过 videos.insert 上传视频，有两个有据可查的事实决定了它对你的产品是否可行。2020年7月28日之后创建的未验证API项目上传的视频，会被限制为私享模式，直到该项目通过审核为止。而且 videos.insert 使用的是它自己每天100次调用的独立配额桶，与其余API共用的10,000单位配额池是分开的。

把这两点放在一起看，情况就很清楚了：没有通过审核，你就无法公开发布；没有获得配额提升，你就无法频繁发布。

YouTube Data API能发布什么，审核门槛又是什么？

videos.insert 上传视频文件并设置其元数据：标题、描述、标签、分类，以及 privacyStatus（可为 public、private 或 unlisted）。文档标注的最大文件大小为256GB，支持的MIME类型为 video/* 和 application/octet-stream。

这里的门槛就是审核。Google的文档指出，2020年7月28日之后创建的未验证API项目上传的视频，会被限制为私享模式，直到该项目通过审核。实际情况是：在开发阶段，你的集成能够端到端跑通，会生成一个真实的视频ID，但这条视频除了频道所有者以外，任何人都看不到。通过审核之后，这个限制才会被解除，privacyStatus: 'public' 才会真正生效。

提示： 本文数据是截至2026年9月，对照 developers.google.com/youtube 核实的。各平台可能随时调整这些数据，不另行通知。

问题文档给出的答案
上传接口POST https://www.googleapis.com/upload/youtube/v3/videos
权限范围youtube.upload、youtube、youtubepartner 或 youtube.force-ssl
最大文件大小256GB
MIME类型video/*、application/octet-stream
隐私状态取值public、private、unlisted
未验证项目上传的视频被限制为私享，直到该项目通过审核

认证模型是怎样的，审核需要多久？

标准的带离线访问的OAuth 2.0流程。你将频道所有者跳转到Google的授权页面，请求 https://www.googleapis.com/auth/youtube.upload 权限，用授权码换取访问令牌和刷新令牌，并在访问令牌过期时进行刷新。

由于上传权限属于敏感权限范围，你的项目除了要通过YouTube API审核之外，还需要通过Google的OAuth验证。这是两项独立的审核，人们经常把它们搞混：OAuth验证管辖的是授权页面以及有多少用户可以授予该权限，而YouTube审核管辖的是你的上传内容是否能被设为私享以外的状态。

我们在官方文档中没能找到关于YouTube API审核处理时长的公开说明，因此不会给出一个具体数字。请假设它是以周为单位计算的，而不是以天为单位，并在需要之前就提前启动审核流程。

实际的上传流程是怎样的？

上传支持续传：你先打开一个上传会话，然后把字节数据发送到该会话的URI。视频随后会在你的请求完成之后，在YouTube这一端进行异步处理。

  1. 打开一个可续传会话。 向上传接口发送 POST 请求，附上JSON格式的视频元数据，并设置 uploadType=resumable。响应会在 Location 响应头中返回一个会话URI。请注意，uploadType=resumable 和 Location 会话URI是Google通用的可续传上传机制，而不是YouTube专属上传页面所记录的内容，该页面只展示了Python客户端库的用法。
  2. 将字节数据PUT到该会话URI，可以一次性发送，也可以分块发送。分块可以让你在网络故障后从断点续传，而不必重新上传整个大文件。
  3. 从最终响应中读取视频ID。 此时上传已经完成。
  4. 轮询处理状态。 YouTube会进行异步转码。视频ID在视频可被观看之前就已经存在，而处理过程可能在上传成功之后失败。
# 1. open the resumable session
curl -X POST \
  "https://www.googleapis.com/upload/youtube/v3/videos?uploadType=resumable&part=snippet,status" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Upload-Content-Type: video/mp4" \
  -d '{"snippet":{"title":"Release notes","categoryId":"28"},
       "status":{"privacyStatus":"private"}}' -D -

# 2. PUT the bytes to the Location URI returned above
curl -X PUT "$SESSION_URI" \
  -H "Content-Type: video/mp4" --data-binary @video.mp4

# 3. then poll videos.list for processing status using the returned video id

Google自己的上传指南是一个基于 MediaFileUpload、设置 resumable=True 并在重试时使用指数退避的Python示例，而且它明确说明该示例脚本没有做任何错误处理。请照字面理解这句话：这个示例只是一个起点，而不是可用于生产环境的模板。

提示： 本文数据是截至2026年9月，对照 developers.google.com/youtube 核实的。各平台可能随时调整这些数据，不另行通知。

一次上传消耗多少配额？

这是让大多数YouTube集成计划止步的数字，值得精确说明。

方法配额消耗
videos.insert1个单位，来自每天100次调用的专属配额桶
videos.list1个单位
thumbnails.set50个单位
videos.update50个单位

按Google的原话，默认分配是”每天100次 search.list 调用，100次 videos.insert 调用，以及所有其他接口共用的每天10,000个单位”。

因此，发布的硬性约束是一个计数值，而不是单位算术：每个项目每天100次上传。10,000单位的配额池是独立的，需要覆盖这些上传前后的所有状态轮询、元数据读取和缩略图设置，相比之下这部分是比较宽裕的。配额在太平洋时间午夜重置。一个服务超过少数几个频道的多租户产品，需要向Google另行提交配额提升申请。

一些较旧的指南（部分至今仍在线）声称 videos.insert 会消耗共享10,000单位配额池中的1,600个单位，换算下来相当于每天六次上传。这已经不是Google当前配额文档的说法了，如果你的预算是按这个旧说法设计的，值得重新核查一下。

提示： 本文数据是截至2026年9月，对照 developers.google.com/youtube 核实的。各平台可能随时调整这些数据，不另行通知。

真正会耗费你三周时间的是什么

  • 两项审核，而不是一项。 敏感上传权限所需的OAuth验证，以及解除私享上传限制所需的YouTube API审核。两者都没有公开的处理时长，两者都会阻塞上线进度。
  • 配额，以及提升配额的申请。 每个项目每天100次上传，一旦你为超过几十个频道提供服务，这个额度就不够用于生产环境。提升申请需要填表、说明理由，然后等待。
  • 在触达Google之前就要完成的转码工作。 接受任意用户视频，意味着需要统一容器格式和编码，生成缩略图，并把文件存放在能够流式传输256GB内容、而不会把整个文件缓冲进内存的地方。
  • 上传成功之后的异步失败。 这一点最容易让人意外。返回200和一个视频ID，只说明字节数据已经到达，并不代表视频已经上线。处理过程之后仍可能失败，一次被拒绝的上传会以处理状态的形式呈现，而不是以HTTP错误的形式呈现。你需要一个轮询器、一个”processing”帖子状态，以及一种方式，在你的API调用成功一小时之后，告诉用户他们的视频处理失败了。

如果你还计划把同一段竖版视频推送到其他网络，相关工作的形态在将Instagram Reels跨平台发布到YouTube Shorts和一次性发布到TikTok、Reels和Shorts两篇文章中有介绍。每个平台都有各自的审核、各自的配额模型和各自的异步失败模式，这正是问题所在。

简而言之

  • videos.insert 上传至 https://www.googleapis.com/upload/youtube/v3/videos，最大256GB，权限范围为 youtube.upload。
  • 2020年7月28日之后创建的未验证项目，只能上传私享视频，直到该项目通过审核。
  • 流程是：打开一个可续传会话，PUT字节数据，然后轮询，因为处理过程是异步的，可能在上传成功之后失败。
  • videos.insert 消耗每天100次调用专属配额桶中的1个单位。另有独立的每天10,000单位覆盖其余所有操作。
  • 没有公开的审核处理时长，请在需要之前就提前启动审核。

一次搞定，而不是每个平台各搞一次

上面这些围绕YouTube的工作是实打实的，而且没有一项能套用到下一个平台。Pinterest有自己的审核，TikTok有自己的Content Posting API审计，每个平台都有各自独立的媒体处理流程。而这种重复劳动，正是我们的API所消除的：BulkPublish 通过一个统一的REST接口发布到15个平台，OAuth、令牌刷新、媒体处理和异步状态追踪都由我们这一侧统一处理。帖子状态包括”processing”和”partial”，正是因为返回200并不等于发布成功。

开发者文档列出了各个接口，REST API集成页面介绍了认证方式和帖子的生命周期。如果你只需要定时发布而不需要自行集成，如何定时发布YouTube视频一文有相关介绍，免费的YouTube字符计数器可以检查标题和描述是否符合限制。

相关阅读