Aviary API Documentation

8/8/2019 Aviary API Documentation

1/3

Table of Contents

Simple API

Simple API Summ ary

Advanced API

Need Help?

API Discussion Forum

Contact us

Code example | Quick ReferenceAPI Documentation

Your API License Code is: 3eeed332f

Simple API

Our simple API is jus t that, simple. Its m eant 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

explanation of how it works right here and placed a quick

reference toward the bottom of the page. We've also

included som e sample code to help you get started.

There are 2 (simple) s teps to implement this API:

Step 1: Launching the Apps

Launching the tools is as s imple 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 s ervers which version of the API you are us ing.

There is one other required parameter you'll need to send and that is "pos turl". 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 m ixdown.

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 websi te, this m akes allowing your users to edit their photo's a snap.

The next parameter we recommend us ing 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 m enu 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 caus e a new window containing the exit url to appear.

Step 2: Handling Creations Saved by the Apps

Upon s aving a Phoenix creations, Aviary's s erver will POST form subm iss ion to the url s pecified in the pos turl

parameter. The fields posted are:

fileguid: A unique string that identifies the file to our s ystem. You can us e this string to reopen the file for editing.

imageurl: The url of the full-sized, flattened png image.

thumbnail: The url of a sm all, square jpg thumbnail (177x177px) of the user's creation. This thumbnail is useful for

displaying lists of images.

Tutorials BlogYou Create Contacts Discover Creations Help Forums0 new

Logout

07/06/10 AviaryAPIDocumentation

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


2/3

name: The nam e the user gave to the creation within Phoenix.

description: The description the user gave to the creation within Phoenix.

tags: The tags the us er 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 pleas e 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, us e 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 Aviarywhen 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 formsubmission 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 thecreation 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 specificuser 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 2below) come from the user's browser (with cookies intact). Omitting this parameter willresult in the post coming from Aviary's server.

defaultfilename : A string that will appear as a default in the "Title" box when the userclicks "Save".

2. Saving Files

Parameters sent in a form pos t to your server upon saving in Phoenix:

fileguid: A unique string that identifies the file to our system. You can use this string toreopen 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.



Aviary API Documentation

Documents

Transcript of Aviary API Documentation