API:Upload
This page is part of the MediaWiki API documentation. |
Language: | English |
---|
Quick overview:
- Quick start guide
- FAQ
- Tutorial
- Formats
- Error reporting
- Restricting usage
- Cross-site requests
- Authentication
- Queries
- Search suggestions
- Parsing wikitext and expanding templates
- Purging pages' caches
- Parameter information
- Changing wiki content
- Watchlist feed
- Wikidata
- Extensions
- Using the API in MediaWiki and extensions
- Miscellaneous
- Implementation
- Client code
MediaWiki version: | = 1.16 |
There are three methods of uploading files via the API:
- Uploading a local file directly
- Uploading a local file in chunks using 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 | edit source]
To upload files, an edit token is required and is the same regardless of 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.
Obtaining a token
Result |
---|
The following content has been placed in a collapsed box for improved usability. |
<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> |
The above content has been placed in a collapsed box for improved usability. |
Uploading[edit | edit source]
- 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
- ignorewarnings - Ignore any warnings
- file - File contents
- url - Url to fetch the file from
- sessionkey - Session key returned by a previous upload that failed due to warnings, or (with httpstatus) The upload_session_key of an asynchronous upload
Uploading directly[edit | edit source]
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 |
---|
The following content has been placed in a collapsed box for improved usability. |
<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> |
The above content has been placed in a collapsed box for improved usability. |
Chunked uploading[edit | edit source]
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.
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 first request) 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: {...} } }
You can then do a final upload using the file key to commit the upload out of the stash area.
Uploading from URL[edit | edit source]
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 |
---|
The following content has been placed in a collapsed box for improved usability. |
<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> |
The above content has been placed in a collapsed box for improved usability. |
Upload from URL (asynchronous)
Result |
---|
The following content has been placed in a collapsed box for improved usability. |
<api> <upload upload_session_key="12345" /> </api> |
The above content has been placed in a collapsed box for improved usability. |
Retrieving upload status[edit | edit source]
This page may need updating. It was written about an older version (or versions) of MediaWiki and may not apply to the most recent version. |
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 |
---|
The following content has been placed in a collapsed box for improved usability. |
<api> <upload upload_session_key="12345" loaded="0" content_length="8558" /> </api> |
The above content has been placed in a collapsed box for improved usability. |
Sample Raw Upload[edit | edit source]
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--