Upload Files

Update time: 2022/12/09 12:05:47

This server APIs allows you to upload file messages to Netease Object Storage (NOS) or remove files uploaded earlier.

Upload a file

Upload a file to NOS.

Rate limit

  • Apps can call the API by 100 times per second. If an app calls the API exceeding the limit, requests from the app will be blocked for 10 seconds before the API become available again.
  • Character streams must be base64 encoded,
  • The maximum size of a file for upload reaches up to 15MB.

URL

POST https://api.netease.im/nimserver/msg/upload.action HTTP/1.1
Content-Type:application/x-www-form-urlencoded;charset=utf-8

Request parameters

  • For information about how to set the header in a POST request, see API Call methods.

  • The settings of the body in a POST request:

ParameterTypeRequiredDescription
contentStringYes Character stream of Base64 encoded string (Base64.encode(bytes)). Up to 15MB is supported.
typeStringNo Type of an uploaded file. Up to 128 characters are allowed. A string exceeding the upper limit, a value of null is applied.
ishttpsbooleanNo Whether the response is returned using HTTPS. The default value is false.
expireSecintNo Time when the file expires. Unit: seconds. The value must be greater than or equal to 86400.
tagStringNo Scenario tag. Up to 32 characters are allowed.

Response parameters

Parameter Type Description
url String URL for the uploaded file.

Example

cURL request example

curl -X POST -H "AppKey: go9dnk49bkd9jd9vmel1*****803mgq3" -H "Nonce: 4tgggergigwow323t23t" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Content-Type: application/x-www-form-urlencoded" -d 'content=gwettwgsgssgs323f' 'https://api.netease.im/nimserver/msg/upload.action'

Example success response

HTTP response in JSON

"Content-Type": "application/json; charset=utf-8"
{
    "code":200,
    "url": "https://sf.nos.netease.im/image.jpg"  
}

Example error response

"Content-Type": "application/json; charset=utf-8"
{
    "code":414
    "desc":"content is empty" // The upload file contains no content.
}

Status code

The following status codes are related to responses of this API. For more status codes, see Status codes.

Status code Description Recommendation
403 Possible reasons for a failed request:
  • Authentication failed
  • The message cannot be recalled.
  • </ ul>
Handle the error based on the specific message.
414 Parameter error Check the format and restrictions of arguments based on the error message.
500 Internal Server Error -

Multipart upload

Overview

Upload files to NOS using multipart upload.

Rate limit

  • Apps can call the API by 100 times per second. If an app calls the API exceeding the limit, requests from the app will be blocked for 10 seconds before the API become available again.
  • The maximum size of a file for upload reaches up to 15MB.

URL

POST https://api.netease.im/nimserver/msg/fileUpload.action HTTP/1.1
Content-Type:multipart/form-data;charset=utf-8

Request parameters

  • For information about how to set the header in a POST request, see API Call methods.

  • The settings of the body in a POST request:

ParameterTypeRequiredDescription
contentStringYes Character stream up to 15MB
typeStringNo File type. Up to 128 characters are allowed. If the string exceeds the upper limit, a value of null is applied.
ishttpsbooleanNo Whether the response is returned using HTTPS. The default value is false.
expireSecintNo Time when the file expires. Unit: seconds. The value must be greater than or equal to 86400.
tagStringNo Scenario tag. Up to 32 characters are allowed.

Response parameters

Parameter Type Description
url String URL for the uploaded file.

Example

cURL request example

curl -X POST -H "AppKey: go9dnk49bkd9jd9vmel1*****803mgq3" -H "Nonce: 4tgggergigwow323t23t" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Content-Type: multipart/form-data" -d 'content=gwettwgsgssgs323f' 'https://api.netease.im/nimserver/msg/fileUpload.action'

Example success response

HTTP response in JSON

"Content-Type": "application/json; charset=utf-8"
{
    "code":200,
    "url": "https://sf.nos.netease.im/image.jpg"  
}

Example error response

"Content-Type": "application/json; charset=utf-8"
{
    "code":414
    "desc":"content is empty" // The upload file contains no content.
}

Status code

The following status codes are related to responses of this API. For more status codes, see Status codes.

Status code Description Recommendation
403 Possible reasons for a failed request:
  • Authentication failed
  • The message cannot be recalled.
  • </ ul>
Handle the error based on the specific message.
414 Parameter error Check the format and restrictions of arguments based on the error message.
500 Internal Server Error -

Delete uploaded files

Create a task to delete uploaded files with a specified time range, types, and scenarios.

You can call this API five times per day. Proceed with caution.

  • When a file is uploaded to NOS, a timestamp to the file is generated.

  • Using different parameters, this API can perform the following four types of deleting tasks:

Required parameter Description
Time range only If a file has a timestamp within the specified time range (between startTime and endTime below), the file will be deleted.
Time range and file type If a file has a timestamp within the specified time range and hits the specified type (contentType), the file will be deleted.
Time range and scenario tag If a file has a timestamp within the specified time range and hits the scenario tag, the file will be deleted.
Time range, file type, and scenario tag If a file has a timestamp within the specified time range and matches the type and scenario tag, the file will be deleted.

URL

POST https://api.netease.im/nimserver/job/nos/del.action HTTP/1.1
Content-Type:application/x-www-form-urlencoded;charset=utf-8

Request parameters

  • For information about how to set the header in a POST request, see API Call methods.

  • The settings of the body in a POST request:

ParameterTypeRequiredDescription
startTimeLongYes Start time in milliseconds. The startTime must be less than the endTime and greater than 0. the difference between the startTime and endTime must be more than 1 day and less than 7 days.
endTimeLongYes End time in milliseconds. The endTime must be earlier than the current day. Only files earlier than the current day can be deleted.
contentTypeStringNo Type of files to be deleted. Files of the types specified in the contentType parameter are deleted. If the file to be deleted is a "image/png” file and the contentType parameter is set to "image", the file will be deleted.
tagStringNo Files of the exact scenario tags are deleted. If a file contains the "usericon" tag, you can delete the file with the "usericon" tag.

Response parameters

Parameter Type Description
data JSON the data about the deleting task, including the task ID (taskid).

Example

cURL request example

curl -X POST -H "CheckSum: 32dc17d0190f37037abc9feb749bbf049c9367e7" -H "AppKey: fe416640c8e8a72734219e*****d2547" -H "Nonce: 1" -H "CurTime: 1451200147" -H "Cache-Control: no-cache" -H "Postman-Token: a503b469-ee33-2c2e-8fb1-87b1fdf9f8f4" -H "Content-Type: application/x-www-form-urlencoded" -d 'startTime=1533988669286&endTime=1534420669286&contentType=image&tag=usericon' "http://223.252.220.223/nimserver/job/nos/del.action"

Response

HTTP response: JSON

"Content‐type":"application/json;charset=utf‐8"
{
  "code": 200,
  "data":{
    "taskid":"1024030f3841440daf2af73672792f47"
  }
}

Status code

The status code is returned in the response body. For more information about status codes, see Status codes.

Was this page helpful?
Yes
No
  • Upload a file
  • Rate limit
  • URL
  • Request parameters
  • Response parameters
  • Example
  • cURL request example
  • Example success response
  • Example error response
  • Status code
  • Multipart upload
  • Overview
  • Rate limit
  • URL
  • Request parameters
  • Response parameters
  • Example
  • cURL request example
  • Example success response
  • Example error response
  • Status code
  • Delete uploaded files
  • URL
  • Request parameters
  • Response parameters
  • Example
  • cURL request example
  • Response
  • Status code