NAV Navbar
shell

Introduction

Welcome to the Resemble API! The Resemble API is a premium feature that programatically allows users to access and create resources on Resemble.

Please note that this early preview of our API. In coming months we will be updating our API to provide more robust information. For specific requests please email at team@resemble.ai.

Authentication

To authorize each request make sure that the base URL is https://app.resemble.ai. You must attached your API key in the Token header as shown below.

# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
  -H "Token token=YOURAPIKEY"

Make sure to replace YOURAPIKEY with your API key.

Resemble uses API keys to allow access to the API. You can register a new Resemble API key at our developer portal.

Resemble expects for the API key to be included in all API requests to the server in a header that looks like the following:

Token token=YOURAPIKEY

Rate Limits

We currently enforce a rate limit of 10 requests every second to our API. If you go above this limit, please email team@resemble.ai.

Introduction

There are 2 resources that you can access using our API. Projects and Pods. In the Project scope, you can access a list of your current Projects, create a new Project, and see all recent pods within all of your projects. The Pod resource represents each audio file that is inside of a Project. You can perform actions such as listing all of the pods inside a project, retrieve one pod, or create a new pod.

Project

{
  name: <string>,
  description: <string>,
  public: <boolean>,
  collaboration: <boolean>
}

Get All Projects

curl "https://app.resemble.ai/api/v1/projects"
  -H "Authorization: YOURAPIKEY"

The above command returns JSON structured like this:

[
  {
      "id": 1,
      "name": "Resemble",
      "description": "Thoughts by Resemble",
  },
  {
      "id": 2,
      "name": "Dose of Health",
      "description": "Health-focused podcast from around the internets.",
  },
]

This endpoint retrieves all projects.

HTTP Request

GET https://app.resemble.ai/api/v1/projects

Get a Specific Project

curl "https://app.resemble.ai/api/v1/projects/<id>"
  -H "Authorization: YOURAPIKEY"

The above command returns JSON structured like this:

{
  "id": 1,
  "name": "Resemble",
  "description": "Thoughts by Resemble",
}

Returns a Project Resource.

URL Parameters

Parameter Description
ID The ID of the project to fetch

HTTP Request

GET https://app.resemble.ai/api/v1/projects/<ID>

Create a new Project

curl "https://app.resemble.ai/api/v1/projects"
  -H "Authorization: YOURAPIKEY"
  -H "Content-Type: application/json"
  --data '{
    data: <Project Resource>
  }'

The above command returns JSON structured like this if successful:

{
  "status": "OK"
}

Creates a new Project. This endpoint expects valid JSON with a data attribute that represents the Project resource.

HTTP Request

POST https://app.resemble.ai/api/v1/projects

Pod

Pod Resource. A Pod is a single Audio file that is generated from given text.

Parameters

Parameter Description
title The title given to this Pod. This can be whatever you wish to use to identify this resource later.
body The text that will be transformed to audio.
voice This will be the ID of the voice that should be used to create the audio.
author The Authors identity.
public Set to true if this Pod should be accessible by everyone
emotion If this voice was configured with emotions, you can pass a style in here. This can be from any of the following: style1, style2, style3, or a custom configuration if provided.
{
  title: <string>, // required
  body: <string>, // required
  voice: <string>, // required
  author: <string>,
  public: <boolean>,
  emotion: <string>,
}

Get All Pods

curl "https://app.resemble.ai/api/v1/projects/<project_id>/pods"
  -H "Authorization: YOURAPIKEY"

The above command returns JSON structured like this:

[
  {
    "id": 1,
    "title": "First Pod!",
    "body": "<speak><p>Resemble increases productivity through an easy to use API. <break time='1.5s'/> What do you think?</p></speak>",
    "published": "2018-09-03T03:33:33.000Z",
    "author": "Resemble Team",
    "finished": true,
    "link": "https://app.resemble.ai/rails/active_storage/blobs/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBYQT09IiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--61a46da3edde02743c8eb18631498c54268e9191/WTIDZGUW.mp3",
    "voice": "Noah",
    "project_id": 1
  }
]

This endpoint retrieves all pods within the given project.

HTTP Request

GET https://app.resemble.ai/api/v1/projects/<project_id>/pods

URL Parameters

Parameter Description
PROJECT_ID The PROJECT_ID of the project to fetch

Get a Specific Pod

curl "https://app.resemble.ai/api/v1/projects/<project_id>/pods/<id>"
  -H "Authorization: YOURAPIKEY"

The above command returns JSON structured like this:

{
  "id": 1,
  "title": "First Pod!",
  "body": "<speak><p>Resemble increases productivity through an easy to use API. <break time='1.5s'/> What do you think?</p></speak>",
  "published": "2018-09-03T03:33:33.000Z",
  "author": "Resemble Team",
  "finished": true,
  "link": "https://app.resemble.ai/rails/active_storage/blobs/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBYQT09IiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--61a46da3edde02743c8eb18631498c54268e9191/WTIDZGUW.mp3",
  "voice": "Noah",
  "project_id": 1
}

Returns a Pod Resource.

URL Parameters

Parameter Description
PROJECT_ID The PROJECT_ID of the project to fetch
ID The ID of the Pod to fetch

HTTP Request

GET https://app.resemble.ai/api/v1/projects/<PROJECT_ID>/pods/<ID>

Create a new Pod (Async)

curl "https://app.resemble.ai/api/v1/projects/<project_id>/pods"
  -H "Authorization: YOURAPIKEY"
  -H "Content-Type: application/json"
  --data '{
    callback_uri: <your callback uri>,
    data: <Pod Resource>
  }'

The above command returns JSON structured like this if successful:

{
  "status": "OK",
  "id": <pod_id>,
  "project_id": <project_id>
}

Creates a new Pod asynchronously. This endpoint expects valid JSON with a data attribute that represents the Pod resource. We also support callback urls, where you can define a service that will recieve a POST request when the pod has been completed.

The callback request will look like this:

{
  "id": <id>,
  "url": <url to audio>
}

HTTP Request

POST https://app.resemble.ai/api/v1/projects/<PROJECT_ID>/pods

URL Parameters

Parameter Description
PROJECT_ID The PROJECT_ID of the project to fetch

Create a new Pod (Synchronous)

curl "https://app.resemble.ai/api/v1/projects/<project_id>/pods/sync"
  -H "Authorization: YOURAPIKEY"
  -H "Content-Type: application/json"
  --data '{
    data: <Pod Resource>
  }'

Creates a new pod synchronously. Given a pod resource that looks like the following, it will return a URL to the generated audio.

// Example of a Pod Resource
{
  "title": "title to your pod",
  "body": "Some text that will be transformed into audio.",
  "voice": "<VOICE_ID>",
  "emotion": "<EMOTION_ID>"
}

The response will be a URL to the audio file.

https://app.resemble.ai/rails/active_storage/blobs/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBYQT09IiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--61a46da3edde02743c8eb18631498c54268e9191/WTIDZGUW.wav

HTTP Request

POST https://app.resemble.ai/api/v1/projects/<PROJECT_ID>/pods/sync

URL Parameters

Parameter Description
PROJECT_ID The PROJECT_ID of the project to fetch

Errors

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The endpointt requested is hidden for administrators only.
404 Not Found -- The specified endpointt could not be found.
405 Method Not Allowed -- You tried to access endpoint with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
410 Gone -- The resource requested has been removed from our servers.
418 I'm a teapot.
429 Too Many Requests -- You're requesting too fast! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.