07/06/10 Aviary API Documentation

0 new
You Create Contacts Discover Creations Tutorials Help Forums Blog
Logout

API Documentation Code example | Quick Reference

Table of Contents

Your API License Code is: 3eeed332f Sim ple API

Sim ple API Sum m ary
Advanced API
Simple API
Our simple API is just that, simple. Its meant to provide a
quick way to edit images and send the newly edited file's
information back to your server. We've included a detailed Need Help?
explanation of how it works right here and placed a quick
reference toward the bottom of the page. We've also
API Discussion Forum
included some sample code to help you get started.
Contact us
There are 2 (simple) steps to implement this API:

Step 1: Launching the Apps

Launching the tools is as simple as opening a new browser window and pointing it to this url:

Phoenix:
http://aviary.com/launch/phoenix?apil=3eeed332f

Raven:
http://aviary.com/launch/raven?apil=3eeed332f

Peacock:
http://aviary.com/launch/peacock?apil=3eeed332f

Toucan:
http://aviary.com/launch/toucan?apil=3eeed332f

Falcon:
http://aviary.com/launch/falcon?apil=3eeed332f

Myna:
http://aviary.com/launch/myna?apil=3eeed332f

The "&apil=3eeed332f" is the code that identifies to our servers which version of the API you are using.

There is one other required parameter you'll need to send and that is "posturl". This is the url to which Aviary will send
your new creation's information. More about that in step 2. For Myna, there is an additional parameter called
"mixdownposturl" which will be used to send your server information about the final mp3 that results from a mixdown.

If you'd like to preload an image from the web into Phoenix, you can use the "loadurl" parameter. If you run a photo
storage website, this makes allowing your users to edit their photo's a snap.

The next parameter we recommend using is "userhash". This is a unique identifier for your user on your website
(preferrably one that does not get displayed on your website) that Aviary will send back to your server in step 2. This will
help you identify the owner of the file that Aviary has just saved. Of course, you can include this information on the
"posturl" querystring and ignore this parameter if you prefer.

To give you control over what happens after a user saves their creation, we've added 2 new parameters. "exiturl" lets
you specify a url that the user is returned to when clicking File -> Exit from them menu bar or the "Back to Site" link in
the header. Adding the parameter "exiturltarget" with a value of "replace" ("exiturl=replace") will redirect the window
containg the app to the exit url. Omitting this parameter will cause a new window containing the exit url to appear.

Step 2: Handling Creations Saved by the Apps

Upon saving a Phoenix creations, Aviary's server will POST form submission to the url specified in the posturl
parameter. The fields posted are:

fileguid: A unique string that identifies the file to our system. You can use this string to reopen the file for editing.
imageurl: The url of the full-sized, flattened png image.
thumbnail: The url of a small, square jpg thumbnail (177x177px) of the user's creation. This thumbnail is useful for
displaying lists of images.

http://aviary.com/apidocs 1/3
07/06/10 Aviary API Documentation
name: The name the user gave to the creation within Phoenix.
description: The description the user gave to the creation within Phoenix.
tags: The tags the user gave to the creation within Phoenix.

In Myna only, after making a mixdown, an additional field will be added to this POST:

mixdownurl: The url of the mp3 file for this creation.

Upon receiving this POST from Aviary, your server should store this info in your database. It should also take this
opportunity to download the png from the "imageurl" parameter as well as the jpeg from "thumbnail" so your website
can show these images. The url's we provide will not be active forever so please download the files within 24 hours.

Reopening a creation
If your user wants to edit a creation that they've previously saved, just follow the instrunctions in Step 1. However, in
place of the loadurl, use the fileguid value (&loadurl={fileguidvaluehere}). Make sure you use the same userhash you
sent in Step 1.

Simple API Summary

1. Launching the Apps

Basic URL - http://aviary.com/flash/aviary/index.aspx

Falcon's URL - http://aviary.com/launch/falcon

Required Parameters:

apil=3eeed332f: Your API License Code

posturl: The url of a script on your server that will handle a form submission from Aviary
when a creation is saved. See section 2 for the form fields that are submitted.
mixdownposturl: (Myna only) The url of a script on your server that will handle a form
submission from Aviary when a mixdown of the creation is created.

Optional Parameters:

loadurl: The url of an image to pre-load for editing into the Aviary application
userhash: A string (255 characters max) that uniquely identifies the owner of the
creation being made. We recommend using a random string for each user that is not
displayed anywhere on your site. This will be used to associate a creation to a specific
user for the purpose of retrieving that user's creations.
exiturl: The url to which the user is taken to after closing the Aviary application.
exiturltarget: Setting this to "replace" will redirect the application window to the "exiturl"
upon exiting. Leave this out to open it in a new window.
postagent: Set this parameter to "client" to have the post to your server (see Section 2
below) come from the user's browser (with cookies intact). Omitting this parameter will
result in the post coming from Aviary's server.
defaultfilename: A string that will appear as a default in the "Title" box when the user
clicks "Save".

2. Saving Files
Parameters sent in a form post to your server upon saving in Phoenix:

fileguid: A unique string that identifies the file to our system. You can use this string to
reopen the file for editing.
imageurl: The url of the full-sized, flattened png image.
mixdownurl: (Myna only) The url of the mp3 created by the mixdown process.
thumbnail: The url of a small, square jpg thumbnail (177x177px) of the user's creation.
This thumbnail is useful for displaying lists of images.
name: The name the user gave to the creation within Aviary.
description: The description the user gave to the creation within Aviary.
tags: The tags the user gave to the creation within Aviary.

Advanced API
Available upon request.

http://aviary.com/apidocs 2/3
07/06/10 Aviary API Documentation

Home | Tools | Blog | About | Help | Contact Us | Tw itter | Facebook | API Terms | Privacy | ©2010 Aviary, Inc. All rights reserved.

Page generated in 16 ms.

http://aviary.com/apidocs 3/3