Images API

The Image API supports the process of uploading and editing images. These images can be used as a splash images for posts, teaser images, social teasers, as well as for other features where photos are required beyond the scope of posts, such as author creation.

Ratios

Every site on RebelMouse can have its own image cropping ratios configured. The configured ratios reflect the desired use and placement of each image.

By default, the following ratios are configured on RebelMouse:

Title Code Sizes
Super Wide 3x1
  • 1200x400
  • 600x200
Wide 2x1
  • 1200x600
  • 600x300
Medium 3x2
  • 1200x800
  • 600x400
Square 1x1
  • 600x600
  • 300x300
Tall 9x16
  • 700x1245
Widescreen 16x9
  • 1245x700

Uploading images

Upload an image and send its contents as a part of an HTTP request body, or send an image URL as part of a JSON document.

POST /api/1.3/images

Parameters

Name Type Description
image_url String A image URL location - Optional
caption String Caption - Optional
photo_credit String Photo credit - Optional
alt String Alt/Title - Optional

Note

  • Multiple files can be sent as part of an HTTP request. This can be done if image_url is not used as part of the HTTP request.
  • For requests with “multipart/form-data” content type, files should be named with “file”.

Example with multipart/form-data

POST /api/1.3/images HTTP/1.1
HOST: <domain>
x-rmauth: <api key>
authorization: Basic <base64 encoded credentials>
content-type: multipart/form-data; boundary=----WebKitFormBoundarym59pe8dwmBaESksR
content-length: <content length>

------WebKitFormBoundarym59pe8dwmBaESksR
Content-Disposition: form-data; name="file"; filename="image.png"
Content-Type: image/png

<file content>
------WebKitFormBoundarym59pe8dwmBaESksR--

Note

Files must be named with “file” string.

Response

For a single image:

{
             "is_animated_gif": false,
             "task_id": "c3e2a367-24cb-426f-9179-457a0e0ea9ec",
             "height": 511,
             "shortcode_id": "7229TA1498262817",
             "iptc": {
                     "by-line": "",
                     "caption/abstract": ""
             },
             "id": <id>,
             "shortcode_params": {
                     "is_animated_gif": false,
                     "crop_info": "%22%7B%22image%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2Forigin.jpg%22%2C%20%22thumbnails%22%3A%20%7B%22origin%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2Forigin.jpg%22%2C%20%2235x35%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F35x35.jpg%22%2C%20%221200x800%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F1200x800.jpg%22%2C%20%22480x270%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F480x270.jpg%22%2C%20%22700x1245%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F700x1245.jpg%22%2C%20%22980x%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F980x.jpg%22%2C%20%22600x%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F600x.jpg%22%2C%20%22600x600%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F600x600.jpg%22%2C%20%22960x540%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F960x540.jpg%22%2C%20%22600x300%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F600x300.jpg%22%2C%20%22210x%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F210x.jpg%22%2C%20%22300x%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F300x.jpg%22%2C%20%22600x400%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F600x400.jpg%22%2C%20%221200x600%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F1200x600.jpg%22%7D%2C%20%22manual_image_crops%22%3A%20%7B%2216x9%22%3A%20%7B%22width%22%3A%20512%2C%20%22top%22%3A%20222%2C%20%22height%22%3A%20289%2C%20%22left%22%3A%200%2C%20%22sizes%22%3A%20%5B%22960x540%22%2C%20%22480x270%22%5D%7D%2C%20%222x1%22%3A%20%7B%22width%22%3A%20512%2C%20%22top%22%3A%20255%2C%20%22height%22%3A%20256%2C%20%22left%22%3A%200%2C%20%22sizes%22%3A%20%5B%221200x600%22%2C%20%22600x300%22%5D%7D%2C%20%223x2%22%3A%20%7B%22width%22%3A%20512%2C%20%22top%22%3A%20169%2C%20%22height%22%3A%20342%2C%20%22left%22%3A%200%2C%20%22sizes%22%3A%20%5B%221200x800%22%2C%20%22600x400%22%5D%7D%2C%20%221x1%22%3A%20%7B%22width%22%3A%20109%2C%20%22top%22%3A%20402%2C%20%22height%22%3A%20109%2C%20%22left%22%3A%200%2C%20%22sizes%22%3A%20%5B%22600x600%22%5D%7D%2C%20%229x16%22%3A%20%7B%22width%22%3A%20117%2C%20%22top%22%3A%20303%2C%20%22height%22%3A%20208%2C%20%22left%22%3A%200%2C%20%22sizes%22%3A%20%5B%22700x1245%22%5D%7D%7D%7D%22%0A",
                     "original_size": "512x511",
                     "expand": 1
             },
             "thumbnails": {
                     "origin": "https://s3.amazonaws.com/dev-assets.rbl.ms/<id>/origin.jpg",
                     "35x35": "https://s3.amazonaws.com/dev-assets.rbl.ms/<id>/35x35.jpg",
                     "1200x800": "https://s3.amazonaws.com/dev-assets.rbl.ms/<id>/1200x800.jpg",
                     "480x270": "https://s3.amazonaws.com/dev-assets.rbl.ms/<id>/480x270.jpg",
                     "700x1245": "https://s3.amazonaws.com/dev-assets.rbl.ms/<id>/700x1245.jpg",
                     "980x": "https://s3.amazonaws.com/dev-assets.rbl.ms/<id>/980x.jpg",
                     "600x": "https://s3.amazonaws.com/dev-assets.rbl.ms/<id>/600x.jpg",
                     "600x600": "https://s3.amazonaws.com/dev-assets.rbl.ms/<id>/600x600.jpg",
                     "960x540": "https://s3.amazonaws.com/dev-assets.rbl.ms/<id>/960x540.jpg",
                     "600x300": "https://s3.amazonaws.com/dev-assets.rbl.ms/<id>/600x300.jpg",
                     "210x": "https://s3.amazonaws.com/dev-assets.rbl.ms/<id>/210x.jpg",
                     "300x": "https://s3.amazonaws.com/dev-assets.rbl.ms/<id>/300x.jpg",
                     "600x400": "https://s3.amazonaws.com/dev-assets.rbl.ms/<id>/600x400.jpg",
                     "1200x600": "https://s3.amazonaws.com/dev-assets.rbl.ms/<id>/1200x600.jpg"
             },
             "manual_image_crops": {
                     "16x9": {
                             "width": 512,
                             "top": 222,
                             "height": 289,
                             "left": 0,
                             "sizes": [
                                     "960x540",
                                     "480x270"
                             ]
                     },
                     "2x1": {
                             "width": 512,
                             "top": 255,
                             "height": 256,
                             "left": 0,
                             "sizes": [
                                     "1200x600",
                                     "600x300"
                             ]
                     },
                     "3x2": {
                             "width": 512,
                             "top": 169,
                             "height": 342,
                             "left": 0,
                             "sizes": [
                                     "1200x800",
                                     "600x400"
                             ]
                     },
                     "1x1": {
                             "width": 109,
                             "top": 402,
                             "height": 109,
                             "left": 0,
                             "sizes": [
                                     "600x600"
                             ]
                     },
                     "9x16": {
                             "width": 117,
                             "top": 303,
                             "height": 208,
                             "left": 0,
                             "sizes": [
                                     "700x1245"
                             ]
                     }
             },
             "filename": "image_hmXa6R.jpg",
             "width": 512,
             "media_html": "<img src=\"https://s3.amazonaws.com/dev-assets.rbl.ms/<id>/980x.jpg\" id=\"89b1c\" class=\"rm-shortcode\" data-rm-shortcode-id=\"7229TA1498262817\" data-rm-shortcode-name=\"rebelmouse-image\" >",
             "shortcode": "[rebelmouse-image <id> is_animated_gif=false crop_info=\"%22%7B%22image%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2Forigin.jpg%22%2C%20%22thumbnails%22%3A%20%7B%22origin%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2Forigin.jpg%22%2C%20%2235x35%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F35x35.jpg%22%2C%20%221200x800%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F1200x800.jpg%22%2C%20%22480x270%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F480x270.jpg%22%2C%20%22700x1245%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F700x1245.jpg%22%2C%20%22980x%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F980x.jpg%22%2C%20%22600x%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F600x.jpg%22%2C%20%22600x600%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F600x600.jpg%22%2C%20%22960x540%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F960x540.jpg%22%2C%20%22600x300%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F600x300.jpg%22%2C%20%22210x%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F210x.jpg%22%2C%20%22300x%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F300x.jpg%22%2C%20%22600x400%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F600x400.jpg%22%2C%20%221200x600%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F1200x600.jpg%22%7D%2C%20%22manual_image_crops%22%3A%20%7B%2216x9%22%3A%20%7B%22width%22%3A%20512%2C%20%22top%22%3A%20222%2C%20%22height%22%3A%20289%2C%20%22left%22%3A%200%2C%20%22sizes%22%3A%20%5B%22960x540%22%2C%20%22480x270%22%5D%7D%2C%20%222x1%22%3A%20%7B%22width%22%3A%20512%2C%20%22top%22%3A%20255%2C%20%22height%22%3A%20256%2C%20%22left%22%3A%200%2C%20%22sizes%22%3A%20%5B%221200x600%22%2C%20%22600x300%22%5D%7D%2C%20%223x2%22%3A%20%7B%22width%22%3A%20512%2C%20%22top%22%3A%20169%2C%20%22height%22%3A%20342%2C%20%22left%22%3A%200%2C%20%22sizes%22%3A%20%5B%221200x800%22%2C%20%22600x400%22%5D%7D%2C%20%221x1%22%3A%20%7B%22width%22%3A%20109%2C%20%22top%22%3A%20402%2C%20%22height%22%3A%20109%2C%20%22left%22%3A%200%2C%20%22sizes%22%3A%20%5B%22600x600%22%5D%7D%2C%20%229x16%22%3A%20%7B%22width%22%3A%20117%2C%20%22top%22%3A%20303%2C%20%22height%22%3A%20208%2C%20%22left%22%3A%200%2C%20%22sizes%22%3A%20%5B%22700x1245%22%5D%7D%7D%7D%22%0A\" original_size=\"512x511\" expand=1]",
             "image_original_url": "https://s3.amazonaws.com/dev-assets.rbl.ms/<id>/origin.jpg"
}

For multiple images:

The images will all use the same schema and will be returned in the form of an array.

Editing images

Editing an image (in terms of altering its dimensions).

PUT /api/1.3/images/<id>

Parameters

Name Type Description
image_url String A image URL location - Required
manual_image_crops Object Crop setting for resizing image - Optional
caption String Caption - Optional
photo_credit String Photo credit - Optional

Manual Image Crops

This will depend on the ratios configured for each site. The images must be objects whose keys are the ratio codes with the corresponding values containing the following information:

Name Type Description
top Integer Absolute top coordinate
left Integer Absolute left coordinate
height Integer Absolute height coordinate
width Integer Absolute width coordinate
imgHeight Integer Width of the original image
imgWidth Integer Height of the original image

Example

{
     "16x9": {
             "top": 222,
             "left": 0,
             "height": 289,
             "width": 512,
             "imgWidth": 512,
             "imgHeight": 511
     },
     "2x1": {
             "top": 255,
             "left": 0,
             "height": 256,
             "width": 512,
             "imgWidth": 512,
             "imgHeight": 511
     },
     "3x2": {
             "top": 169,
             "left": 0,
             "height": 342,
             "width": 512,
             "imgWidth": 512,
             "imgHeight": 511
     },
     "1x1": {
             "top": 402,
             "left": 0,
             "height": 109,
             "width": 109,
             "imgWidth": 512,
             "imgHeight": 511
     },
     "9x16": {
             "top": 303,
             "left": 0,
             "height": 208,
             "width": 117,
             "imgWidth": 512,
             "imgHeight": 511
     }
}

Response

The response here is the same as when images are uploaded. Only one image can be edited per request.