使用 POST media/upload 端点时,有几个重要概念需要理解。使用 OAuth 上传媒体可能有点棘手,因此我们概述了一些需要记住的事项,以及如何使用此端点的工作示例。

注意事项

  • 因为该方法使用多部分 POST,所以 OAuth 的处理方式不同。计算 OAuth 签名 basestring 或签名时,不使用 POST 或查询字串参数。只使用 oauth_* 参数。
  • 您可以在推文中最多附加 4 张照片、1 个动画 GIF 或 1 段视频。
  • 传输的图像应是图像的原始二进制或经过二进制 base64 编码,只要适当设置了 Content-Type(有疑问时:application/octet-stream),就不需要对内容进行编码或转义。
  • 在发布 base64 编码的图像时,请确保在私信的图像部分上设置“Content-Transfer-Encoding: base64”。
  • 多部分私信边界必须位于自身的行上,并由 CRLF 终止。
  • 对于如何使用此端点 POST 的工作示例,我们建议使用 twurl 进行测试。另外,查看可用的 Twitter 库,包括 large-video-upload-python 库。
  • 使用 JavaScript 在 API 响应中提供的 media_id_string 以及其他无法准确表示长整数的语言。
     

媒体类别

媒体类型参数定义要上传的媒体文件用例,并会影响文件大小限制或其他针对媒体上传的限制。上传媒体时使用正确的媒体类别非常重要,以避免在尝试使用媒体时出现问题。该参数是初始化请求中输入的可选值,属于上传流。如果未指定媒体类别,则将上传的媒体假定为推文媒体(图像、视频或 GIF),具体视内容类型而定。

最常见的媒体类别如下所示:

  • TweetImage
  • TweetVideo
  • TweetGif
  • DmImage
  • DmVideo
  • DmGif
  • Subtitles

如果您是广告 API 合作伙伴,请参阅这些文档,获取关于推广视频的推荐媒体类别的更多信息。

图像规格和建议

图像文件必须满足以下所有标准:

  • 支持的图像媒体类型:JPG、PNG、GIF、WEBP
  • 图像尺寸小于等于 5 MB、动画 GIF 尺寸小于等于 15 MB

上面的文件大小限制由媒体上传端点强制执行。此外,在使用 media_id 调用推文创建(或类似的)端点时,还存在单独的产品实体特定的文件大小限制。 文件大小限制及其他限制可能会随着 media_category 参数的不同而变化。

动画 GIF 建议

GIF 在创建推文时可能会失败,即使未超出文件大小限制。遵循以下限制要求来提高成功率。

  • 分辨率应小于等于 1280x1080(宽 x 高)
  • 帧数小于等于 350
  • 像素数量(宽 * 高 * 帧数)小于等于 3 亿
  • 文件大小小于等于 15 MB

为了处理更大的 GIF,请使用带有 media_category 参数的分块上传端点。此端点允许服务器异步处理 GIF 文件,这是处理较大文件的要求。传递 media_category=tweet_gif 以针对附有动画 GIF 的推文启用异步上传操作。
 

视频规格和建议

请使用异步路径进行媒体上传。

建议:

  • 建议的视频编解码器:H264 High Profile
  • 建议帧率:30 FPS、60 FPS
  • 建议视频分辨率:1280x720(横向)、720x1280(纵向)、720x720(方形)
  • 建议的最小视频码率:5,000 kbps
  • 建议的最小音频码率:128 kbps
  • 建议的音频编解码器:AAC LC
  • 建议纵横比:16:9(横向或纵向)、1:1(方形)

高级设置:

  • 帧率必须等于或小于 60 FPS
  • 尺寸必须介于 32x32 和 1280x1024 之间
  • 文件大小不能超过 512 MB
  • 时长必须在 0.5 秒到 140 秒之间
  • 纵横比必须在 1:3 和 3:1 之间
  • 像素纵横比必须为 1:1
  • 仅支持 YUV 4:2:0 像素格式
  • 音频必须是具有低复杂度配置文件的 AAC。不支持高效的 AAC
  • 音频必须是单声道或立体声,而不是 5.1 或更高
  • 不能有开放式 GOP
  • 必须使用逐行扫描
     

其他信息:

在下面的表中,每一行代表一种上传建议,但并不是强制性要求。所有上传都经过优化处理,适用于多个平台。

方向

宽度

高度

视频码率

音频码率

横向

1280

720

2048K

128K

横向

640

360

768K

64K

横向

320

180

256K

64K

纵向

720

1280

2048K

128K

纵向

360

640

768K

64K

纵向

180

320

256K

64K

方形

720

720

2048K

128K

方形

480

480

768K

64K

方形

240

240

256K

32K


如需了解有关如何上传媒体的示例,请参阅分块媒体上传文档
 

疑难解答

有关媒体 API 的问题,请浏览开发者论坛中的媒体 API 类别获取答案。

Was this document helpful?

感谢

谢谢你的反馈。我们真的很高兴能帮上忙!

Thank you for the feedback. How could we improve this document?

Thank you for the feedback. Your comments will help us improve our documents in the future.