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

Other languages:
English • ‎español • ‎русский • ‎日本語
MediaWiki バージョン: 1.16

ファイルをアップロードする POST リクエストです。

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.



(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:ログイン .
  2. CSRF トークン を取得します:
  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 リクエスト


  "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

サンプル コード



    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 リクエスト


サンプル コード

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.

サンプル コード


コード 情報
mustbeloggedin このファイルのアップロードにログインしている必要があります。
permissiondenied この操作は、以下のグループのいずれかに属する利用者のみが実行できます: Administrators, Uploaders
fileexists-shared-forbidden この名前のファイルは共有ファイルリポジトリに既に存在しています。


chunk-too-small Minimum chunk size is n bytes for non-final chunks.
stashfailed このファイルは、ファイルの検証システムに合格しませんでした。


  • v1.21: async checkstatus を導入しました
  • v1.19: offset filesize chunk を導入しました
  • v1.18: stash filekey を導入しました
  • v1.17: stash, statuskey, leavemessage, asyncdownload を導入しました
  • v1.18: sessionkey を廃止予定にしました
  • v1.17: watch を廃止予定にしました


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