API:Upload
This page is part of the MediaWiki Action API documentation. |
MediaWiki version: | ≥ 1.16 |
POST request to upload a file.
There are three methods of uploading files via the API:
- Uploading a local file directly
- Uploading a copy of a file from a URL
- Uploading a local file in chunks
All of these methods require an account with the upload
right.
API documentation
edit
Upload warnings
editNote that an upload may fail due to a number of warning conditions. This can be overridden by setting ignorewarnings=1
. Some notable warnings include:
- exists: A file with the given name already exists. If this warning is ignored, the uploaded file will replace the existing file.
- no-change: A file with the given name already exists and is exactly the same as the uploaded file.
- duplicateversions: A file with the given name already exists and an old version of that file is exactly the same as the uploaded file.
- was-deleted: a file with the given name used to exist but has been deleted.
- duplicate: The uploaded file exists under a different (or the same) name. Uploading a duplicate may be undesirable.
- duplicate-archive: The uploaded used to exist under a different (or the same) name but has been deleted. This may indicate that the file is inappropriate and should not be uploaded.
- badfilename: The file name supplied is not acceptable on this wiki, for instance because it contains forbidden characters
Result |
---|
{
"upload": {
"result": "Warning",
"warnings": {
"badfilename": "My_bad:filename.png"
},
"filekey": "19mmz8arzreg.9md1cj.2283740.png",
"sessionkey": "19mmz8arzreg.9md1cj.2283740.png"
}
}
|
Example
editMaking any POST request is a multi-step process:
- Log in, via one of the methods described in API:Login .
- GET a CSRF token :
- Send a POST request, with the CSRF token to upload a file.
Example 1: Upload a local file directly
editWhen 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
editResponse
editResult |
---|
{
"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&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
}
}
}
|
Sample code
editPython
edit"""
upload_file_directly.py
MediaWiki API Demos
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",
"meta":"tokens",
"format":"json"
}
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()
print(DATA)
PHP
edit<?php
/*
upload_file_directly.php
MediaWiki API Demos
Demo of `Upload` module: Sending post request to upload a file directly
MIT license
*/
$endPoint = "https://test.wikipedia.org/w/api.php";
$login_Token = getLoginToken(); // Step 1
loginRequest( $login_Token ); // Step 2
$csrf_Token = getCSRFToken(); // Step 3
upload( $csrf_Token ); // Step 4
// Step 1: GET request to fetch login token
function getLoginToken() {
global $endPoint;
$params1 = [
"action" => "query",
"meta" => "tokens",
"type" => "login",
"format" => "json"
];
$url = $endPoint . "?" . http_build_query( $params1 );
$ch = curl_init( $url );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $ch, CURLOPT_COOKIEJAR, "cookie.txt" );
curl_setopt( $ch, CURLOPT_COOKIEFILE, "cookie.txt" );
$output = curl_exec( $ch );
curl_close( $ch );
$result = json_decode( $output, true );
return $result["query"]["tokens"]["logintoken"];
}
// Step 2: POST request to log in. Use of main account for login is not
// supported. Obtain credentials via Special:BotPasswords
// (https://www.mediawiki.org/wiki/Special:BotPasswords) for lgname & lgpassword
function loginRequest( $logintoken ) {
global $endPoint;
$params2 = [
"action" => "login",
"lgname" => "bot_user_name",
"lgpassword" => "bot_password",
"lgtoken" => $logintoken,
"format" => "json"
];
$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $endPoint );
curl_setopt( $ch, CURLOPT_POST, true );
curl_setopt( $ch, CURLOPT_POSTFIELDS, http_build_query( $params2 ) );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $ch, CURLOPT_COOKIEJAR, "cookie.txt" );
curl_setopt( $ch, CURLOPT_COOKIEFILE, "cookie.txt" );
$output = curl_exec( $ch );
curl_close( $ch );
}
// Step 3: GET request to fetch CSRF token
function getCSRFToken() {
global $endPoint;
$params3 = [
"action" => "query",
"meta" => "tokens",
"format" => "json"
];
$url = $endPoint . "?" . http_build_query( $params3 );
$ch = curl_init( $url );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $ch, CURLOPT_COOKIEJAR, "cookie.txt" );
curl_setopt( $ch, CURLOPT_COOKIEFILE, "cookie.txt" );
$output = curl_exec( $ch );
curl_close( $ch );
$result = json_decode( $output, true );
return $result["query"]["tokens"]["csrftoken"];
}
// Step 4: POST request to upload a file directly
function upload( $csrftoken ) {
global $endPoint;
$params4 = [
"action" => "upload",
"filename" => "Sandboxfile1.jpg",
"file" => curl_file_create("localfile.jpg", "image/jpeg", "Sandboxfile1.jpg"),
"ignorewarnings" => "1",
"token" => $csrftoken,
"format" => "json"
];
$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $endPoint );
curl_setopt( $ch, CURLOPT_POST, true );
curl_setopt( $ch, CURLOPT_HTTPHEADER, array('Content-type: multipart/form-data'));
curl_setopt( $ch, CURLOPT_POSTFIELDS, $params4 );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $ch, CURLOPT_COOKIEJAR, "cookie.txt" );
curl_setopt( $ch, CURLOPT_COOKIEFILE, "cookie.txt" );
$output = curl_exec( $ch );
curl_close( $ch );
echo ( $output );
}
JavaScript
edit/*
upload_file_directly.js
MediaWiki API Demos
Demo of `Upload` module: Sending post request to upload a file directly
MIT license
*/
var fs = require('fs'),
request = require('request').defaults({jar: true}),
url = "https://test.wikipedia.org/w/api.php";
// Step 1: GET request to fetch login token
function getLoginToken() {
var params_0 = {
action: "query",
meta: "tokens",
type: "login",
format: "json"
};
request.get({ url: url, qs: params_0 }, function (error, res, body) {
if (error) {
return;
}
var data = JSON.parse(body);
loginRequest(data.query.tokens.logintoken);
});
}
// Step 2: POST request to log in.
// Use of main account for login is not
// supported. Obtain credentials via Special:BotPasswords
// (https://www.mediawiki.org/wiki/Special:BotPasswords) for lgname & lgpassword
function loginRequest(login_token) {
var params_1 = {
action: "login",
lgname: "bot_username",
lgpassword: "bot_password",
lgtoken: login_token,
format: "json"
};
request.post({ url: url, form: params_1 }, function (error, res, body) {
if (error) {
return;
}
getCsrfToken();
});
}
// Step 3: GET request to fetch CSRF token
function getCsrfToken() {
var params_2 = {
action: "query",
meta: "tokens",
format: "json"
};
request.get({ url: url, qs: params_2 }, function(error, res, body) {
if (error) {
return;
}
var data = JSON.parse(body);
upload(data.query.tokens.csrftoken);
});
}
// Step 4: POST request to upload a file directly
function upload(csrf_token) {
var params_3 = {
action: "upload",
filename: "Sandboxfile1.jpg",
ignorewarnings: "1",
token: csrf_token,
format: "json"
};
var file = {
file: fs.createReadStream('My.jpg')
};
var formData = Object.assign( {}, params_3, file );
request.post({ url: url, formData: formData }, function (error, res, body) {
body = JSON.parse(body);
if (error) {
return;
}
else if (body.upload.result === "Success"){
console.log("File Uploaded :)");
}
});
}
// Start From Step 1
getLoginToken();
MediaWiki JS
edit/*
upload_file_directly.js
MediaWiki API Demos
Demo of `Upload` module: Sending post request to upload a file directly
MIT license
*/
var param = {
filename: 'File_1.jpg',
format: 'json',
ignorewarnings: 1
},
fileInput = $( '<input/>' ).attr( 'type', 'file' ),
submitBtn = $( '<input/>' ).attr( 'type', 'button' ).attr( 'value', 'Upload' ),
api = new mw.Api();
$( '#bodyContent' ).append( [ fileInput, submitBtn ] );
$( submitBtn ).on( 'click', function () {
api.upload( fileInput[ 0 ], param ).done( function ( data ) {
console.log( data.upload.filename + ' has sucessfully uploaded.' );
} ).fail( function ( data ) {
console.log( data );
} );
} );
Example 2: Upload file from URL
editThis requires $wgAllowCopyUploads = true
in the wiki's local settings and an account with the upload_by_url
user right.
POST request
editResponse
editResult |
---|
{
"upload": {
"result": "Success",
"filename": "New_image.jpg",
},
"imageinfo": {
"userid": 42588,
"commonmetadata": [],
"sha1": "0553e6106acdc4d09d9ec5f204aff9e7594193cc",
"bitdepth": 8,
"extmetadata": {
"ObjectName": {
"source": "mediawiki-metadata",
"hidden": "",
"value": "Tempa123"
},
"CommonsMetadataExtension": {
"source": "extension",
"hidden": "",
"value": 1.2
},
"Categories": {
"source": "commons-categories",
"hidden": "",
"value": ""
},
"DateTime": {
"source": "mediawiki-metadata",
"hidden": "",
"value": "2019-03-06 18:24:46"
},
"Assessments": {
"source": "commons-categories",
"hidden": "",
"value": ""
}
},
"descriptionshorturl": "https://test.wikipedia.org/w/index.php?curid=0",
"height": 240,
"mediatype": "BITMAP",
"timestamp": "2019-03-06T18:30:53Z",
"descriptionurl": "https://test.wikipedia.org/wiki/File:New_image.jpg",
"metadata": [
{
"value": 2,
"name": "MEDIAWIKI_EXIF_VERSION"
}
],
"mime": "image/jpeg",
"url": "https://upload.wikimedia.org/wikipedia/test/3/34/New_image.jpg",
"user": "Mansi29ag",
"width": 320,
"size": 27202,
"parsedcomment": "",
"canonicaltitle": "File:New image.jpg",
"html": "<p>A file with this name exists already, please check <strong><a class=\"mw-selflink selflink\">File:New image.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&wpDestFile=New_image.jpg\" class=\"new\" title=\"File:New image.jpg\">File:New image.jpg</a> <div class=\"thumbcaption\"></div></div></div>\n",
"comment": ""
}
}
}
|
Sample code
editPython
edit"""
upload_file_from_url.py
MediaWiki API Demos
Demo of `Upload` module: Post request to upload a file from a URL
MIT license
"""
import requests
S = requests.Session()
URL = "https://test.wikipedia.org/w/api.php"
# 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: While logged in, retrieve a CSRF token
PARAMS_3 = {
"action": "query",
"meta":"tokens",
"format":"json"
}
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 from a URL
PARAMS_4 = {
"action": "upload",
"filename": "new_image.jpg",
"url": "https://farm9.staticflickr.com/8213/8300206113_374c017fc5.jpg",
"format": "json",
"token": CSRF_TOKEN,
"ignorewarnings": 1
}
R = S.post(URL, data=PARAMS_4)
DATA = R.json()
print(DATA)
PHP
edit<?php
/*
upload_file_from_url.php
MediaWiki API Demos
Demo of `Upload` module: Post request to upload a file from a URL
MIT license
*/
$endPoint = "https://test.wikipedia.org/w/api.php";
$login_Token = getLoginToken(); // Step 1
loginRequest( $login_Token ); // Step 2
$csrf_Token = getCSRFToken(); // Step 3
upload( $csrf_Token ); // Step 4
// Step 1: GET request to fetch login token
function getLoginToken() {
global $endPoint;
$params1 = [
"action" => "query",
"meta" => "tokens",
"type" => "login",
"format" => "json"
];
$url = $endPoint . "?" . http_build_query( $params1 );
$ch = curl_init( $url );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $ch, CURLOPT_COOKIEJAR, "cookie.txt" );
curl_setopt( $ch, CURLOPT_COOKIEFILE, "cookie.txt" );
$output = curl_exec( $ch );
curl_close( $ch );
$result = json_decode( $output, true );
return $result["query"]["tokens"]["logintoken"];
}
// Step 2: POST request to log in. Use of main account for login is not
// supported. Obtain credentials via Special:BotPasswords
// (https://www.mediawiki.org/wiki/Special:BotPasswords) for lgname & lgpassword
function loginRequest( $logintoken ) {
global $endPoint;
$params2 = [
"action" => "login",
"lgname" => "bot_user_name",
"lgpassword" => "bot_password",
"lgtoken" => $logintoken,
"format" => "json"
];
$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $endPoint );
curl_setopt( $ch, CURLOPT_POST, true );
curl_setopt( $ch, CURLOPT_POSTFIELDS, http_build_query( $params2 ) );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $ch, CURLOPT_COOKIEJAR, "cookie.txt" );
curl_setopt( $ch, CURLOPT_COOKIEFILE, "cookie.txt" );
$output = curl_exec( $ch );
curl_close( $ch );
}
// Step 3: GET request to fetch CSRF token
function getCSRFToken() {
global $endPoint;
$params3 = [
"action" => "query",
"meta" => "tokens",
"format" => "json"
];
$url = $endPoint . "?" . http_build_query( $params3 );
$ch = curl_init( $url );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $ch, CURLOPT_COOKIEJAR, "cookie.txt" );
curl_setopt( $ch, CURLOPT_COOKIEFILE, "cookie.txt" );
$output = curl_exec( $ch );
curl_close( $ch );
$result = json_decode( $output, true );
return $result["query"]["tokens"]["csrftoken"];
}
// Step 4: POST request to upload a file from a URL
function upload( $csrftoken ) {
global $endPoint;
$params4 = [
"action" => "upload",
"filename" => "Test-Jayprakash12345.jpg",
"url" => "https://farm9.staticflickr.com/8213/8300206113_374c017fc5.jpg",
"ignorewarnings" => "1",
"token" => $csrftoken,
"format" => "json"
];
$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $endPoint );
curl_setopt( $ch, CURLOPT_POST, true );
curl_setopt( $ch, CURLOPT_POSTFIELDS, http_build_query( $params4 ) );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $ch, CURLOPT_COOKIEJAR, "cookie.txt" );
curl_setopt( $ch, CURLOPT_COOKIEFILE, "cookie.txt" );
$output = curl_exec( $ch );
curl_close( $ch );
echo ( $output );
}
JavaScript
edit/*
upload_file_from_url.js
MediaWiki API Demos
Demo of `Upload` module: Post request to upload a file from a URL
MIT license
*/
var request = require('request').defaults({jar: true}),
url = "https://test.wikipedia.org/w/api.php";
// Step 1: GET request to fetch login token
function getLoginToken() {
var params_0 = {
action: "query",
meta: "tokens",
type: "login",
format: "json"
};
request.get({ url: url, qs: params_0 }, function (error, res, body) {
if (error) {
return;
}
var data = JSON.parse(body);
loginRequest(data.query.tokens.logintoken);
});
}
// Step 2: POST request to log in.
// Use of main account for login is not
// supported. Obtain credentials via Special:BotPasswords
// (https://www.mediawiki.org/wiki/Special:BotPasswords) for lgname & lgpassword
function loginRequest(login_token) {
var params_1 = {
action: "login",
lgname: "bot_username",
lgpassword: "bot_password",
lgtoken: login_token,
format: "json"
};
request.post({ url: url, form: params_1 }, function (error, res, body) {
if (error) {
return;
}
getCsrfToken();
});
}
// Step 3: GET request to fetch CSRF token
function getCsrfToken() {
var params_2 = {
action: "query",
meta: "tokens",
format: "json"
};
request.get({ url: url, qs: params_2 }, function(error, res, body) {
if (error) {
return;
}
var data = JSON.parse(body);
editRequest(data.query.tokens.csrftoken);
});
}
// Step 4: POST request to upload a file from a URL
function editRequest(csrf_token) {
var params_3 = {
action: "upload",
filename: "Test-ABCD.jpg",
url: "https://farm9.staticflickr.com/8213/8300206113_374c017fc5.jpg",
ignorewarnings: "1",
token: csrf_token,
format: "json"
};
request.post({ url: url, form: params_3 }, function (error, res, body) {
if (error) {
return;
}
console.log(body);
});
}
// Start From Step 1
getLoginToken();
MediaWiki JS
edit/*
upload_file_from_url.js
MediaWiki API Demos
Demo of `Upload` module: Post request to upload a file from a URL
MIT License
*/
var params = {
action: 'upload',
filename: 'New_image.jpg',
url: 'https://farm9.staticflickr.com/8213/8300206113_374c017fc5.jpg',
ignorewarnings: '1',
format: 'json'
},
api = new mw.Api();
api.postWithToken( 'csrf', params ).done( function ( data ) {
console.log( data );
} );
Example 3: Upload file in chunks
editSince 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
editFor all the chunks except the last chunk you will receive this:
Result 1 |
---|
{
"upload": {
"offset": 5000,
"result": "Continue",
"filekey": "16gqn54g1z98.4g5brp.42588.jpg"
}
}
|
Step 2: Pass filekey parameter for second and further chunks
editYou will obtain the filekey
parameter from the previous continue result as well:
For the last chunk, you will receive this:
Result 2 |
---|
{
"upload": {
"filekey": "16gqn663shqw.pop712.42588.jpg",
"imageinfo": {
"mediatype": "UNKNOWN",
"user": "None",
"comment": "None",
"height": 600,
"size": 48316,
"descriptionurl": "https://test.wikipedia.org/wiki/Special:UploadStash/file/16gqn663shqw.pop712.42588.jpg",
"html": "<p>A file with this name exists already, please check <strong><a class=\"mw-selflink selflink\">File:20190314182304!chunkedupload 4a2a524b5147.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&wpDestFile=20190314182304!chunkedupload_4a2a524b5147.jpg\" class=\"new\" title=\"File:20190314182304!chunkedupload 4a2a524b5147.jpg\">File:20190314182304!chunkedupload 4a2a524b5147.jpg</a> <div class=\"thumbcaption\"></div></div></div>\n",
"canonicaltitle": "File:20190314182304!chunkedupload 4a2a524b5147.jpg",
"extmetadata": {
"DateTime": {
"source": "mediawiki-metadata",
"hidden": "",
"value": "2019-03-14 18:08:10"
},
"CommonsMetadataExtension": {
"source": "extension",
"hidden": "",
"value": 1.2
},
"Assessments": {
"source": "commons-categories",
"hidden": "",
"value": ""
},
"Categories": {
"source": "commons-categories",
"hidden": "",
"value": ""
},
"ObjectName": {
"source": "mediawiki-metadata",
"hidden": "",
"value": "20190314180809!chunkedupload 6d04724f88bd"
}
},
"commonmetadata": [
{
"value": "371DB9CF4042631EC8B5E9963CA5AC16",
"name": "OriginalDocumentID"
},
{
"value": "Adobe Photoshop CC 2015 Windows",
"name": "Software"
}
],
"anon": "",
"timestamp": "2019-03-14T18:23:05Z",
"bitdepth": 8,
"mime": "image/jpeg",
"sha1": "d07dbfcb97861b23fbe6b33efb14856694458450",
"url": "https://test.wikipedia.org/wiki/Special:UploadStash/file/16gqn663shqw.pop712.42588.jpg",
"parsedcomment": "",
"userid": "None",
"metadata": [
{
"value": "371DB9CF4042631EC8B5E9963CA5AC16",
"name": "OriginalDocumentID"
},
{
"value": "Adobe Photoshop CC 2015 Windows",
"name": "Software"
},
{
"value": 2,
"name": "MEDIAWIKI_EXIF_VERSION"
}
],
"width": 600
},
"result": "Success"
}
}
|
Step 3: Final upload using the filekey to commit the upload out of the stash area
editThe result from the final upload will include the complete, accurate imageinfo
object, comparable to what you would get from a non-chunked upload.
Result 3 |
---|
{
"upload": {
"imageinfo": {
"mediatype": "BITMAP",
"user": "Mansi29ag",
"comment": "Upload Testing",
"height": 600,
"size": 48316,
"descriptionurl": "https://test.wikipedia.org/wiki/File:Testfile5.jpg",
"html": "<p>A file with this name exists already, please check <strong><a class=\"mw-selflink selflink\">File:Testfile5.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&wpDestFile=Testfile5.jpg\" class=\"new\" title=\"File:Testfile5.jpg\">File:Testfile5.jpg</a> <div class=\"thumbcaption\"></div></div></div>\n",
"canonicaltitle": "File:Testfile5.jpg",
"extmetadata": {
"DateTime": {
"source": "mediawiki-metadata",
"hidden": "",
"value": "2019-03-14 18:08:10"
},
"CommonsMetadataExtension": {
"source": "extension",
"hidden": "",
"value": 1.2
},
"Assessments": {
"source": "commons-categories",
"hidden": "",
"value": ""
},
"Categories": {
"source": "commons-categories",
"hidden": "",
"value": ""
},
"ObjectName": {
"source": "mediawiki-metadata",
"hidden": "",
"value": "20190314180809!chunkedupload 6d04724f88bd"
}
},
"commonmetadata": [
{
"value": "371DB9CF4042631EC8B5E9963CA5AC16",
"name": "OriginalDocumentID"
},
{
"value": "Adobe Photoshop CC 2015 Windows",
"name": "Software"
}
],
"sha1": "d07dbfcb97861b23fbe6b33efb14856694458450",
"width": 600,
"bitdepth": 8,
"mime": "image/jpeg",
"url": "https://upload.wikimedia.org/wikipedia/test/8/8e/Testfile5.jpg",
"parsedcomment": "Upload Testing",
"descriptionshorturl": "https://test.wikipedia.org/w/index.php?curid=0",
"userid": 42588,
"metadata": [
{
"value": "371DB9CF4042631EC8B5E9963CA5AC16",
"name": "OriginalDocumentID"
},
{
"value": "Adobe Photoshop CC 2015 Windows",
"name": "Software"
},
{
"value": 2,
"name": "MEDIAWIKI_EXIF_VERSION"
}
],
"timestamp": "2019-03-14T18:23:07Z"
},
"result": "Success",
"filename": "Testfile5.jpg"
}
}
|
Sample code
editPython
edit"""
upload_file_in_chunks.py
MediaWiki API Demos
Demo of `Upload` module: Step-by-step process to upload a file in chunks
MIT license
"""
import os
import requests
S = requests.Session()
URL = "https://test.wikipedia.org/w/api.php"
# File path of the image to be uploaded
FILE_PATH = 'f.jpg'
FILE = open(FILE_PATH, 'rb')
FILE_SIZE = os.stat(FILE_PATH).st_size
# Bot credentials
BOT_USERNAME = 'enter_a_bot_username'
BOT_PASSWORD = 'enter_a_bot_password'
def read_chunks(file_object, chunk_size=5000):
"""Return the next chunk of the file"""
while True:
data = file_object.read(chunk_size)
if not data:
break
yield data
def fetch_login_token():
"""Retrieve a login token"""
params = {
"action": "query",
"meta": "tokens",
"type": "login",
"format": "json"
}
res = S.get(url=URL, params=params)
data = res.json()
return data["query"]["tokens"]["logintoken"]
def user_login(login_token, username, password):
"""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 = {
"action": "login",
"lgname": username,
"lgpassword": password,
"format": "json",
"lgtoken": login_token
}
S.post(URL, data=params)
def fetch_csrf_token():
"""While logged in, retrieve a CSRF token"""
params = {
"action": "query",
"meta":"tokens",
"format":"json"
}
res = S.get(url=URL, params=params)
data = res.json()
return data["query"]["tokens"]["csrftoken"]
def upload_file_in_chunks(csrf_token):
"""Send multiple post requests to upload a file in chunks using `stash` mode.
Stash mode is used to build a file up in pieces and then commit it at the end
"""
chunks = read_chunks(FILE)
chunk = next(chunks)
# Parameters for the first chunk
params = {
"action": "upload",
"stash": 1,
"filename": "chunk_test.jpg",
"filesize": FILE_SIZE,
"offset": 0,
"format": "json",
"token": csrf_token,
"ignorewarnings": 1
}
index = 0
file = {'chunk':('{}.jpg'.format(index), chunk, 'multipart/form-data')}
index += 1
res = S.post(URL, files=file, data=params)
data = res.json()
# Pass the filekey parameter for second and further chunks
for chunk in chunks:
params = {
"action": "upload",
"stash": 1,
"offset": data["upload"]["offset"],
"filename": "chunk_test.jpg",
"filesize": FILE_SIZE,
"filekey": data["upload"]["filekey"],
"format": "json",
"token": csrf_token,
"ignorewarnings": 1
}
file = {'chunk':('{}.jpg'.format(index), chunk, 'multipart/form-data')}
index += 1
res = S.post(URL, files=file, data=params)
data = res.json()
# Final upload using the filekey to commit the upload out of the stash area
params = {
"action": "upload",
"filename": "chunk_test.jpg",
"filekey": data["upload"]["filekey"],
"format": "json",
"comment": "Upload Testing",
"token": csrf_token,
}
res = S.post(URL, data=params)
data = res.json()
def main():
""" Four-step process to uploading a file in chunks"""
login_token = fetch_login_token() # Step 1: Fetch login token
user_login(login_token, BOT_USERNAME, BOT_PASSWORD) # Step 2: Login
csrf_token = fetch_csrf_token() # Step 3: Fetch CSRF token
upload_file_in_chunks(csrf_token) # Step 3: Upload a file in chunks
if __name__ == "__main__":
main()
JavaScript
edit/*
upload_file_in_chunks.js
MediaWiki API Demos
Demo of `Upload` module: Step-by-step process to upload a file in chunks
MIT license
*/
var fs = require('fs'),
request = require('request').defaults({jar: true}),
url = "http://dev.wiki.local.wmftest.net:8080/w/api.php",
filename = "My.jpg";
// Step 1: GET request to fetch login token
function getLoginToken() {
var params_0 = {
action: "query",
meta: "tokens",
type: "login",
format: "json"
};
request.get({ url: url, qs: params_0 }, function (error, res, body) {
if (error) {
return;
}
var data = JSON.parse(body);
loginRequest(data.query.tokens.logintoken);
});
}
// Step 2: POST request to log in.
// Use of main account for login is not
// supported. Obtain credentials via Special:BotPasswords
// (https://www.mediawiki.org/wiki/Special:BotPasswords) for lgname & lgpassword
function loginRequest(login_token) {
var params_1 = {
action: "login",
lgname: "bot_username",
lgpassword: "bot_password",
lgtoken: login_token,
format: "json"
};
request.post({ url: url, form: params_1 }, function (error, res, body) {
if (error) {
return;
}
getCsrfToken();
});
}
// Step 3: GET request to fetch CSRF token
function getCsrfToken() {
var params_2 = {
action: "query",
meta: "tokens",
format: "json"
};
request.get({ url: url, qs: params_2 }, function(error, res, body) {
if (error) {
return;
}
var data = JSON.parse(body);
upload(data.query.tokens.csrftoken);
});
}
// Step 4: POST request to upload a file
function upload(csrf_token) {
/*
Send multiple post requests to upload a file in chunks using `stash` mode.
Stash mode is used to build a file up in pieces and then commit it at the end
*/
var fileSizeInBytes = fs.statSync(filename).size;
var headers = {
"Content-Type": "multipart/form-data"
};
var params_3 = {
action: "upload",
stash: "1",
filename: "Sandboxfile1.jpg",
filesize: fileSizeInBytes,
offset: "0",
ignorewarnings: "1",
token: csrf_token,
format: "json"
};
var file = {
file: fs.createReadStream(filename)
};
var formData = Object.assign( {}, params_3, file );
request.post({ url: url, headers: headers, formData: formData }, function (error, res, body) {
body = JSON.parse(body);
if (error) {
return;
}
params_4 = {
action: "upload",
filename: "Sandboxfile1.jpg",
filekey: body.upload.filekey,
comment: "Upload Testing",
token: csrf_token,
format: "json"
};
request.post({ url: url, form: params_4 }, function (error, res, body) {
body = JSON.parse(body);
if (error) {
return;
}
console.log(body.upload.result);
});
});
}
// Start From Step 1
getLoginToken();
MediaWiki JS
edit/*
upload_file_in_chunks.js
MediaWiki API Demos
Demo of `Upload` module: Step-by-step process to upload a file in chunks
MIT license
*/
var param = {
filename: 'TestFile_2.jpg',
format: 'json',
ignorewarnings: 1
},
fileInput = $( '<input/>' ).attr( 'type', 'file' ),
submitBtn = $( '<input/>' ).attr( 'type', 'button' ).attr( 'value', 'Upload' ),
api = new mw.Api();
$( '#bodyContent' ).append( [ fileInput, submitBtn ] );
$( submitBtn ).on( 'click', function () {
api.uploadToStash( fileInput[ 0 ], param ).done( function ( finish ) {
finish( param ).done( function ( data ) {
console.log( data.upload.filename + ' has sucessfully uploaded.' );
} ).fail( function ( data ) {
console.log( data );
} );
} );
} );
Possible errors
editCode | Info |
---|---|
mustbeloggedin | You must be logged in to upload this file. |
permissiondenied | The user group you are a part of does not have the upload right.
|
fileexists-shared-forbidden | A file with this name exists already in the shared file repository. |
chunk-too-small | Minimum chunk size is n bytes for non-final chunks. |
stashfailed | This file did not pass file verification. |
verification-error | Either the data is corrupt or the file extension and the file's MIME type don't correlate. |
windows-nonascii-filename | The server doesn't support filenames with special characters. |
copyuploaddisabled | Upload by URL is disabled. |
See also the section on #Upload warnings above.
Parameter history
edit- 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
Additional notes
edit- 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:
Result |
---|
{
"upload": {
"stage": "uploading",
"offset": 5000,
"result": "Continue"
}
}
|
- 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.
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-- |
See also
edit- API:Login - Allows a user to login
- API:Import - Allows a user to import a page
- Manual:$wgRateLimits - Upload limits according to user groups