From MediaWiki.org
Jump to navigation Jump to search
This page is a translated version of the page API:Upload and the translation is 17% complete.

Other languages:
English • ‎español • ‎русский • ‎日本語
Versión de MediaWiki: 1.16

POST request to upload a file.

There are three methods of uploading files via the API:

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

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

API documentation


(main | upload)
  • This module requires read rights.
  • This module requires write rights.
  • This module only accepts POST requests.
  • Source: MediaWiki
  • License: GPL-2.0-or-later

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.


Target filename.


Upload comment. Also used as the initial page text for new files if text is not specified.

Default: (empty)

Change tags to apply to the upload log entry and file page revision.

Values (separate with | or alternative):

Initial page text for new files.


Watch the page.

Type: boolean (details)

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

Ignore any warnings.

Type: boolean (details)

File contents.

Must be posted as a file upload using multipart/form-data.

URL to fetch the file from.


Key that identifies a previous upload that was stashed temporarily.


Same as filekey, maintained for backward compatibility.


If set, the server will stash the file temporarily instead of adding it to the repository.

Type: boolean (details)

Filesize of entire upload.

The value must be between 0 and 4,294,967,296.
Type: integer

Offset of chunk in bytes.

The value must be no less than 0.
Type: integer

Chunk contents.

Must be posted as a file upload using multipart/form-data.

Make potentially large file operations asynchronous when possible.

Type: boolean (details)

Only fetch the upload status for the given file key.

Type: boolean (details)

A "csrf" token retrieved from action=query&meta=tokens

This parameter is required.


Making any POST request is a multi-step process:

  1. Log in, via one of the methods described in API:Login .
  2. GET a CSRF token :
  3. Send a POST request, with the CSRF token to upload a file.

Example 1: Upload a local file 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.

POST request


  "upload": {
    "filename": "File_1.jpg",
    "result": "Success",
    "imageinfo": {
      "url": "https://upload.wikimedia.org/wikipedia/test/3/39/File_1.jpg",
      "html": "<p>A file with this name exists already, please check <strong><a class=\"mw-selflink selflink\">File:File 1.jpg</a></strong> if you are not sure if you want to change it.\n</p>\n<div class=\"thumb tright\"><div class=\"thumbinner\" style=\"width:182px;\"><a           href=\"/w/index.php?title=Special:Upload&amp;wpDestFile=File_1.jpg\" class=\"new\" title=\"File:File 1.jpg\">File:File 1.jpg</a>  <div class=\"thumbcaption\"></div></div></div>\n",
      "width": 474,
      "size": 26703,
      "bitdepth": 8,
      "mime": "image/jpeg",
      "userid": 42588,
      "mediatype": "BITMAP",
      "descriptionurl": "https://test.wikipedia.org/wiki/File:File_1.jpg",
      "extmetadata": {
        "ObjectName": {
          "value": "File 1",
          "hidden": "",
          "source": "mediawiki-metadata"
        "DateTime": {
          "value": "2019-03-06 08:43:37",
          "hidden": "",
          "source": "mediawiki-metadata"
      "comment": "",
      "commonmetadata": [],
      "descriptionshorturl": "https://test.wikipedia.org/w/index.php?curid=0",
      "sha1": "2ffadd0da73fab31a50407671622fd6e5282d0cf",
      "parsedcomment": "",
      "metadata": [
          "name": "MEDIAWIKI_EXIF_VERSION",
          "value": 2
      "canonicaltitle": "File:File 1.jpg",
      "user": "Mansi29ag",
      "timestamp": "2019-03-06T08:43:37Z",
      "height": 296

Código de ejemplo



    MediaWiki Action API Code Samples
    Demo of `Upload` module: Sending POST request to upload a file directly

    MIT license

import requests

S = requests.Session()
URL = "https://test.wikipedia.org/w/api.php"
FILE_PATH = 'f.jpg'

# Step 1: Retrieve a login token
PARAMS_1 = {
    "action": "query",
    "meta": "tokens",
    "type": "login",
    "format": "json"

R = S.get(url=URL, params=PARAMS_1)
DATA = R.json()

LOGIN_TOKEN = DATA["query"]["tokens"]["logintoken"]

# Step 2: Send a POST request to login. Use of main account for login is not
# supported. Obtain credentials via Special:BotPasswords
# (https://www.mediawiki.org/wiki/Special:BotPasswords) for lgname & lgpassword
PARAMS_2 = {
    "action": "login",
    "lgname": "bot_username",
    "lgpassword": "bot_password",
    "format": "json",
    "lgtoken": LOGIN_TOKEN

R = S.post(URL, data=PARAMS_2)

# Step 3: Obtain a CSRF token
PARAMS_3 = {
    "action": "query",

R = S.get(url=URL, params=PARAMS_3)
DATA = R.json()

CSRF_TOKEN = DATA["query"]["tokens"]["csrftoken"]

# Step 4: POST request to upload a file directly
PARAMS_4 = {
    "action": "upload",
    "filename": "file_1.jpg",
    "format": "json",
    "token": CSRF_TOKEN,
    "ignorewarnings": 1

FILE = {'file':('file_1.jpg', open(FILE_PATH, 'rb'), 'multipart/form-data')}

R = S.post(URL, files=FILE, data=PARAMS_4)
DATA = R.json()

Example 2: Upload file from URL

This requires $wgAllowCopyUploads = true in the wiki's local settings and an account with the upload_by_url user right.

POST request


Sample code

Example 3: Upload file in chunks

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 version 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.

Step 1: Pass content for the first chunk

For all the chunks except the last chunk you will receive this:

Step 2: Pass filekey parameter for second and further chunks

You will obtain the filekey parameter from the previous continue result as well:

For the last chunk, you will receive this:

Step 3: Final upload using the filekey to commit the upload out of the stash area

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

Código de ejemplo

Possible errors

Código Información
mustbeloggedin Debes estar conectado para subir este archivo.
permissiondenied La acción que has solicitado está restringida a los usuarios de uno de estos 2 grupos: Administrators, Uploaders.
fileexists-shared-forbidden Ya existe un archivo con este nombre en el repositorio compartido. Si todavía quieres subir tu archivo, por favor, regresa a la página anterior y usa otro nombre.
chunk-too-small Minimum chunk size is n bytes for non-final chunks.
stashfailed Este archivo no superó la verificación de archivos.

Parameter history

  • v1.21: Introduced async checkstatus
  • v1.19: Introduced offset filesize chunk
  • v1.18: Introduced stash filekey
  • v1.17: Introduced stash, statuskey, leavemessage, asyncdownload
  • v1.18: Deprecated sessionkey
  • v1.17: Deprecated watch

Notas adicionales

  • To check the status of an in-progress upload to the stash or the progress of a file being published from the stash, send a POST request:
  • Below 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.

Véase también