Add a photo.

Similar to pwg.images.addChunk + pwg.images.add, but simpler and better suited for Piwigo 2.7+


This method requires authentication with an administrator user.

This method requires an HTTP POST request.

This method also requires a pwg_token (session valid key).


Important note: we are uploading a file, so the HTTP request encoding must be set to “form-data”.

image /path/to/file.jpg mandatory the uploaded file. JPG or PNG files only.
category 123 mandatory the identifier of the destination category, use pwg.categories.getList to find existing categories
pwg_token verylongstring mandatory this is a session key, once identified you can get it with method pwg.session.getStatus
chunks 12 optional number of expected chunks
chunk 0 optional current chunk number, from 0 to chunks-1
name A nice title optional the title of your photo, don't make it too long (use the comment to go into details
name A nice title optional the title of your photo, don't make it too long (use the comment to go into details
level 2 optional (default = 0) privacy setting. See an example in your Piwigo on screen Administration > Photos > Add. 0 is for everybody, 8 is for admins only


Here comes a full example in Perl language (see the most updated version on on source code repository):

# Usage
# perl --url= --user=admin --password=secret --file=photo.jpg --album_id=9
use strict;
use warnings;
use JSON;
use LWP::UserAgent;
use Getopt::Long;
use POSIX qw(ceil floor);
use Digest::MD5 qw/md5 md5_hex/;
use File::Slurp;
use File::Basename;
my %opt = ();
our %conf = (
    chunk_size => 500_000,
our $ua = LWP::UserAgent->new;
$ua->agent('Mozilla/ 1.56');
my $result = undef;
my $form = {
    method => 'pwg.session.login',
    username => $opt{username},
    password => $opt{password},
$result = $ua->post(
my $response = $ua->post(
        method => 'pwg.session.getStatus',
my $pwg_token = from_json($response->content)->{result}->{pwg_token};
my $content = read_file($opt{file});
my $content_length = length($content);
my $nb_chunks = ceil($content_length / $conf{chunk_size});
my $chunk_pos = 0;
my $chunk_id = 0;
while ($chunk_pos < $content_length) {
    my $chunk = substr(
    # write the chunk as a temporary local file
    my $chunk_path = '/tmp/'.md5_hex($opt{file}).'.chunk';
    open(my $ofh, '>'.$chunk_path) or die "problem for writing temporary local chunk";
    print {$ofh} $chunk;
    $chunk_pos += $conf{chunk_size};
    my $response = $ua->post(
            method => 'pwg.images.upload',
            chunk => $chunk_id,
            chunks => $nb_chunks,
            category => $opt{album_id},
            pwg_token => $pwg_token,
            file => [$chunk_path],
            name => basename($opt{file}),
        'Content_Type' => 'form-data',
        'chunk %03u of %03u for "%s"'."\n",
    if ($response->code != 200) {
        printf("response code    : %u\n", $response->code);
        printf("response message : %s\n", $response->message);
$result = $ua->get(
        method => 'pwg.session.logout'
Back to top
dev/webapi/pwg.images.upload.txt · Last modified: 2015/06/16 09:51 by plg
github twitter newsletter Donate © 2002-2023 · Contact