API Overview

The YAKiToMe! application programmer's interface (API) gives developers http-level control over the YAKiToMe! text-to-speech conversion and file-management functions. Standard http POST protocol and XML and JSON formats are used throughout.

The API comprises two classes of function calls: action calls and status calls.

• Action calls post data and return a status. Action calls create and delete records in the YAKiToMe! database and invoke the text to speech engine.
• Information calls query the database without affecting its contents.
  
  Action and information call functions are summarized here and described in detail in subsequent sections. Function names are descriptive, so you can easily determine what they are going to do based on the function and argument names. Variables are passed to these calls using standard URL-encoded syntax.
  
  API calls return a response in either JSON or XML formats, per your preference.
  
  A list of api voices and api error codes appears at the end of this document.

API Action Calls

• tts
• share
• delete

API Information Calls

• audio
• status
• balance
• myherds
• voices

API Key

All API calls require your api_key, which is passed as an argument. Keep your api_key secret as API calls that reference this key will be charged against your account.

Your api_key is found on the Login tab of your user profile. Sign in to YAKiToMe! and click your user name link at the top right of the YAKiToMe! page. Click the Login tab to see your api_key.

Call Syntax

Three different call methods are supported: JSON RPC, XML RPC and REST.

JSON RPC and XML RPC Examples

RPC call syntax is constructed from a base URL with the api/call arguments:
    http://yakitome.com/api/call/ ...

followed by the type or response expected, json or xml:
    http://www.yakitome.com/api/call/json/ ...
    http://www.yakitome.com/api/call/xml/ ...

and then the name of the function, in this example, the tts function:
    http://www.yakitome.com/api/call/json/tts ...
    http://www.yakitome.com/api/call/xml/tts ...

followed by variables used to pass data:
    http://www.yakitome.com/api/call/json/tts?api_key=your_api_key&voice=9&speed=5&text=hello+world
    http://www.yakitome.com/api/call/xml/tts?api_key=your_api_key&voice=9&speed=5&text=hello+world



REST Example

Following is a sample python implementation of a REST interface to the YAKiToMe! API. All REST examples in this documentation will reference this function.
    def rest(request_type, api_func, vars):
        # performs RESTful calls to YAKiToMe API functions
        import httplib
        import urllib
        headers = {
            "Content-type": "application/x-www-form-urlencoded",
            "Accept": "text/plain"
            }
        conn = httplib.HTTPConnection('www.yakitome.com')
        conn.request(request_type,
            '/api/rest/%s' % api_func,
            urllib.urlencode(vars),
            headers,
            )
        response = conn.getresponse()
        return response.read()
    # setup variables
    vars = dict(
        api_key='your_api_key',
        voice=9,
        speed=5,
        text='Hello world!'
        )
    # POST data to tts function
    tts_response = rest('POST', 'tts', vars)

The next section describes API action calls in detail.

API Action Calls

API action calls modify the YAKiToMe! database by creating, sharing and deleting audio books.

tts

The tts action call converts text into an audio file using the specified reader voice and speed.

Request

    .../tts?api_key=your_api_key&voice=1&speed=0&text=hello+world

Variables

• api_key
  The value of api_key as it appears on your user profile page.
• voice
  An integer from 1 to 14 corresponding to the desired reader voice.
  Important Reminder! Voices have different API cost rates. Please refer to our voice pricing before using the TTS call.
• speed
  The speaker's relative speed of speaking. 5 is normal. 1 is slowest. 10 is fastest.
• text
  The string of text you wish converted to audio.

Response Signature

The tts call returns the following response in either json or xml formats. Response variables may appear in any order.

Note that the response signature to the tts command is identical to the status command, since status is called after submitting tts. For clarity, we print the signature here.

• book_id
  The YAKiToMe! unique identification number for the newly created book. If the TTS process generates an error message and no book is created, the returned value of book_id will be 0.
• status
  The status of the book conversion process.
• word_cnt
  A count of words in the book.
• iframe
  The iframe URI to be used when embedding the audio player for this audio book in your website.
• herd
  A list of herds with which the book has been shared. By default, the book will be shared only with your base user herd, which is not visible or accessible to others.
• error_code
  An error code associated with the TTS conversion process. See the API Error Codes section for an explanation of all error codes.
• msg
  A message regarding the TTS conversion.
• http_status
  The return http status code (e.g. 200 = OK).

Examples

• JSON RPC
  Convert "Hello world!" into audio using the AT&T Audrey voice reading at a slightly-faster-than-normal speed.
      http://www.yakitome.com/api/call/json/tts?api_key=your_api_key&voice=9&speed=6&text=hello+world
The json response to this successful call might look like this:
      {
        "book_id": 12345,
        "status": "TTS RUNNING",
        "word_cnt": 2,
        "iframe": "http://www.yakitome.com/tts/index/12345/ss14qWjUb8",
        "herd": [1],
        "error_code": 0,
        "msg": "",
        "http_status": 200
    }

• XML RPC
  Call:
      http://www.yakitome.com/api/call/xml/tts?api_key=your_api_key&voice=9&speed=6&text=hello+world!
The xml response might look like this:
      <document>
        <book_id>12345</book_id>
        <status>TTS RUNNING</status>
        <word_cnt>2</word_cnt>
        <iframe>http://www.yakitome.com/tts/index/12345/ss14qWjUb8</iframe>
        <herd>
            <item>1</item>
        </herd>
        <error_code>0</error_code>
        <msg/>
        <http_status>200</http_status>
    </document>
        

• REST
  This is an example of a python implementation of the REST interface, which returns a dict response. It relies upon the definition of the rest function as listed previously.
      vars = dict(
        api_key='your_api_key',
        voice=9,
        speed=5,
        text='Hello world!',
        )
    tts_response = rest('POST', 'tts', vars)
    print tts_response
Produces this:
      {
        "status": "TTS RUNNING",
        "word_cnt": 2,
        "iframe": "http://www.yakitome.com/tts/index/12345/ss14qWjUb8",
        "herd": [1],
        "http_status": 200,
        "msg": "",
        "error_code": 0,
        "book_id": 12345
    }


share

Shares a book with a list of herds. The book will be shared with your base herd regardless of whether you list it in the herds list.

Your base herd is automatically created when you first register your YAKiToMe! account. Your base herd is unlisted and other users may not join it, so by definition, all base-herd content is private and can not be accessed by other users.

All your tts books are automatically shared with your base herd and you are the only member of this herd. It is only when you share an audio book with other herds other than your base herd that other YAKiToMe! users may have the opportunity to access your content, depending on how you set the privacy settings for those herds.

Request

    .../share?api_key=your_api_key&book_id=12345&herds=1,2,3

Variables

• api_key
  The value of api_key as it appears on your user profile page.
• book_id
  The YAKiToMe! unique numeric id for the requested book. If the requested book is invalid, the value of book_id will be set to 0.
• herds
  A comma-separated list of unique herd identification numbers with which the user is priviledged to share the book. The myherds API call will list the herds to which you belong.
  
  IMPORTANT NOTE! You may join a herd that does not allow posting of books. Although the myherds call will list those herds because you joined them, if you specify them in the argument list to the share call you will get a response error code 8: INVALID HERD LIST because you lack permissions to post books to them.

Response Signature

The response signature is the same as it is for the status call (see below).

Examples

• JSON RPC
  Call:
      http://www.yakitome.com/api/call/xml/share?api_key=your_api_key&book_id=12345&herds=1,2
Response
      {
        "book_id": 12345,
        "status": "TTS DONE",
        "word_cnt": 2,
        "iframe": "http://www.yakitome.com/tts/index/12345/ss14qWjUb8",
        "herd": [1, 2],
        "error_code": 0,
        "msg": "",
        "http_status": 200
    }

• XML RPC
  Call:
      http://www.yakitome.com/api/call/xml/share?api_key=your_api_key&book_id=12345&herds=1,3
Note that in this case, the user is not a member of herd #3. This results in the following response:
      <document>
        <status>TTS DONE</status>
        <word_cnt>12</word_cnt>
        <iframe>http://www.yakitome.com/tts/index/12345/ss14qWjUb8</iframe>
        <herd>
            <item>1</item>
            <item>2</item>
        </herd>
        <http_status>200</http_status>
        <msg>INVALID HERD</msg>
        <error_code>8</error_code>
        <book_id>12345</book_id>
    </document>

• REST
      vars = dict(
        api_key='your_api_key',
        book_id=12345,
        herds='1, 2, 3',
        )
    rest('POST', 'share', vars)


delete

This call deletes the specified book and returns a status response packet.

Request

    .../delete?api_key=your_api_key&book_id=12345

Variables

• api_key
  The value of api_key as it appears on your user profile page.
• book_id
  The YAKiToMe! numeric id for the requested book. If the requested book is invalid, the value of book_id will be set to 0.

Response Signature

The response signature is the same as it is for the status call (see below).

Examples

• JSON RPC
  Call:
    http://www.yakitome.com/api/call/json/delete?api_key=your_api_key&book_id=12345
Response:
    {
        "status": "",
        "word_cnt": 0,
        "iframe": "",
        "herd": [],
        "http_status": 200,
        "msg": "DELETED",
        "error_code": 0,
        "book_id": 12345
    }
If you were to run the same command a second time the returned status would be:
    {
        "status": "",
        "word_cnt": 0,
        "iframe": "",
        "herd": [],
        "http_status": 200,
        "msg": "INVALID_BOOK_ID",
        "error_code": 8,
        "book_id": 12345
    }

• XML RPC
      http://www.yakitome.com/api/call/xml/delete?api_key=your_api_key&book_id=12345
• REST
      vars = dict(
        api_key='your_api_key',
        book_id=12345,
        )
    rest('POST', 'delete', vars)


API Information Calls

audio

This call returns the audio files for all the chapters that comprise a book.

Request

  .../audio?api_key=your_api_key&book_id=12345&format=mp3

Variables

• api_key
  The value of api_key as it appears on your user profile page.
• book_id
  The book_id of the book who's status you wish to learn. If you provide an invalid book_id, either for a book that doesn't exist in the database or that you have insufficient privildeges to access, you will get an error message response.
• format
  The format of the audio. Valid formats are mp3 or ogg.

Response Signature

The audio call returns the following response in either json or xml formats. Response variables may appear in any order.

• book_id
  The YAKiToMe! numeric id for the requested book. If the requested book is invalid, the value of book_id will be set to 0.
• status
  The status of the book conversion process. This is either "TTS RUNNING" or "TTS DONE".
• audios
  A list of URIs pointing to the audio files corresponding to each chapter in the book in the order in which they are to be played. These URIs can be embedded directly into html-based audio players.
• word_cnt
  A count of words in the book.
• iframe
  The iframe URI to be used when embedding the audio player for this audio book in your website.
• herd
  A list of herds with which the book has been shared. By default, the book will be shared only with your base user herd, which is not visible or accessible to others.
• http_status
  The return http status code (e.g. 200 = OK).
• error_code
  An error code associated with the TTS conversion process. See the API Error Codes section for an explanation of all error codes.
• msg
  A message regarding the TTS conversion.

Examples

• JSON RPC
      http://www.yakitome.com/api/call/json/audio?api_key=my_api_key&book_id=12345&format=mp3
The json response as it might appear:
      {
        "status": "COMPLETED",
        "audios": [
            "http://www.YAKiToMe.com/audio/download_mp3/audio.name.9157cbcbce6ba34b.617564696f2e6d7033.mp3",
            "http://www.YAKiToMe.com/audio/download_mp3/audio.name.b3b2ef349acc82ad.617564696f2e6d7033.mp3"
            ],
        "word_cnt": 2,
        "iframe": "http://www.yakitome.com/tts/index/12345/ss14qWjUb8",
        "herd": [1],
        "http_status": 200,
        "msg": "",
        "error_code": 0,
        "book_id": 12345
    }
• XML RPC
  http://www.yakitome.com/api/call/xml/audio?api_key=my_api_key&book_id=12345&format=ogg
The xml response as it might appear:
      <document>
        <status>COMPLETED</status>
        <word_cnt>2</word_cnt>
        <audios>
            <item>http://www.YAKiToMe.com/audio/download_mp3/audio.name.9157cbcbce6ba34b.617564696f2e6d7033.ogg</item>
            <item>http://www.YAKiToMe.com/audio/download_mp3/audio.name.b3b2ef349acc82ad.617564696f2e6d7033.ogg</item>
        </audios>
        <iframe>http://www.yakitome.com/tts/index/12345/ss14qWjUb8</iframe>
        <herd>
            <item>1</item>
        </herd>
        <http_status>200</http_status>
        <msg/>
        <error_code>0</error_code>
        <book_id>12345</book_id>
    </document>
• REST
      vars = dict(api_key='your_api_key', book_id=12345, format='ogg')
    rest('POST', 'audio', vars)


status

This call requests the TTS status of a book.

Request

  .../status?api_key=your_api_key&book_id=12345

Variables

• api_key
  The value of api_key as it appears on your user profile page.
• book_id
  The book_id of the book who's status you wish to learn. If you provide an invalid book_id, either for a book that doesn't exist in the database or that you have insufficient privildeges to access, you will get an error message response.

Response Signature

The status call returns the following response in either json or xml formats. Response variables may appear in any order.

• book_id
  The YAKiToMe! numeric id for the requested book. If the requested book is invalid, the value of book_id will be set to 0.
• status
  The status of the book conversion process. This is either "TTS RUNNING" or "TTS DONE".
• word_cnt
  A count of words in the book.
• iframe
  The iframe URI to be used when embedding the audio player for this audio book in your website.
• herd
  A list of herds with which the book has been shared. By default, the book will be shared only with your base user herd, which is not visible or accessible to others.
• http_status
  The return http status code (e.g. 200 = OK).
• error_code
  An error code associated with the TTS conversion process. See the API Error Codes section for an explanation of all error codes.
• msg
  A message regarding the TTS conversion.

Examples

• JSON RPC
      http://www.yakitome.com/api/call/json/status?api_key=my_api_key&book_id=12345
The json response as it might appear:
      {
        "status": "COMPLETED",
        "word_cnt": 2,
        "iframe": "http://www.yakitome.com/tts/index/12345/ss14qWjUb8",
        "herd": [1],
        "http_status": 200,
        "msg": "",
        "error_code": 0,
        "book_id": 12345
    }
• XML RPC
  http://www.yakitome.com/api/call/xml/status?api_key=my_api_key&book_id=12345
The xml response as it might appear:
      <document>
        <status>COMPLETED</status>
        <word_cnt>2</word_cnt>
        <iframe>http://www.yakitome.com/tts/index/12345/ss14qWjUb8</iframe>
        <herd>
            <item>1</item>
        </herd>
        <http_status>200</http_status>
        <msg/>
        <error_code>0</error_code>
        <book_id>12345</book_id>
    </document>
• REST
      vars = dict(api_key='your_api_key', book_id=12345)
    rest('POST', 'status', vars)


balance

Returns the balance of YAKiToMe! API credits remaining in your account.

Request

  .../balance?api_key='your_api_key'

Variables

• api_key
  The value of api_key as it appears on your user profile page.

Response Signature

• balance
  The balance of API credits in your account.

Examples

• JSON RPC
  Call:
      http://www.yakitome.com/api/call/json/balance?api_key=my_api_key
Response:
      {"balance": 9876}

• XML RPC
  Call:
      http://www.yakitome.com/api/call/xml/balance?api_key=my_api_key
Response:
      <document>
        <balance>9876</balance>
    </document>
• REST
      vars = dict(api_key='your_api_key')
    response = rest('POST', 'balance', vars)


myherds

Returns the list of herds to which the YAK user belongs.

Request

    .../myherds?api_key=your_api_key

Variables

• api_key
  The value of api_key as it appears on your user profile page.

Response

A list of dictionaries containing unique herd names and herd ids.

Examples

• JSON RPC
  Call:
      http://www.yakitome.com/api/call/json/myherds?api=your_api_key
Response:
      [
        {"name": "YAK FAQ", "id": 2},
        {"name": "YAK User", "id": 56789},
        {"name": "Project Gutenberg", "id": 126616}
    ]
Note that in this case, the herd YAK User is being used to illustrate the user's base herd.
• XML RPC
  Call:
    http://www.yakitome.com/api/call/xml/myherds?api_key=your_api_key
Response:
    <document>
        <item>
            <name>Super YAK</name>
            <id>1</id>
        </item>
        <item>
            <name>YAK FAQ</name>
            <id>2</id>
        </item>
        <item>
            <name>Project Gutenberg</name>
            <id>126616</id>
        </item>
        <item>
            <name>Sour Puss</name>
            <id>126750</id>
        </item>
        <item>
            <name>test213123123</name>
            <id>126753</id>
        </item>
    </document>

• REST
      vars = dict(api_key='your_api_key')
    response = rest('POST', 'myherds', vars)


voices

Returns a list of voices supported by YAKiToMe! See the next section for a list of supported voices and their unique identification number.

Request

    .../voices?api_key='your_api_key'

Variables

• api_key
  The value of api_key as it appears on your user profile page.

Examples

• JSON RPC
  Call:
      http://www.yakitome.com/api/call/json/voices?api_key='your_api_key'
Response:
    [
        {"lang": "Fran\u00e7ais", "voice": "AT&T Alain", "id": 1},
        {"lang": "Espa\u00f1ol", "voice": "AT&T Alberto", "id": 2},
        {"lang": "Fran\u00e7ais", "voice": "AT&T Arnaud", "id": 3},
    ...
        {"lang": "English US", "voice": "AT&T Lauren", "id": 12},
        {"lang": "English US", "voice": "AT&T Mike", "id": 13},
        {"lang": "English US", "voice": "MS Anna", "id": 14}
    ]
• XML RPC
  Call:
      http://www.yakitome.com/api/call/xml/voices?api_key='your_api_key'
Response:
      <document>
        <item>
            <lang>Français</lang>
            <voice>AT&T Alain</voice>
            <id>1</id>
        </item>
        <item>
            <lang>Español</lang>
            <voice>AT&T Alberto</voice>
            <id>2</id>
        </item>
        <item>
            <lang>Français</lang>
            <voice>AT&T Arnaud</voice>
            <id>3</id>
        </item>
    ...
        <item>
            <lang>English US</lang>
            <voice>AT&T Lauren</voice>
            <id>12</id>
            </item>
        <item>
            <lang>English US</lang>
            <voice>AT&T Mike</voice>
            <id>13</id>
        </item>
        <item>
            <lang>English US</lang>
            <voice>MS Anna</voice>
            <id>14</id>
        </item>
    </document>
• REST
  response = rest('GET', 'voices', dict(api_key='your_api_key'))


API Voices

Voices Ordered by Voice ID

Voice ID	Reader Name	Gender	Language
1	AT&T Alain	Male	French
2	AT&T Alberto	Male	Spanish
3	AT&T Arnaud	Male	French
4	AT&T Juliette	Female	French
5	AT&T Klara	Female	German
6	AT&T Reiner	Male	German
7	AT&T Rosa	Female	Spanish
8	AT&T Anjali	Female	English UK
9	AT&T Audrey	Female	English UK
10	AT&T Crystal	Female	English US
11	AT&T Julia	Female	English US
12	AT&T Lauren	Female	English US
13	AT&T Mike	Male	English US
14	MS Anna	Female	English US

Voices Ordered by Language and Gender

Language	Gender	Reader Name	Voice ID
English US	Female	AT&T Crystal	10
English US	Female	AT&T Julia	11
English US	Female	AT&T Lauren	12
English US	Male	AT&T Mike	13
English US	Female	MS Anna	14
English UK	Female	AT&T Anjali	8
English UK	Female	AT&T Audrey	9
Spanish	Female	AT&T Rosa	7
Spanish	Male	AT&T Alberto	2
French	Female	AT&T Juliette	4
French	Male	AT&T Alain	1
French	Male	AT&T Arnaud	3
German	Female	AT&T Klara	5
German	Male	AT&T Reiner	6

API Error Codes

Code	Message	Description
0	---	Normal termination
1	INVALID API_KEY	Invalid api_key or none supplied
2	INSUFFICIENT API CREDIT	Not enough credit to pay for TTS conversion
3	MISSING TEXT	No text given during a tts call
4	INVALID VOICE	Not a valid voice ID
5	INVALID SPEED	Not a valid speed value
6	MISSING BOOK_ID	No book_id given
7	INVALID BOOK_ID	Book doesn't exist or API caller has insufficient priviledges to access book
8	INVALID HERD	Herd entry doesn't exist or API caller has insufficient prviledges to access or share book with one or more of the given herds
9	INSUFFICIENT PRIVILEDGES	API user has insufficient priviledges to execute specified action