平時運營微信公眾平台時有沒發現素材管理有點不太好操作,特別是素材一多,找個東西都翻半天。現在好了,微信宣布公眾平台新增素材管理接口,對所有認證公眾號開放,方便快捷,可以實現同步互通。(4.29更新第三方平台也能為未微信認證的訂閱號調用自定義菜單接口和素材管理接口)
微信公眾平台素材管理接口具體如下:
-
新增臨時素材
公眾號經常有需要用到一些臨時性的多媒體素材的場景,例如在使用接口特別是發送消息時,對多媒體文件、多媒體消息的獲取和調用等操作,是通過media_id來進行的。素材管理接口對所有認證的訂閱號和服務號開放。通過本接口,公眾號可以新增臨時素材(即上傳臨時多媒體文件)。但請注意,每個多媒體文件(media_id)會在開發者上傳或粉絲發送到微信服務器3天后自動刪除(所以用戶發送給開發者的素材,若開發者需要,應盡快下載到本地),以節省服務器資源。請注意,media_id是可復用的。
本接口即為原“上傳多媒體文件”接口。
接口調用請求說明
http請求方式: POST/FORM,需使用https https://api.weixin.qq.com/cgi-bin/media/upload?access_token=ACCESS_TOKEN&type=TYPE 調用示例(使用curl命令,用FORM表單方式上傳一個多媒體文件): curl -F media=@test.jpg "https://api.weixin.qq.com/cgi-bin/media/upload?access_token=ACCESS_TOKEN&type=TYPE"
參數說明
參數 是否必須 說明 access_token 是 調用接口憑證 type 是 媒體文件類型,分別有圖片(image)、語音(voice)、視頻(video)和縮略圖(thumb) media 是 form-data中媒體文件標識,有filename、filelength、content-type等信息 返回說明
正確情況下的返回JSON數據包結果如下:
{"type":"TYPE","media_id":"MEDIA_ID","created_at":123456789}
參數 描述 type 媒體文件類型,分別有圖片(image)、語音(voice)、視頻(video)和縮略圖(thumb,主要用於視頻與音樂格式的縮略圖) media_id 媒體文件上傳后,獲取時的唯一標識 created_at 媒體文件上傳時間戳 錯誤情況下的返回JSON數據包示例如下(示例為無效媒體類型錯誤):
{"errcode":40004,"errmsg":"invalid media type"}
注意事項
上傳的臨時多媒體文件有格式和大小限制,如下:
- 圖片(image): 1M,支持JPG格式
- 語音(voice):2M,播放長度不超過60s,支持AMR\MP3格式
- 視頻(video):10MB,支持MP4格式
- 縮略圖(thumb):64KB,支持JPG格式
媒體文件在后台保存時間為3天,即3天后media_id失效。
-
獲取臨時素材
公眾號可以使用本接口獲取臨時素材(即下載臨時的多媒體文件)。請注意,視頻文件不支持https下載,調用該接口需http協議。本接口即為原“下載多媒體文件”接口。
接口調用請求說明
http請求方式: GET,https調用 https://api.weixin.qq.com/cgi-bin/media/get?access_token=ACCESS_TOKEN&media_id=MEDIA_ID 請求示例(示例為通過curl命令獲取多媒體文件) curl -I -G "https://api.weixin.qq.com/cgi-bin/media/get?access_token=ACCESS_TOKEN&media_id=MEDIA_ID"
參數說明
參數 是否必須 說明 access_token 是 調用接口憑證 media_id 是 媒體文件ID 返回說明
正確情況下的返回HTTP頭如下:
HTTP/1.1 200 OK Connection: close Content-Type: image/jpeg Content-disposition: attachment; filename="MEDIA_ID.jpg" Date: Sun, 06 Jan 2013 10:20:18 GMT Cache-Control: no-cache, must-revalidate Content-Length: 339721 curl -G "https://api.weixin.qq.com/cgi-bin/media/get?access_token=ACCESS_TOKEN&media_id=MEDIA_ID"
錯誤情況下的返回JSON數據包示例如下(示例為無效媒體ID錯誤)::
{"errcode":40007,"errmsg":"invalid media_id"}
-
新增永久素材
除了3天就會失效的臨時素材外,開發者有時需要永久保存一些素材,屆時就可以通過本接口新增永久素材。請注意:
1、新增的永久素材也可以在公眾平台官網素材管理模塊中看到 2、永久素材的數量是有上限的,請謹慎新增。圖文消息素材和圖片素材的上限為5000,其他類型為1000 3、調用該接口需https協議
新增永久圖文素材
接口調用請求說明
http請求方式: POST https://api.weixin.qq.com/cgi-bin/material/add_news?access_token=ACCESS_TOKEN
調用示例
{ "articles": [{ "title": TITLE, "thumb_media_id": THUMB_MEDIA_ID, "author": AUTHOR, "digest": DIGEST, "show_cover_pic": SHOW_COVER_PIC(0 / 1), "content": CONTENT, "content_source_url": CONTENT_SOURCE_URL }, //若新增的是多圖文素材,則此處應還有幾段articles結構 ] }
參數說明
參數 是否必須 說明 title 是 標題 thumb_media_id 是 圖文消息的封面圖片素材id(必須是永久mediaID) author 是 作者 digest 是 圖文消息的摘要,僅有單圖文消息才有摘要,多圖文此處為空 show_cover_pic 是 是否顯示封面,0為false,即不顯示,1為true,即顯示 content 是 圖文消息的具體內容,支持HTML標簽,必須少於2萬字符,小於1M,且此處會去除JS content_source_url 是 圖文消息的原文地址,即點擊“閱讀原文”后的URL 返回說明
{ "media_id":MEDIA_ID }
返回的即為新增的圖文消息素材的media_id。
新增其他類型永久素材
接口調用請求說明
通過POST表單來調用接口,表單id為media,包含需要上傳的素材內容,有filename、filelength、content-type等信息。請注意:圖片素材將進入公眾平台官網素材管理模塊中的默認分組。
http請求方式: POST http://file.api.weixin.qq.com/cgi-bin/material/add_material?access_token=ACCESS_TOKEN 調用示例(使用curl命令,用FORM表單方式新增一個其他類型的永久素材): curl -F media=@test.jpg "http://file.api.weixin.qq.com/cgi-bin/material/add_material?access_token=ACCESS_TOKEN"
參數說明
參數 是否必須 說明 access_token 是 調用接口憑證 type 是 媒體文件類型,分別有圖片(image)、語音(voice)、視頻(video)和縮略圖(thumb) media 是 form-data中媒體文件標識,有filename、filelength、content-type等信息 新增永久視頻素材需特別注意
在上傳視頻素材時需要POST另一個表單,id為description,包含素材的描述信息,內容格式為JSON,格式如下:
{ "title":VIDEO_TITLE, "introduction":INTRODUCTION }
新增永久視頻素材的調用示例:
curl "http://file.api.weixin.qq.com/cgi-bin/material/add_material?access_token=ACCESS_TOKEN" -F media=@media.file -F description='{"title":VIDEO_TITLE, "introduction":INTRODUCTION}'
參數說明
參數 是否必須 說明 title 是 視頻素材的標題 introduction 是 視頻素材的描述 返回說明
{ "media_id":MEDIA_ID }
返回參數說明
參數 描述 media_id 新增的永久素材的media_id 錯誤情況下的返回JSON數據包示例如下(示例為無效媒體類型錯誤):
{"errcode":40007,"errmsg":"invalid media_id"}
-
獲取永久素材
在新增了永久素材后,開發者可以根據media_id來獲取永久素材,需要時也可保存到本地。請注意:
1、獲取永久素材也可以獲取公眾號在公眾平台官網素材管理模塊中新建的圖文消息、語音、視頻等素材(但需要先通過獲取素材列表來獲知素材的media_id) 2、臨時素材無法通過本接口獲取 3、調用該接口需https協議
接口調用請求說明
http請求方式: POST,https調用 https://api.weixin.qq.com/cgi-bin/material/get_material?access_token=ACCESS_TOKEN
調用示例
{ "media_id":MEDIA_ID }
參數說明
參數 是否必須 說明 access_token 是 調用接口憑證 media_id 是 要獲取的素材的media_id 返回說明
如果請求的素材為圖文消息,則響應如下:
{ "news_item": [ { "title":TITLE, "thumb_media_id"::THUMB_MEDIA_ID, "show_cover_pic":SHOW_COVER_PIC(0/1), "author":AUTHOR, "digest":DIGEST, "content":CONTENT, "content_source_url":CONTENT_SOURCE_URL }, //多圖文消息有多篇文章 ] }
其他類型的素材消息,則響應的直接為素材的內容,開發者可以自行保存為文件。例如:
示例 curl "https://api.weixin.qq.com/cgi-bin/material/get_material?access_token=ACCESS_TOKEN" -d '{"media_id":"61224425"}' > file
返回參數說明
參數 描述 title 圖文消息的標題 thumb_media_id 圖文消息的封面圖片素材id(必須是永久mediaID) show_cover_pic 是否顯示封面,0為false,即不顯示,1為true,即顯示 author 作者 digest 圖文消息的摘要,僅有單圖文消息才有摘要,多圖文此處為空 content 圖文消息的具體內容,支持HTML標簽,必須少於2萬字符,小於1M,且此處會去除JS content_source_url 圖文消息的原文地址,即點擊“閱讀原文”后的URL 錯誤情況下的返回JSON數據包示例如下(示例為無效媒體類型錯誤):
{"errcode":40007,"errmsg":"invalid media_id"}
-
刪除永久素材
在新增了永久素材后,開發者可以根據本接口來刪除不再需要的永久素材,節省空間。請注意:
1、請謹慎操作本接口,因為它可以刪除公眾號在公眾平台官網素材管理模塊中新建的圖文消息、語音、視頻等素材(但需要先通過獲取素材列表來獲知素材的media_id) 2、臨時素材無法通過本接口刪除 3、調用該接口需https協議
接口調用請求說明
http請求方式: POST https://api.weixin.qq.com/cgi-bin/material/del_material?access_token=ACCESS_TOKEN
調用示例
{ "media_id":MEDIA_ID }
參數說明
參數 是否必須 說明 access_token 是 調用接口憑證 media_id 是 要獲取的素材的media_id 返回說明
{ "errcode":ERRCODE, "errmsg":ERRMSG }
正常情況下調用成功時,errcode將為0。
-
修改永久圖文素材
開發者可以通過本接口對永久圖文素材進行修改。請注意:
1、也可以在公眾平台官網素材管理模塊中保存的圖文消息(永久圖文素材) 2、調用該接口需https協議
接口調用請求說明
http請求方式: POST https://api.weixin.qq.com/cgi-bin/material/update_news?access_token=ACCESS_TOKEN
調用示例
{ "media_id":MEDIA_ID, "index":INDEX, "articles": [{ "title": TITLE, "thumb_media_id": THUMB_MEDIA_ID, "author": AUTHOR, "digest": DIGEST, "show_cover_pic": SHOW_COVER_PIC(0 / 1), "content": CONTENT, "content_source_url": CONTENT_SOURCE_URL }, //若新增的是多圖文素材,則此處應還有幾段articles結構 ] }
參數說明
參數 是否必須 說明 media_id 是 要修改的圖文消息的id index 是 要更新的文章在圖文消息中的位置(多圖文消息時,此字段才有意義),第一篇為0 title 是 標題 thumb_media_id 是 圖文消息的封面圖片素材id(必須是永久mediaID) author 是 作者 digest 是 圖文消息的摘要,僅有單圖文消息才有摘要,多圖文此處為空 show_cover_pic 是 是否顯示封面,0為false,即不顯示,1為true,即顯示 content 是 圖文消息的具體內容,支持HTML標簽,必須少於2萬字符,小於1M,且此處會去除JS content_source_url 是 圖文消息的原文地址,即點擊“閱讀原文”后的URL 返回說明
{ "errcode": ERRCODE, "errmsg": ERRMSG }
正確時errcode的值應為0。
-
獲取素材總數
開發者可以根據本接口來獲取永久素材的列表,需要時也可保存到本地。請注意:
1.永久素材的總數,也會計算公眾平台官網素材管理中的素材 2.圖片和圖文消息素材(包括單圖文和多圖文)的總數上限為5000,其他素材的總數上限為1000 3.調用該接口需https協議
接口調用請求說明
http請求方式: GET https://api.weixin.qq.com/cgi-bin/material/get_materialcount?access_token=ACCESS_TOKEN
返回說明
{ "voice_count":COUNT, "video_count":COUNT, "image_count":COUNT, "news_count":COUNT }
返回參數說明
參數 描述 voice_count 語音總數量 video_count 視頻總數量 image_count 圖片總數量 news_count 圖文總數量 錯誤情況下的返回JSON數據包示例如下(示例為無效媒體類型錯誤):
{"errcode":-1,"errmsg":"system error"}
-
獲取素材列表
在新增了永久素材后,開發者可以分類型獲取永久素材的列表。(這里有 如何快速查找微信公眾平台的歷史圖文消息素材 的小方法,是在公眾平台上的,不是第三方網站的)請注意:
1、獲取永久素材的列表,也會包含公眾號在公眾平台官網素材管理模塊中新建的圖文消息、語音、視頻等素材(但需要先通過獲取素材列表來獲知素材的media_id) 2、臨時素材無法通過本接口獲取 3、調用該接口需https協議
接口調用請求說明
http請求方式: POST https://api.weixin.qq.com/cgi-bin/material/batchget_material?access_token=ACCESS_TOKEN
調用示例
{ "type":TYPE, "offset":OFFSET, "count":COUNT }
參數說明
參數 是否必須 說明 type 是 素材的類型,圖片(image)、視頻(video)、語音 (voice)、圖文(news) offset 是 從全部素材的該偏移位置開始返回,0表示從第一個素材 返回 count 是 返回素材的數量,取值在1到20之間 返回說明
永久圖文消息素材列表的響應如下:
{ "total_count": TOTAL_COUNT, "item_count": ITEM_COUNT, "item": [{ "media_id": MEDIA_ID, "content": { "news_item": [{ "title": TITLE, "thumb_media_id": THUMB_MEDIA_ID, "show_cover_pic": SHOW_COVER_PIC(0 / 1), "author": AUTHOR, "digest": DIGEST, "content": CONTENT, "content_source_url": CONTETN_SOURCE_URL }, //多圖文消息會在此處有多篇文章 ] }, "update_time": UPDATE_TIME }, //可能有多個圖文消息item結構 ] }
其他類型(圖片、語音、視頻)的返回如下:
{ "total_count": TOTAL_COUNT, "item_count": ITEM_COUNT, "item": [{ "media_id": MEDIA_ID, "name": NAME, "update_time": UPDATE_TIME }, //可能會有多個素材 ] }
返回參數說明
參數 描述 total_count 該類型的素材的總數 item_count 本次調用獲取的素材的數量 title 圖文消息的標題 thumb_media_id 圖文消息的封面圖片素材id(必須是永久mediaID) show_cover_pic 是否顯示封面,0為false,即不顯示,1為true,即顯示 author 作者 digest 圖文消息的摘要,僅有單圖文消息才有摘要,多圖文此處為空 content 圖文消息的具體內容,支持HTML標簽,必須少於2萬字符,小於1M,且此處會去除JS content_source_url 圖文消息的原文地址,即點擊“閱讀原文”后的URL update_time 這篇圖文消息素材的最后更新時間 name 文件名稱 錯誤情況下的返回JSON數據包示例如下(示例為無效媒體類型錯誤):
{"errcode":40007,"errmsg":"invalid media_id"}