API:Upload

Language:	English  • 日本語

This page is part of the MediaWiki action API documentation.

MediaWiki APIsAPI:Main page

• Web APIs showcaseAPI:Web APIs hub
• REST content API

MediaWiki action API

• Introduction and quick startAPI:Main page
• FAQAPI:FAQ
  • Etiquette and usage limitsAPI:Etiquette
• TutorialAPI:Tutorial
• FormatsAPI:Data formats
• Error reportingAPI:Errors and warnings
• Restricting usageAPI:Restricting API usage
• Cross-site requestsAPI:Cross-site requests
• Authentication
  • LoginAPI:Login
  • LogoutAPI:Logout
  • Account creationAPI:Account creation
• QueriesAPI:Query
  • Meta informationAPI:Meta
  • PropertiesAPI:Properties
  • ListsAPI:Lists
• Searching (by title, content, coordinates...)API:Search and discovery
• Parsing wikitext and expanding templatesAPI:Parsing wikitext
• Purging pages' cachesAPI:Purge
• Parameter informationAPI:Parameter information
• Changing wiki contentAPI:Changing wiki content
  • Create and edit pagesAPI:Edit
  • Move pagesAPI:Move
  • RollbackAPI:Rollback
  • Delete pagesAPI:Delete
  • Restore deleted revisionsAPI:Undelete
  • (Un)protect pagesAPI:Protect
  • (Un)block usersAPI:Block
  • (Un)watch pagesAPI:Watch
  • Mark revisions of watched pages as visitedAPI:SetNotificationTimestamp
  • Send emailAPI:Email
  • Patrol changesAPI:Patrol
  • Import pagesAPI:Import
  • Change user group membershipAPI:User group membership
  • Upload filesAPI:Upload
  • User optionsAPI:Options
  • TokensAPI:Tokens
  • Page languageAPI:PageLanguage
• Watchlist feedAPI:Watchlist feed
• WikidataWikibase/API
• ExtensionsAPI:Extensions
• Using the API in MediaWiki and extensionsAPI:Calling internally
• MiscellaneousAPI:Other services
• ImplementationAPI:Implementation Strategy
  • LocalisationAPI:Localisation
• Client codeAPI:Client code
• AssertingAPI:Assert

MediaWiki version:

≥ 1.16

There are three methods of uploading files via the API:

1. Uploading a local file directly
2. Uploading a local file in chunks (originally based on the Firefogg chunked upload protocol)
3. Uploading a copy of a file elsewhere on the Web given by a URL

All of these methods require an account with the "upload" right.

Token

To upload files, an edit token is required and is the same regardless of the target filename, but changes at every login. Unlike other tokens, it cannot be obtained directly, so one must obtain and use an edit token instead. Edit tokens can be obtained via action=tokens (MW 1.20+), or by using the following method:

Obtaining a token

api.php?action=query&prop=info&intoken=edit&titles=Foo [try in ApiSandbox]

Parameters

• filename: Target filename
• comment: Upload comment. Also used as the initial page text for new files if text parameter not provided
• text: Initial page text for new files.
• token: Edit token
• watch: Watch the page (deprecated in 1.17)
• watchlist: Unconditionally add or remove the page from your watchlist, use preferences or do not change watch Possible values: watch, preferences, nochange. (Default: preferences) 1.17+
• ignorewarnings: Ignore any warnings. This must be set to upload a new version of an existing image.
• file: File contents
• url: Url to fetch the file from
• filekey: Key returned by a previous upload that failed due to warnings, or (with httpstatus) The upload_session_key of an asynchronous upload. Key that identifies a previous upload that was stashed temporarily. Formerly named sessionkey. 1.18+
• sessionkey: Same as filekey, maintained for backward compatibility (deprecated in 1.18)
• stash: If set, the server will not add the file to the repository and stash it temporarily 1.17+
• chunk: Chunk contents 1.19+
• offset: Offset of chunk in bytes 1.19+
• filesize: Filesize of entire upload 1.19+
• async: Make potentially large file operations asynchronous when possible 1.21+
• asyncdownload: Make fetching a URL asynchronous 1.17+
• leavemessage: If asyncdownload is used, leave a message on the user talk page if finished 1.17+
• statuskey: Fetch the upload status for this file key (upload by URL) 1.17+
• checkstatus: Only fetch the upload status for the given file key 1.21+

Uploading directly

When uploading files directly, the request must use multipart/form-data as Content-Type or enctype, application/x-www-form-urlencoded will not work. The below is only a guide.

Uploading a text file

api.php?action=upload&filename=Test.txt&file=file_contents_here&token=+\ [try in ApiSandbox]

Chunked uploading

Since uploading a huge file in a single HTTP POST can be unreliable, the API also supports a chunked upload mode, where you make multiple requests with portions of the file. This is available in MediaWiki 1.20 and above, but does not work correctly for SVGs (phab:T67724).

This is used by Extension:UploadWizard in browsers supporting FileAPI, uploading files in chunks of 1 megabyte, but you may choose your own size. This works in conjunction with the "stash" mode, to build a file up in pieces and then commit it at the end.

 action: upload
 stash: 1
 format: json
 token: (token)
 offset: 0
 filename: "filename.jpg"
 filesize: (total file size)
 chunk: (binary data of first chunk)

You'll receive data like this:

 {
   upload: {
     result: "Continue",
     filekey: "long scary filename.1.jpg",
     offset: (next chunk's starting point)
     imageinfo: {...}
   }
 }

For the second and further chunks, pass in the filekey parameter as well:

 action: upload
 stash: 1
 format: json
 token: (token)
 offset: (offset of start of this chunk)
 filename: "filename.jpg"
 filesize: (total file size)
 filekey: (filekey received from the previous Continue result)
 chunk: (binary data of next chunk)

On the last chunk, you'll get back

 {
   upload: {
     result: "Success",
     filekey: "long scary filename.1.jpg",
     offset: (next chunk's starting point)
     imageinfo: {...} (the data returned by this result is not completely accurate)
   }
 } 

You can then do a final upload using the file key to commit the upload out of the stash area:

 action: upload
 format: json
 token: (token)
 filename: "filename.jpg"
 filekey: (filekey received from the Success result)
 comment: upload comment
 text: file description

The result from the final upload will include the complete, accurate imageinfo object, comparable to what you would get from a non-chunked upload.

Uploading from URL

This requires $wgAllowCopyUploads = true in the wiki's local settings and an account with the upload_by_url user right. By default this is done synchronously, so downloading large files may exceed PHP's max_execution_time and fail. Asynchronous mode will return a session key that can then be used to query the upload status (see below). Asynchronous mode requires $wgEnableAsyncDownload = true ($wgAllowAsyncCopyUploads = true in later versions) in the wiki's local settings.

Asynchronous upload is no-longer available as-of r81612.

Upload from URL (synchronous)

api.php?action=upload&filename=Image.jpg&url=http://www.google.com/intl/en_ALL/images/logo.gif&token=+\ [try in ApiSandbox]

Upload from URL (asynchronous)

api.php?action=upload&filename=Image.jpg&url=http://www.google.com/intl/en_ALL/images/logo.gif&token=+\&asyncdownload=1 [try in ApiSandbox]

Retrieving upload status

For checking the status of an in-progress upload to the stash, or checking the progress of a file being published from the stash:

Retrieving upload status

api.php?action=upload&checkstatus=true&filekey=somekey1234.jpg&token=+\ [try in ApiSandbox]

Sample Raw Upload

Newlines are \r\n.

User-Agent: Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 5.1)
Content-Type: multipart/form-data; boundary=---------------------------8ce5ac3ab79ab2c
Host: commons.wikimedia.org
Cookie: <cookies>
Content-Length: <proper content length>
Connection: Keep-Alive


-----------------------------8ce5ac3ab79ab2c
Content-Disposition: form-data; name="action"
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

upload
-----------------------------8ce5ac3ab79ab2c
Content-Disposition: form-data; name="filename"
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Apple.gif
-----------------------------8ce5ac3ab79ab2c
Content-Disposition: form-data; name="text"
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

text
-----------------------------8ce5ac3ab79ab2c
Content-Disposition: form-data; name="comment"
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

comment
-----------------------------8ce5ac3ab79ab2c
Content-Disposition: form-data; name="token"
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

0ff12678952302357892acc565412393+\
-----------------------------8ce5ac3ab79ab2c
Content-Disposition: form-data; name="format"
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

xml
-----------------------------8ce5ac3ab79ab2c
Content-Disposition: form-data; name="file"; filename="Apple.gif"
Content-Type: application/octet-stream; charset=UTF-8
Content-Transfer-Encoding: binary

<Gif in binary>
-----------------------------8ce5ac3ab79ab2c--