Find file
Fetching contributors…
Cannot retrieve contributors at this time
143 lines (114 sloc) 3.94 KB

The Meme Captain API is currently experimental and may change.

Creating a Meme Image

HTTP POST a JSON body to For this request set the Accept and Content-Type headers to application/json. Example JSON body:

  "src_image_id": "MDyuQg",
  "private": false,
  "captions_attributes": [
      "text": "top text",
      "top_left_x_pct": 0.05,
      "top_left_y_pct": 0,
      "width_pct": 0.9,
      "height_pct": 0.25
      "text": "bottom text",
      "top_left_x_pct": 0.05,
      "top_left_y_pct": 0.75,
      "width_pct": 0.9,
      "height_pct": 0.25

Required Fields

  • src_image_id
  • text
  • top_left_x_pct
  • top_left_y_pct
  • width_pct
  • height_pct

Optional Fields

  • private - true if the meme is private (defaults to false), a private meme will not show up on public pages on the web site

Caption Coordinates

The top left corner of the image has the coordinates (0, 0).

  • top_left_x_pct - the x coordinate of the top left corner of the caption as a percentage of the total image width
  • top_left_y_pct - the y coordinate of the top left corner of the caption as a percentage of the total image height
  • width_pct - the width of the caption as a percentage of the total image width
  • height_pct - the height of the caption as a percentage of the total image height


If the request is accepted you will receive an HTTP 202 Accepted response. The Location header will contain a URL to poll. The same URL will also be in the status_url field of the response body.

Poll the URL returned in the Location header until it returns 303 (See Other). When it returns 303, the image is finished processing and the Location header will contain the URL of the image. Under normal circumstances creation of the image should be instantaneous.

If there was an error processing the image, the error field in the JSON response will contain an error message. If the error field is null, no error has occurred. If there is an error message, the client should stop polling.

Polling Responses

  • 200 - The image is still being processed. Keep polling.
  • 303 - The image is finished. Its URL is in the Location header.
  • 404 - Image not found.

Error Responses

If the src_image_id in the initial POST request references a source image that is not found or is not finished being created, the response code will be 404.

If there are validation errors the response code will be 422 Unprocessable Entity. The body will contain JSON with the errors.

Shell script example

On every meme image page, there is an API button that shows a shell script that recreates that image using the API. This script can also be used to determine text position parameters for an API request.

Ruby example

#!/usr/bin/env ruby

require 'json'
require 'net/http'

json_request = {
  src_image_id: 'MDyuQg',
  private: false,
  captions_attributes: [
      text: 'top text',
      top_left_x_pct: 0.05,
      top_left_y_pct: 0,
      width_pct: 0.9,
      height_pct: 0.25
      text: 'bottom text',
      top_left_x_pct: 0.05,
      top_left_y_pct: 0.75,
      width_pct: 0.9,
      height_pct: 0.25

create_uri = URI('')
create_request =
create_request['Accept'] = 'application/json'
create_request['Content-Type'] = 'application/json'
create_request.body = json_request.to_json

Net::HTTP.start(create_uri.hostname, create_uri.port) do |http|
  create_response = http.request(create_request)

  poll_uri = URI(create_response['Location'])
  poll_request =
  10.times do
    poll_response = http.request(poll_request)
    puts "poll response #{poll_response.code}"
    if poll_response.code == '303'
      puts poll_response['Location']
    parsed_body = JSON.parse(poll_response.body)
    fail(parsed_body['error']) if parsed_body['error']
    sleep 3