API:Upload
Language: | English • 日本語 |
---|
![]() |
Please expand this page. The reason given is: needs more examples, more explanation of parameters, more detail of API responses including the possible warnings |
![]() |
This page is part of the MediaWiki action API documentation. |
MediaWiki action API
- Introduction and quick start
- FAQ
- Tutorial
- Formats
- Error reporting
- Restricting usage
- Cross-site requests
- Authentication
- Queries
- Searching (by title, content, coordinates...)
- Parsing wikitext and expanding templates
- Purging pages' caches
- Parameter information
- Changing wiki content
- Create and edit pages
- Move pages
- Merge pages
- Rollback
- Delete pages
- Restore deleted revisions
- (Un)protect pages
- (Un)block users
- (Un)watch pages
- Mark revisions of watched pages as visited
- Send email
- Patrol changes
- Import pages
- Change user group membership
- Upload files
- User options
- Tokens
- Page language
- Watchlist feed
- Wikidata
- Extensions
- Using the API in MediaWiki and extensions
- Miscellaneous
- Implementation
- Client code
- Asserting
upload | ||
---|---|---|
Upload a file, or get the status of pending uploads This module cannot be used as a Generator . |
||
Prefix | ||
Required rights | upload | |
Post only? | Yes | |
Generated help | Current | |
Version added |
|
There are three methods of uploading files via the API:
- Uploading a local file directly
- Uploading a local file in chunks (originally based on the Firefogg chunked upload protocol)
- 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.
Contents
Token[edit]
To upload files, an edit token is required. This token is the same for all pages, but changes at every login. The preferred method to obtain an edit token depends on the MediaWiki version:
- Versions 1.24 and later: action=query&meta=tokens
- Versions 1.20-1.23: action=tokens
- Versions 1.19 and earlier: action=query&prop=info
Currently, all older methods continue to work, but are deprecated.
Example[edit]
Obtaining a token
Result |
---|
<api>
<query>
<pages>
<page
pageid="1"
ns="0"
title="Foo"
touched="2000-01-01T00:00:00Z"
lastrevid="1"
counter="0"
length="0"
edittoken="+\"
/>
</pages>
</query>
</api>
|
Parameters[edit]
filename
: Target filenamecomment
: Upload comment. Also used as the initial page text for new files if text parameter not providedtext
: Initial page text for new files.token
: Edit tokenwatch
: 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 contentsurl
: Url to fetch the file fromfilekey
: 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 namedsessionkey
. 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[edit]
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
Result |
---|
<api>
<upload result="Success" filename="Test.txt">
<imageinfo timestamp="2000-01-01T00:00:00Z" user="127.0.0.1" anon="" size="1000" width="0" height="0" url="http://localhost/images/3/35/Test.txt" descriptionurl="http://localhost/index.php/File:Test.txt" comment="" sha1="b8f32ebbf9512d8641d7e72c86614c2cee3e8108" metadata="" mime="text/plain" bitdepth="0" />
</upload>
</api>
|
Chunked uploading[edit]
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, although prior to version 1.25, SVGs could not be uploaded via chunked uploading.
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[edit]
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)
Result |
---|
<api>
<upload result="Success" filename="Test.gif">
<imageinfo timestamp="2009-10-30T05:06:43Z" user="Gurch" size="8558" width="276" height="110" url="http://localhost/images/e/ea/Test.gif" descriptionurl="http://localhost/index.php/File:Test.gif" comment="" sha1="fd852df5478eb7eb9410ee9101bb364adf487fb0" mime="image/gif" bitdepth="8">
<metadata>
<metadata name="frameCount" value="1" />
<metadata name="looped" value="" />
<metadata name="duration" value="0" />
</metadata>
</imageinfo>
</upload>
</api>
|
Upload from URL (asynchronous)
Result |
---|
<api>
<upload upload_session_key="12345" />
</api>
|
Retrieving upload status[edit]
Parts of this api (those related to section) are outdated. It was written for an older version of MediaWiki and may not apply to the most recent version. See the talk page for a possible discussion on this. |
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
Result |
---|
<api>
<upload upload_session_key="12345" loaded="0" content_length="8558" />
</api>
|
Sample Raw Upload[edit]
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--
![]() |
The following documentation is the output of Special:ApiHelp/upload, generated from upload's source code. |
action=upload
- This module requires read rights.
- This module requires write rights.
- This module only accepts POST requests.
- Source: MediaWiki
- License: GPL-2.0+
Upload a file, or get the status of pending uploads.
Several methods are available:
- Upload file contents directly, using the file parameter.
- Upload the file in pieces, using the filesize, chunk, and offset parameters.
- Have the MediaWiki server fetch a file from a URL, using the url parameter.
- Complete an earlier upload that failed due to warnings, using the filekey parameter.
Note that the HTTP POST must be done as a file upload (i.e. using multipart/form-data
) when sending the file.
- filename
-
Target filename.
- comment
-
Upload comment. Also used as the initial page text for new files if text is not specified.
- Default: (empty)
- tags
-
Change tags to apply to the upload log entry and file page revision.
- Values (separate with | or alternative):
- text
-
Initial page text for new files.
- watch
- Deprecated.
-
Watch the page.
- Type: boolean (details)
- watchlist
-
Unconditionally add or remove the page from the current user's watchlist, use preferences or do not change watch.
- One of the following values: watch, preferences, nochange
- Default: preferences
- ignorewarnings
-
Ignore any warnings.
- Type: boolean (details)
- file
-
File contents.
- Must be posted as a file upload using multipart/form-data.
- url
-
URL to fetch the file from.
- filekey
-
Key that identifies a previous upload that was stashed temporarily.
- sessionkey
- Deprecated.
-
Same as filekey, maintained for backward compatibility.
- stash
-
If set, the server will stash the file temporarily instead of adding it to the repository.
- Type: boolean (details)
- filesize
-
Filesize of entire upload.
- The value must be between 0 and 4,294,967,296.
- Type: integer
- offset
-
Offset of chunk in bytes.
- The value must be no less than 0.
- Type: integer
- chunk
-
Chunk contents.
- Must be posted as a file upload using multipart/form-data.
- async
-
Make potentially large file operations asynchronous when possible.
- Type: boolean (details)
- checkstatus
-
Only fetch the upload status for the given file key.
- Type: boolean (details)
- token
-
A "csrf" token retrieved from action=query&meta=tokens
- This parameter is required.
- Upload from a URL.
- api.php?action=upload&filename=Wiki.png&url=http%3A//upload.wikimedia.org/wikipedia/en/b/bc/Wiki.png&token=123ABC [open in sandbox]
- Complete an upload that failed due to warnings.
- api.php?action=upload&filename=Wiki.png&filekey=filekey&ignorewarnings=1&token=123ABC [open in sandbox]