教程
上传媒体
简单上传
简单上传端点只能用于上传图像。
twurl -X POST -H upload.twitter.com "/1.1/media/upload.json?media_category=TWEET_IMAGE&additional_owners=3805104374" -f adsapi-heirarchy.png -F media
{
"media_id": 931270813906374700,
"media_id_string": "931270813906374657",
"media_key": "3_931270813906374657",
"size": 95294,
"expires_after_secs": 86400,
"image": {
"image_type": "image/png",
"w": 1000,
"h": 600
}
}
-f 是文件本身,而 -F 是指文件字段类型。
然后,可使用 media_id_string 和 media_key 值将此图像附于任何推文或卡片对象。
分块上传
顾名思义,多部分分块上传端点是一个多部分上传的进程。此端点是为了允许执行可恢复的上传,而特意设计的。
例如,将视频上传至认证用户的 Twitter 用户,并与该同一实体共享 @furni 账号。但首先,我们需要确定所上传文件包含的总字节数:
stat -f%z ~/Desktop/sample-video.mp4
514065
超过 1MB(最大分块大小)的文件可这样分解为若干小块:
split -b 5m ~/Desktop/sample-video.mp4
该上传本身包含一系列的调用,如下所示:
INIT
twurl -X POST -H upload.twitter.com "/1.1/media/upload.json?additional_owners=3805104374" -d
"command=INIT&media_type=video/mp4&media_category=amplify_video&total_bytes=5678971"
additional_owners 字段设置为 @furni 账号的用户 ID。此外,media_category 可用于设置所上传媒体的类型,它可以是 Gif 动图、视频或增效视频(或前置广告视频)。用户的用户 ID 可从 GET users/show 端点进行检索。
注意:如果上传的视频时长 > 140 秒或在 Twitter 广告活动中被用作素材,则要求使用 amplify_video 媒体类别。为了上传长视频,需要将 @handle 添加到允许列表。
{
"media_id": 931263015239934000,
"media_id_string": "931263015239933952",
"expires_after_secs": 86399,
"media_key": "7_931263015239933952"
}
所有后续调用均需要 media_id_string 值。
APPEND
必须尽可能地多次调用 APPEND 命令,直至文件的所有分块(最大 1MB)均完成上传。各调用需修改 segment_index 值。
twurl -X POST -H upload.twitter.com "/1.1/media/upload.json" -d "command=APPEND&media_id=931263015239933952&segment_index=0" --file ~/Desktop/sample-video.mp4 --file-field "media"
Twurl 提供了一些有用的助手,例如 -f 旗帜用于指定所上传的媒体,--file-field 旗帜用于指定所上传文件为媒体文件。注意,此端点没有响应体。所有其他标题仍然可用。
FINALIZE
完成上传程序的最后一个调用如下:
twurl -X POST -H upload.twitter.com "/1.1/media/upload.json" -d "command=FINALIZE&media_id=931263015239933952"
{
"media_id": 931263015239934000,
"media_id_string": "931263015239933952",
"media_key": "7_931263015239933952",
"size": 514065,
"expires_after_secs": 86400,
"processing_info": {
"state": "pending",
"check_after_secs": 5
}
}
processing_info 字段可用于确定文件是否已经备好可供使用。一旦 state 设置为“已成功”,文件便可供使用。媒体上传状态端点可用于检查上传的当前状态。
twurl -t -X GET -H upload.twitter.com "/1.1/media/upload.json?command=STATUS&media_id=931263015239933952"
{
"media_id": 931263015239934000,
"media_id_string": "931263015239933952",
"media_key": "7_931263015239933952",
"size": 514065,
"expires_after_secs": 83510,
"video": {
"video_type": "video/mp4"
},
"processing_info": {
"state": "succeeded",
"progress_percent": 100?
}
}
一旦视频成功上传,media_id_string 或 media_key 可用于将媒体实体与推文或卡片关联。
可重复相同的步骤来上传 Gif 动图,唯一的变化是 video_type 的 image/gif 和 media_category 的 TWEET_GIF
将媒体与推文关联
一旦完成上传媒体的全部步骤,则可以这样将媒体实体附于推文中
twurl "/1.1/statuses/update.json" -d "media_ids= 931263015239933952&text=Sample Tweet with media_ids and twurl"
此外,请阅读我们的媒体最佳实践指南,了解支持的文件格式等其他详细信息。
准备好构建你的解决方案了吗?