Images API
==========

.. contents:: :depth: 2

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.

.. code::

   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
``link_url``     String Link's destination, it wraps image markup with a link element - Optional
``title``        String Link's title, it renders a title attribute in link - Optional
``link_target``  String If ``"true"`` is received, it adds target="_blank" in image markup - 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
********************************

.. code::

   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:

.. code:: json
   :force:

   {
		"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).


.. code::

   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
~~~~~~~

.. code::

   {
	"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.