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 "Authorization: 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 Clips. In the Project scope, you can access a list of your current Projects, create a new Project, and see all recent clips within all of your projects. The Clip resource represents each audio file that is inside of a Project. You can perform actions such as listing all of the clips inside a project, retrieve one clip, or create a new clip.

Project

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

Get All Projects

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

The above command returns JSON structured like this:

[
  {
      "id": 1,
      "uuid": "1ab233",
      "name": "Resemble",
      "description": "Thoughts by Resemble",
  },
  {
      "id": 2,
      "uuid": "1ab234",
      "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/<uuid>"
  -H "Authorization: Token token=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
UUID The UUID 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: Token token=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

Clip

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

Parameters

Parameter Description
title The title given to this Clip. 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 Clip 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 Clips

curl "https://app.resemble.ai/api/v1/projects/<project_id>/clips"
  -H "Authorization: Token token=YOURAPIKEY"

The above command returns JSON structured like this:

[
  {
    "id": 1,
    "title": "First Clip!",
    "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 clips within the given project.

HTTP Request

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

URL Parameters

Parameter Description
PROJECT_UUID The PROJECT_UUID of the project to fetch

Get a Specific Clip

curl "https://app.resemble.ai/api/v1/projects/<project_uuid>/clips/<uuid>"
  -H "Authorization: Token token=YOURAPIKEY"

The above command returns JSON structured like this:

{
  "id": 1,
  "title": "First Clip!",
  "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 Clip Resource.

URL Parameters

Parameter Description
PROJECT_UUID The PROJECT_UUID of the project to fetch
UUID The UUID of the Clip to fetch

HTTP Request

GET https://app.resemble.ai/api/v1/projects/<PROJECT_UUID>/clips/<UUID>

Create a new Clip (Async)

curl "https://app.resemble.ai/api/v1/projects/<project_uuid>/clips"
  -H "Authorization: Token token=YOURAPIKEY"
  -H "Content-Type: application/json"
  --data '{
    "callback_uri": <your callback uri>,
    "data": <Clip Resource>
  }'

The above command returns JSON structured like this if successful:

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

Creates a new Clip asynchronously. This endpoint expects valid JSON with a data attribute that represents the Clip resource. We also support callback urls, where you can define a service that will recieve a POST request when the clip 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_UUID>/clips/sync

URL Parameters

Parameter Description
PROJECT_UUID The PROJECT_UUID of the project to fetch

Create a new Clip (Synchronous)

curl "https://app.resemble.ai/api/v1/projects/<project_uuid>/clips/sync"
  -H "Authorization: Token token=YOURAPIKEY"
  -H "Content-Type: application/json"
  --data '{
    "data": <Clip Resource>,
    "quality": "x-high|high (default)|medium|low",
    "raw": false (default)|true
  }'

Creates a new clip synchronously. Given a clip resource that looks like the following, it will return a URL to the generated audio. If raw is set to true, it will return the raw WAV output.

The quality parameter will synthesize the speech in varying resolutions. A lower quality param will result in lower latency. By default, the parameter is set to high, but a developer can choose from x-high, medium, or low.

// Example of a Clip Resource
{
  "title": "title to your clip",
  "body": "Some text or SSML that will be transformed into audio.",
  "voice": "<VOICE_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_UUID>/clips/sync

URL Parameters

Parameter Description
PROJECT_UUID The PROJECT_UUID of the project to fetch

Voice

{
    "name": <VoiceName>,
    "language": "en-US",
    "id": <ID>,
    "uuid": <UUID>
}

Get All Voices

curl "https://app.resemble.ai/api/v1/voices"
  -H "Authorization: Token token=YOURAPIKEY"

The above command returns JSON structured like this:

[
    {
        "name": "Jessica",
        "language": "en-US",
        "id": 500001,
        "uuid": "123456"
    },
    {
        "name": "Saqib",
        "language": "en-US",
        "id": 500002,
        "uuid": "789012"
    },
]

This endpoint retrieves all voices.

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.