API setup

This guide explains how to use our API to convert articles into audio articles.

Prerequisites

To use SpeechKit you will need a SpeechKit account. You can create one here.

1. Login to your SpeechKit account

You can login to SpeechKit using the email/password or Google credentials you used to create an account.

If you're an enterprise customer, you can login to SpeechKit using the email/password provided to you by your account manager.

2. Create a new project

To get started you will need to create a project. Every SpeechKit account can have multiple projects. For example, your company may have two news websites. In this case, each website should have its own project. For Example, News UK, which owns The Times and The Sun, would create a project for each of them.

2.1. Select API

To start producing audio articles via an API, you will need to create an API project in your SpeechKit account.

2.2. Enter your website details

Once you have selected the API option, you will need to enter the following details about your website.

  1. Website name. For example: BBC News.

  2. Website URL. For example: . https://www.bbc.co.uk/news.

3. Choose a voice to read your articles

Once you have entered your website details, you will need to select the language and voice(s) that will be used to produce your audio articles:

3.1. Select a language

  1. Select the language that your articles are written in. For example: English (US).

3.2. Select a voice

  1. Select a voice to read your title. For example: Joanna (Newscaster) (Female).

  2. Select a voice to read the rest of the article. For example: Matthew (male).

With the form now complete, click Finish Setup to finish creating the project.

4. Using the API to create, update and fetch audio

Once you have Finished Setup, you can get your API credentials from the project settings page. You will need both the API key and the Project ID to interact with the API, so have these available for the next steps.

4.1. Create an audio article

You can create an audio article using the POST request. Use the endpoint below to send your request to, providing all required parameters in the path or body of the request, along with any optional parameters you would like to use.

If you are using the API to both create and retrieve your audio, we advise including a unique external_id with your request that relates to the content, so you can easily retrieve the audio when necessary using this same ID.

post
Post request to create an audio article

https://app.speechkit.io/api/v3/projects/{project_id}/audio
This endpoint allows you to add a new audio article to your project. All request parameters can be seen in the table below and example responses can also be seen in the response tab.
Request
Response
Request
Path Parameters
project_id
required
integer
ID of the project you wish to add audio to
Body Parameters
external_id
optional
string
Your own internal ID
body
required
string
Text content of your article (max 100,000 chars)
title
optional
string
Title of your article
author
optional
string
Author of the article
article_url
optional
string
Web page (URL) where the article is located
api_key
required
string
Your API key
Response
200: OK
Audio successfully created within the project.
{
"id": 999,
"external_id": "123-a",
"state": "unprocessed",
"media": [
{
"id": 999,
"content_type": "mp3",
"url": []
}
],
"deleted": false
}
400: Bad Request
Invalid request.
401: Unauthorized
Invalid API key.
404: Not Found
Wrong project ID.

4.2. Fetch an audio article by ID

Once you have created an audio article, it will be available via the API fetch. You can use the endpoint below to do this, making sure you include the project ID and audio ID in the path, along with your API key as a query parameter.

get
Get request to fetch audio article by ID

https://app.speechkit.io/api/v3/projects/{project_id}/audio/{audio_id}
This endpoint allows you to retrieve details of an audio article using its ID.
Request
Response
Request
Path Parameters
project_id
required
integer
ID of the project
audio_id
required
integer
ID or external_id of the audio
Query Parameters
api_key
required
string
Your API key
Response
200: OK
Audio edition successfully retrieved.
{
"id": 999,
"external_id": "123-a",
"state": "processed",
"media": [
{
"id": 999,
"content_type": "mp3",
"url": "http://link.to/the/file.mp3"
}
],
"deleted": false
}
401: Unauthorized
Invalid API key.
404: Not Found
Wrong project ID or audio ID.

If you would prefer to fetch a list of audio article under a specific project, you can Fetch audio articles by project first, to see which audio articles are available and follow with the request for a specific audio article after using the endpoint above.

You can also Update an audio article or Delete an audio article via the API - follow the links for related instructions on how to do these.

If you have any questions, comments or issues please contact support@speechkit.io.