API integration

Before you start using our API, you will need to create a project in SpeechKit. This will give you access to a Project ID and API key. You can also set your default voices in the 'Settings (General)' section of the project dashboard.

The SpeechKit API is organized around REST. Our API returns JSON-encoded responses and uses standard HTTP response codes, authentication, and verbs.

Requests should include content-type: application/json.

Prepare content

Prior to using the API to create audio, you should make sure that your content is in a suitable format to be processed.

We recommend submitting title and body content in HTML. This is because HTML provides additional context that enables better conversion into speech synthesis markup language (SSML) and therefore better conversion into audio.

Submit HTML

The HTML markup is submitted via a JSON request, so make sure it is valid JSON by escaping quotation marks and forward slashes:

<h4 class=\"line\" data-line=\"0\">h4 Heading<\/h4>
<p class=\"line\" data-line=\"2\"><strong>This is bold text<\/strong><\/p>
<p class=\"line\" data-line=\"4\"><em>This is italic text<\/em><\/p>

Submit markdown

You can also submit content in markdown.

#### Heading
**This is bold text**
_This is italic text_

Submit plain text

For plain text, use \n\n to signify a new paragraph.

Heading
This is bold text
This is italic text

Authentication

The SpeechKit API uses API keys to authenticate requests. You can view the API key for your project by going to the 'Settings (General)' section of your project dashboard.

️Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, etc.

API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Multiple voices per audio

You can create audios using multiple voices by adding a data-speechkit-voice=* data attribute to a <p> element (when using HTML), where the * is a Voice ID from our list of voices.

For example, the following HTML, SpeechKit data attributes, and voice IDs would produce the following audio:

<p data-speechkit-voice="492" class="line" data-line="1" >This is the first paragraph.</p>
<p data-speechkit-voice="453" class="line" data-line="2" >This is a sub heading.</p>
<p data-speechkit-voice="492" class="line" data-line="3" >This is the second paragraph.</p>

Receive event notifications with web hooks

You can use our webhooks to recieve notifications when an event takes place. You can enter your webhook endpoint in the 'Settings (Webhooks)' section of your project dashboard.

SpeechKit webhooks are POST requests with JSON data. Event types are in the action_type field and include audio.created, audio.updated, and audio.deleted.

Audio created or updated

{
   "id":284568,
   "external_id":"629bb065-9699-4d85-b069-890884b6685c",
   "state":"processed",
   "metadata":{

   },
   "media":[
      {
         "id":2236642,
         "content_type":"m3u8",
         "url":"https://speechkit-staging.s3.amazonaws.com/audio/projects/3438/podcasts/284568/media/2ffc1bff61a0779e5d07b78f32db4c9e.m3u8",
         "duration":2.564622
      },
      {
         "id":2236641,
         "content_type":"mp3",
         "url":"https://speechkit-staging.s3.amazonaws.com/audio/projects/3438/podcasts/284568/media/2d6e5234b1f940c0f164066f1d6fa166_compiled.mp3",
         "duration":2.592
      }
   ],
   "image_url":null,
   "deleted":false,
   "action_type":"audio.updated",
   "project_id":"3438"
}

Audio deleted

{
   "id":284568,
   "external_id":"629bb065-9699-4d85-b069-890884b6685c",
   "state":"processed",
   "metadata":{

   },
   "media":[

   ],
   "image_url":null,
   "deleted":true,
   "action_type":"audio.deleted",
   "project_id":"3438"
}