API:Upload

From MediaWiki.org
Jump to: navigation, search
Language:Project:Language policy English  • 日本語
Tools clipart.png This page is part of the MediaWiki action API documentation.
MediaWiki APIsAPI:Main page



MediaWiki action API

v · d · e
upload
Upload a file, or get the status of pending uploads
This module cannot be used as a GeneratorAPI:generator.
Prefix
Required rights upload
Post only? Yes
Generated help Current
Version added
≥ 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[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:

Currently, all older methods continue to work, but are deprecated.

Example[edit]

Obtaining a token

api.php?action=query&prop=info&intoken=edit&titles=Foo [try in ApiSandbox]
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 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[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

api.php?action=upload&filename=Test.txt&file=file_contents_here&token=+\ [try in ApiSandbox]
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.

Sample Raw POST of a single chunk[edit]

This is an example of a multipart POST to /api.php?action=upload, representing a single chunk. Note that you must unstash the file for it to appear in the Wiki once you have successfully uploaded all your chunks.

Extended content 
User-Agent: <YOUR USER-AGENT>
Content-Type: multipart/form-data; boundary=--24b7c3bb-fb4d-45c3-937c-11c2e0c2525b
Host: commons.wikimedia.org
Cookie: <cookies>
Connection: Keep-Alive

--24b7c3bb-fb4d-45c3-937c-11c2e0c2525b
Content-Disposition: form-data; name="filename"
Content-Length: 20

UploadTest356456.png
--24b7c3bb-fb4d-45c3-937c-11c2e0c2525b
Content-Disposition: form-data; name="offset"
Content-Length: 1

0
--24b7c3bb-fb4d-45c3-937c-11c2e0c2525b
Content-Disposition: form-data; name="format"
Content-Length: 4

json
--24b7c3bb-fb4d-45c3-937c-11c2e0c2525b
Content-Disposition: form-data; name="ignorewarnings"
Content-Length: 1

1
--24b7c3bb-fb4d-45c3-937c-11c2e0c2525b
Content-Disposition: form-data; name="filesize"
Content-Length: 3

971
--24b7c3bb-fb4d-45c3-937c-11c2e0c2525b
Content-Disposition: form-data; name="token"
Content-Length: 42

<YOUR_CSRF_TOKEN_HERE>
--24b7c3bb-fb4d-45c3-937c-11c2e0c2525b
Content-Disposition: form-data; name="stash"
Content-Length: 1

1
--24b7c3bb-fb4d-45c3-937c-11c2e0c2525b
Content-Disposition: form-data; name="chunk"; filename="1.png"
Content-Type: application/octet-stream
Content-Length: 971

<RAW_BYTES_FROM_FILE_HERE>
--24b7c3bb-fb4d-45c3-937c-11c2e0c2525b--

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)

api.php?action=upload&filename=Image.jpg&url=http://www.google.com/intl/en_ALL/images/logo.gif&token=+\ [try in ApiSandbox]
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)

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

Retrieving upload status[edit]

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]
Result 
<api>
  <upload upload_session_key="12345" loaded="0" content_length="8558" />
</api>



action=upload

(main | 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.

Parameters:
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.
Examples:
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]
Retrieved from "https://www.mediawiki.org/w/index.php?title=API:Upload&oldid=2339771"