Posting to the Tumblr V2 API in Perl

As part of a larger intellectual exercise, I started investigating the viability of posting to Tumblr programatically. The old (V1) API is pretty simple to use but lacks security; not to mention: it’s the old API. So API V2 it is. In order to access a large portion of the V2 API, you need to use OAuth for the authentication. This means that you can grant access to applications and revoke access individually.

Getting an application set up to use OAuth is a multi-step process (outlined here) but basically works like this:

  • Generate consumer key and consumer secret
  • Request request token and token secret
  • Grant application access (requires user intervention)
  • Request access token and token secret
  • Use consumer key, consumer secret, access token and token secret to post content

Some services may do most of this work for you, but Tumblr does not. When you register an application, one of the fields you fill in is the ‘callback url’. This is the URL that you will be directed to after you authorize a token for that application. When this happens (and if you’re setting up this application for your own use, it doesn’t matter where you’re redirected to) you’ll be provided with a oauth verifier token (VIA URL parameter). For my own simplicity sake, I put a PHP script on my web server that would echo the contents of that parameter:

<?php echo $_GET["oauth_verifier"]; ?>

I accidentally found a Perl script meant for walking you through the process of getting tokens. For useability sake, I made some slight modifications to the script to make it a little more extensible and you can get it here.

Running this script will require that you at least set the consumer key and consumer secret but these are the configurable options:

  1. my $consumer_key = 'CONSUMER_KEY';
  2. my $consumer_secret = 'CONSUMER_SECRET';
  3. my $request_url = '';
  4. my $access_url = '';
  5. my $authorize_url = '';

And you should get an output similar to:

Got Request Token xkbGIXIgi2Shz1tufLvCBpSTVJCCqcchb4yBm38EHYirE5uripe
Got Request Token Secret T6SkINaD9gAh7ElEPBB2vQFkpmGqQjpPqFqGtW5TaN8HXMWUvoE
Go to
Go to the above URL, authorize and give me the oauth_verifier token. Then press <ENTER>
Got Access Token H8JrcegT6gpMUfnqjJBIkRNWi9ecFWeZ5UIcn9jiywEua5VIpml
Got Access Token Secret FEQlJHPwoOhIYZvpL9xKzhpLXo3q77uqVT4HW75DSGo2cidZLzR

Now that you have the consumer keys and access tokens, you can post to Tumblr!
There are already several modules that will handle OAuth requests. I wanted to stick with something simple, so I stuck with the LWP::Authen::OAuth. This module makes it very easy to make OAuth requests, since you provide it with the information it needs for the authentication and the request itself and that’s it. The following code is a snippet of what I was using; it also prints the contents of the request just so I could see what was happening:

use LWP::Authen::OAuth;
use strict;
my $ua = LWP::Authen::OAuth->new(
                oauth_consumer_key => 'CONSUMER_KEY',
                oauth_consumer_secret => 'CONSUMER_SECRET',
                oauth_token => 'TOKEN',
                oauth_token_secret => 'TOKEN_SECRET',
print $ua->post( '{base_hostname}/post', [
            type => 'photo',
            link => 'CALLBACK_URL',
            source => 'SOURCE_URL',
            caption => 'CAPTION',
            tags => 'TAG1,TAG2',

While I’ve not tried more complicated content, this blog post indicated that “UTF8-formatted strings get corrupted”. So he provided a more verbose example using the lower-lever Net::OAuth module.



Hey man, great tutorial! I’ve really been digging into the tumblr API with perl, but I’ve had one giant hiccup – photo uploads. My data is local, so I have to use the “data’ parameter. The tumblr API page does a poor job saying exactly what they want in the data parameter. Have you been able to upload images to Tumblr successfully?

kid strangelove | May 20, 01:19 PM | permalink

In the same way that specify source=>$URL you should also be able to specify data=>$blob.

The part of the API documentation this is referenced is here. It says that you can’t specify more than 10mb, and that it’s either source or data.

Now, I’ve tried to use this before without much luck, I get a 401/Not Authorized.

Hopefully you’ll have better luck, or someone else will point out where we’ve gone wrong.


Ryan | May 22, 06:13 PM | permalink

Thanks for the write up. I had trouble to extract the correct oauth_verifier token as I did not know, that I’m not allowed to add the #_=_ at the end of the token url string.
A hint about this would be cool. Or to extract this in the script from the complete URL returned by tumblr :-)

Alex | Jul 11, 06:23 AM | permalink

Add Your Comment

  Textile help