NAV Navbar
Logo
shell

Introduction

Welcome to the speechkit.io API documentation!

Please read these docs to get a better understanding for how you can use speechkit.io to generate audio from text.

Model orientation/structure

  1. PUBLISHER: By using speechkit.io you’re a publisher, no matter if you’re a blogger or a media conglomerate. Your keys belong to what we call a publisher. Every publisher needs to have at least one news site.
  2. NEWS_SITE: A news site defines every site you run. This is to separate analytics and audio generation etc.
  3. ARTICLES: Every article belongs to a news site.
  4. MEDIA: Every article has one or more media. Each media object defines an audio version of the article it belongs to.
  5. VOICE: A voice as defined from speechkit can be used for synthesizing text to speech. Each media created has a voice attached to it.

Authentication

To authorize, use this code:


curl "https://app.speechkit.io/api/v1/{endpoint}"
  -H "Authorization: Token=token {WRITE_API_KEY}"

The speechkit API uses token authentication. You should have received 2 keys, one write key and one read only key. You can request a key from signing up on our website: https://speechkit.io

Voices

Get All Voices

curl "https://app.speechkit.io/api/v1/voices"

Example response:

[
  {
    "id": 1,
    "language": "en_AU",
    "name": "Nicole"
  },
  {
    "id": 2,
    "language": "en_AU",
    "name": "Russel"
  }
]

This endpoint retrieves all voices available from speechkit

HTTP Request

GET https://app.speechkit.io/api/v1/voices

News sites

Get all your news sites

curl "https://app.speechkit.io/api/v1/news_sites"
  -H "Authorization: Token=token {READ_API_KEY}"

Example response:

[
  {
    "id": 28,
    "title": "Bloomberg",
    "external_id": "bloomberg"
  },
  {
    "id": 29,
    "title": "The Guardian",
    "external_id": "the-guardian"
  },
  {
    "id": 30,
    "title": "Der Tagesspiegel",
    "external_id": "der-tagesspiegel"
  }
]

This endpoint retrieves all news sites that belong to your publisher.

HTTP Request

GET https://app.speechkit.io/api/v1/news_sites

Create a new news site

curl -X POST -d '{"title": "My site"}' "https://app.speechkit.io/api/v1/news_sites"
  -H "Authorization: Token=token {WRITE_API_KEY}"

Example response:

{
  "id": 1,
  "title": "My Site",
  "external_id": "my-site"
}

This endpoint allows you to add sites to your publisher.

HTTP Request

POST https://app.speechkit.io/api/v1/news_sites

Parameters

Parameter Default Description
title “” The name of your site. This is for your own reference

Articles

Get All Articles

curl "https://app.speechkit.io/api/v1/news_sites/{news_site_id}/articles"
  -H "Authorization: Token=token {READ_API_KEY}"

Example response:

[
  {
    "id": "1",
    "url": "https://www.bloomberg.com/news/articles/2016-09-09/google-s-ai-brainiacs-achieve-speech-generation-breakthrough",
    "title": "Google’s DeepMind Achieves Speech-Generation Breakthrough",
    "author": "Jeremy Khan",
    "summary": "",
    "image": "",
    "published_at": "2016-09-09T13:03:00.000Z",
    "body": "Google’s DeepMind Achieves Speech-Generation Breakthrough.....",
    "state": "processed",
    "media": [
      {
        "id": 25726,
        "role": "body",
        "content_type": "application/x-mpegURL",
        "url": "https://d22tbkdovk5ea2.cloudfront.net/audio/news_sites/28/articles/12860/roles/body/voices/37/ab6faf941b7f604a77a60c5ebcacda82.m3u8",
        "created_at": "2017-04-25T13:05:15.536Z",
        "state": "processed"
      },
      {
        "id": 25725,
        "role": "body",
        "content_type": "audio/mpeg",
        "url": "https://d22tbkdovk5ea2.cloudfront.net/audio/news_sites/28/articles/12860/roles/body/voices/37/c9d36a0c25e84d98c5a40f4a6ca510ca.mp3",
        "created_at": "2017-04-25T13:05:06.450Z",
        "state": "processed"
      }
    ]
  }
]

This endpoint retrieves all articles for a news site.

HTTP Request

GET https://app.speechkit.io/api/v1/news_sites/{news_site_id}/articles?page={page}

Parameters

Parameter Default Description
news_site_id none The id of your site you want to fetch all articles for. This can also be your news_sites external id
page 1 Since this is a paginated response you can set the page to get more articles.

Get A Specific Article

curl "https://app.speechkit.io/api/v1/news_sites/{news_site_id}/articles/{article_id}"
  -H "Authorization: Token=token {READ_API_KEY}"

Example response:

{
  "id": "1",
  "url": "https://www.bloomberg.com/news/articles/2016-09-09/google-s-ai-brainiacs-achieve-speech-generation-breakthrough",
  "title": "Google’s DeepMind Achieves Speech-Generation Breakthrough",
  "author": "Jeremy Khan",
  "summary": "",
  "image": "",
  "published_at": "2016-09-09T13:03:00.000Z",
  "body": "Google’s DeepMind Achieves Speech-Generation Breakthrough.....",
  "state": "processed",
  "media": [
    {
      "id": 25726,
      "role": "body",
      "content_type": "application/x-mpegURL",
      "url": "https://d22tbkdovk5ea2.cloudfront.net/audio/news_sites/28/articles/12860/roles/body/voices/37/ab6faf941b7f604a77a60c5ebcacda82.m3u8",
      "created_at": "2017-04-25T13:05:15.536Z",
      "state": "processed"
    },
    {
      "id": 25725,
      "role": "body",
      "content_type": "audio/mpeg",
      "url": "https://d22tbkdovk5ea2.cloudfront.net/audio/news_sites/28/articles/12860/roles/body/voices/37/c9d36a0c25e84d98c5a40f4a6ca510ca.mp3",
      "created_at": "2017-04-25T13:05:06.450Z",
      "state": "processed"
    }
  ]
}

This endpoint retrieves a specified article.

HTTP Request

GET https://app.speechkit.io/api/v1/news_sites/{news_site_id}/articles/{article_id}

Parameters

Parameter Default Description
news_site_id none The id of your site you want to fetch all articles for. This can also be your news_sites external id
article_id none The id of the article you want to request.

Create an article (with audio)

curl -X POST -d '{
    "external_id": 1,
    "title": "The title of my article",
    "published_at": "2017-02-03",
    "author": "John Doe",
    "summary": "My summary of the article",
    "body": "This is the body of the article",
    "media_attributes": [{
        "role": "summary",
        "voice_id": 1
    }, {
        "role": "body",
        "voice_id": 1
    }]
}' "https://app.speechkit.io/api/v1/news_sites/{news_site_id}/articles"
  -H "Authorization: Token=token {WRITE_API_KEY}"

Example response:

{
  "id": "1141123123",
  "url": null,
  "title": "The title of my article",
  "author": "John Doe",
  "summary": "My summary of the article",
  "image": null,
  "published_at": "2017-02-03T00:00:00.000Z",
  "body": "This is the body of the article",
  "state": "unprocessed",
  "media": [
    {
      "id": 208,
      "role": "summary",
      "content_type": "",
      "url": null,
      "created_at": "2017-04-26T11:48:29.069Z",
      "state": "unprocessed",
      "voice": {
        "id": 1,
        "language": "en_GB",
        "name": "en-GB_KateVoice"
      }
    },
    {
      "id": 209,
      "role": "body",
      "content_type": "",
      "url": null,
      "created_at": "2017-04-26T11:48:29.071Z",
      "state": "unprocessed",
      "voice": {
        "id": 1,
        "language": "en_GB",
        "name": "en-GB_KateVoice"
      }
    }
  ]
}

Create an article for your site. Every time you create an article we build the audio for you.

HTTP Request

POST https://app.speechkit.io/api/v1/news_sites/{news_site_id}/articles

Parameters

Parameter Default Description
external_id none The id you want to identify this article as. Needs to be unique
title none The title of the article
published_at none When this article was originally published
author none The name of the author for this article
summary none The summary of the article
body none The complete body of the article
media_attributes none This is an array containing all media files you want produced.
media_attributes[:role] none The role specifies what part of the article you want synthesized
media_attributes[:voice_id] none The voice id you want to use for this synthesis.

Errors

The errors you can expect coming out from Speechkit.io API

Error Code Meaning
401 Unauthorized – If you’re API key does not have access to do what you’re trying to do.
404 Not Found – The speicifed resource you were trying to access does not exist
422 Unprocessable entity – Whatever you tried to create you didn’t pass validation. Reasons are in response.
500 Unknown – Everything else comes back as a 500.