Skip to main content

​
API call description

Call this API to upload a media file and obtain the media resource identifier media_id. About media_id:
  • Use multipart/form-data POST to upload the file. The file identifier name is media.
  • media_id is reusable. The same media_id can be used multiple times.
  • The resource file corresponding to a media_id can only be used within the DingTalk client.
  • Media files use a dedicated storage space that DingTalk provides to organizations. Files uploaded through this API do not consume the DingTalk Drive space of your organization.

​
Request

Basic information
HTTP URLhttps://oapi.dingtalk.io/media/upload
HTTP MethodPOST
Supported app typesappType-Internal app appType-Third-party enterprise app
Required permissionspermission-qyapi_base-Basic permissions required to call enterprise APIs

​
Query parameters

NameTypeRequiredExampleDescription
access_tokenStringYesbE74xxxxThe app credential used to call this API. - For an internal app, obtain it through the API for getting the access_token of an internal app. - For a third-party enterprise app, obtain it through the API for getting the access_token of a third-party enterprise.

​
Request body

NameTypeRequiredExampleDescription
typeStringYesimageThe media file type: - image: Image. Maximum size is 20 MB. Supported formats: jpg, gif, png, bmp. - voice: Voice. Maximum size is 2 MB. Supported formats: amr, mp3, wav. - video: Video. Maximum size is 20 MB. Supported format: mp4. - file: Regular file. Maximum size is 20 MB. Supported formats: doc, docx, xls, xlsx, ppt, pptx, zip, pdf, rar. Important If you call this API in C# and receive error 40004 (invalid media file type), append the type parameter to the request URL.
mediaFileItemYesC:/Users/Desktop/222.pngThe media file to upload. In form-data, the media file identifier contains information such as filename, filelength, and content-type.

​
Request example

curl -X POST "https://oapi.dingtalk.io/media/upload" \
-H 'Content-Type:multipart/form-data;charset=utf-8' \
-F 'access_token=4c813ba0-2363-4927-9de0-376b0e6853a2' \
-F 'type=image' \
-F 'media=@"C:/Users/Desktop/222.png"'
Java 
DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/media/upload");
OapiMediaUploadRequest req = new OapiMediaUploadRequest();
req.setType("image");
// The media file to upload
FileItem item = new FileItem("C:/Users/Desktop/222.png");
req.setMedia(item);
OapiMediaUploadResponse rsp = client.execute(req, access_token);
System.out.println(rsp.getBody());
Python 
import dingtalk.api

req=dingtalk.api.OapiMediaUploadRequest("https://oapi.dingtalk.io/media/upload")

req.type="image"
req.media=dingtalk.api.FileItem('abc.jpg',open('abc.jpg','rb'))
try:
  resp= req.getResponse(access_token)
  print(resp)
except Exception,e:
  print(e)
PHP 
include "TopSdk.php";
date_default_timezone_set('Asia/Shanghai');

$c = new DingTalkClient(DingTalkConstant::$CALL_TYPE_OAPI, DingTalkConstant::$METHOD_POST , DingTalkConstant::$FORMAT_JSON);
$req = new OapiMediaUploadRequest;
$req->setType("image");

$req->setMedia("C:/Users/Desktop/222.png");
$resp = $c->execute($req, $access_token, "https://oapi.dingtalk.io/media/upload");
C# 
IDingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/media/upload");
OapiMediaUploadRequest req = new OapiMediaUploadRequest();
req.Type = "image";
req.Media = new FileItem("C:/Users/Desktop/222.png");
OapiMediaUploadResponse rsp = client.Execute(req, access_token);
Console.WriteLine(rsp.Body);

​
Response

​
Response body

NameTypeExampleDescription
errcodeNumber0The return code.
errmsgStringokThe description of the return code.
typeStringfileThe media file type: - image: Image - voice: Voice - file: Regular file - video: Video
media_idString@#lAzPDgCwPn1mJiDOQoLpxxxxThe unique identifier obtained after the media file is uploaded.
created_atNumber1599556098964The timestamp when the media file was uploaded.

​
Response body example

{
  "errcode": 0,
  "errmsg": "ok",
  "media_id": "$iAEKAqNwbmcDBgTNAk",
  "created_at": 1605863153573,
  "type": "image"
}

​
Error codes

If an error occurs when calling this API, refer to the Global error codes document to find the solution.