Knowledge Base: images.create

images.create

HTTP Method: POST
Parameters: api_key, user_token, file
Optional Paramters: name, description, url, rating, date_taken, slug, privacy_level_id, image_type_id, shared_token

Uploads a new image file to the site.

Required Parameters

api_key:    API token for your client.
user_token: The users token, received after the user logs in.
file:       A file to be added.

Optional Parameters

name:               The name of the image [string] (255 characters max)
slug:               A slug to be used in the url [string] (30 chars max, alphanumeric and hyphen)
description:        Description of the image [string]
url:                A url for the image, should be fully formed inc. protocol [string]
date_taken:         Unix timestamp of the date the image was taken. [int]
rating:             An integer between 0 and 5 [int]
tags:               A comma separated list of tags. [string]
privacy_level_id:   An id to set the privacy level of the image to. [int]
image_type_id:      An id for the image_type of the image. [int]
shared_token:       Image token for the image if uploading a modified version [string]
short_url:          Boolean value (0 or 1) to generate a short "embr.it"" url and return it in the XML [boolean]

Usage

Simply send a HTTP POST request with Content-Type: multipart/form-data containing the above parameters in the body.

https://api.emberapp.com/images/create

Response

On success: HTTP 200 response.

image:

name:           Name of the image: [string]
token:          Unique identifier for the image. [string]
shared_token:   Token for the parent image if it exists. [string]
description:    Description of the image. [string]
rating:         Rating of the image 0-5. [int]
url:            The original url of the image (if web snap). [string]
date_taken:     Unix timestamp the image was created. [int]
slug:           The slug used by the image on the site unique to the owner. [string]
views:          The number of times the image has been viewed. [int]
created:        Unix Timestamp the image was added. [int]
updated:        Unix Timestamp the image was updated. [int]
files:          An array of file information. [array]
permalink:      URL to the image page on Ember. [string]
short_url:      Short "embr.it" URL to the image page on Ember. [string]
embed_code:     HTML snippet to embed the image on a webpage. [string]

files:

size:           Size flag of the image (sq,t,s,m,l,o) [string]
src:            URL to the image file [string]
width:          Width of the image in pixels. [int]
height:         Height of the image in pixels. [int]
filesize:       Size in bytes of the file. [int]

NOTE: Files sizes for the thumbnails may not be returned
      initially as it can take a few seconds to crop the images.

On failure: HTTP 400 response plus an array of errors.

Example Successful XML Response

<?xml version="1.0"?>
<response>
    <status code="0">OK</status>
    <api>api.images.create</api>
    <item>
        <name>A Newly Uploaded Image</name>
        <token>jgYIN0NtV4nEpcHYtrRmQt26zlFjeaLx</token>
        <shared_token>jgYIN0NtV4nEpcHYtrRmQt26zlFjeaLx</shared_token>
        <description>This is new image uploaded to Ember</description>
        <rating>5</rating>
        <url/>
        <date_taken>1248779218</date_taken>
        <slug>new-image</slug>
        <views>0</views>
        <created>1248779218</created>
        <files>
            <file>
                <size>o</size>
                <width>550</width>
                <height>550</height>
                <filesize>20683</filesize>
                <src>http://emberapp.com/ac94/images/untitled-1/sizes/o.png</src>
            </file>
            <file>
                <size>l</size>
                <width>0</width>
                <height>0</height>
                <filesize>0</filesize>
                <src>http://emberapp.com/ac94/images/untitled-1/sizes/l.png</src>
            </file>
            <file>
                <size>m</size>
                <width>0</width>
                <height>0</height>
                <filesize>0</filesize>
                <src>http://emberapp.com/ac94/images/untitled-1/sizes/m.png</src>
            </file>
            <file>
                <size>s</size>
                <width>0</width>
                <height>0</height>
                <filesize>0</filesize>
                <src>http://emberapp.com/ac94/images/untitled-1/sizes/s.png</src>
            </file>
            <file>
                <size>t</size>
                <width>0</width>
                <height>0</height>
                <filesize>0</filesize>
                <src>http://emberapp.com/ac94/images/untitled-1/sizes/t.png</src>
            </file>
            <file>
                <size>sq</size>
                <width>0</width>
                <height>0</height>
                <filesize>0</filesize>
                <src>http://emberapp.com/ac94/images/untitled-1/sizes/sq.png</src>
            </file>
        </files>
        <permalink>http://emberapp.com/ac94/images/new-image</permalink>
        <short_url>http://embr.it/D</short_url>
        <embed_code>&lt;a href="http://emberapp.com/ac94/images/new-image" title="View Image A Newly Uploaded Image at Ember.com"&gt;&lt;img src="http://emberapp.com/ac94/images/untitled-1/sizes/m.png" title="A Newly Uploaded Image" /&gt;&lt;/a&gt;</embed_code>
    </item>
</response>

Example Unsuccessful XML Response

<?xml version="1.0"?>
<response>
    <status code="1">FAIL</status>
    <api>api.images.create</api>
    <errors>
         <rating>Rating must be numeric, between 0 and 5.</rating>
    </errors>
</response>