Create a clip

This endpoint creates a clip in a project.

HTTP Request

POST https://app.resemble.ai/api/v2/projects/<project_uuid>/clips

URL Parameters	Type	Description
project_uuid	string	UUID of the project to which the clip should belong

JSON Body	Type	Description
title	(optional) string	Title for this clip
body	string	Content to be synthesized
voice_uuid	string	UUID of the voice to use for synthesizing
is_public	boolean	Whether this clip should be accessible publically
is_archived	boolean	Whether this clip should be archived
callback_uri	(optional, see description) string	The URL to POST the final clip to -- this paramter is required for most users, but those who have been granted synchronous access don't need to pass this in (contact us for more details)
precision	(optional) one of the following values: PCM_32 or PCM_16	The audio bit depth of generated audio
sample_rate	(optional) one of the following values: 8000, 16000, 22050 or 44100	The sample rate (Hz) of the generated audio
output_format	(optional) one of the following values: wav or mp3	The format of the generated audio
include_timestamps	(optional) boolean	Whether to include timestamps for the generated content -- see the documentation on timestamps for more information
raw	(optional) boolean	Whether to return raw audio data in the response
suggestions	(optional) boolean	Whether to apply substitutions and phonemes configured through the dashboard

HTTP Response

There are two types of responses you can expect based whether the callback_uri parameter was provided or not. If the callback_uri parameter is provided, it is considered an asynchronous request and the client can expect to receive a POST request to the callback_uri endpoint with the asynchronous response described below. Otherwise, it is considered a synchronous request and the audio will be returned to the caller, as described in the synchronous response section.

Asynchronous Response

1. HTTP response returned to the requester:

{
  "success": true,
  "item": {
    "uuid": <string>,
    "title": <string>,
    "body": <string>,
    "voice_uuid": <string>,
    "is_public": <boolean>,
    "is_archived": <boolean>,
    "created_at": <UTC Date>,
    "updated_at": <UTC Date>,
  }
}

2. Sends a POST request to the callback_uri with the following body:

The callback request will send a POST request to the callback URI provided. It will include a body of JSON:

{
  "id": <string>,
  "project_id": <string>,
  "url": <string: url to audio which expires after 1 hour>,
  "audio_timestamps": {
    "graph_chars": <string[]>,
    "graph_times": <float[[]]>,
    "phon_chars": <string[]>,
    "phon_times": <float[[]]>
  },
  "issues": <string[]>
}

Note:

• audio_timestamps is only sent if the include_timestamps parameter was true in the original request

Synchronous Response

{
  "success": true,
  "item": {
    "uuid": <string>,
    "title": <string>,
    "body": <string>,
    "voice_uuid": <string>,
    "is_public": <boolean>,
    "is_archived": <boolean>,
    "timestamps": {
        "graph_chars": <string[]>,
        "graph_times": <float[[]]>,
        "phon_chars": <string[]>,
        "phon_times": <float[[]]>
    },
    "audio_src": <string>,
    "raw_audio": <any>,
    "created_at": <UTC Date>,
    "updated_at": <UTC Date>,
  }
}

Note:

• raw_audio is only returned if the raw parameter is true
• timestamps is only returned if the include_timestamps parameter is true

Examples

Asynchronous Synthesis

NodeJS

1 2 3 4 5 6 7 8 const Resemble = require('@resemble/node') const resemble = new Resemble('v2', 'YOUR_API_TOKEN') await resemble.clips.createAsync(projectUuid, { body: 'This audio was synthesized ', voice_uuid: 'my_voice_uuid', callback_uri: 'https://...' })

tip

webhook.site is a great development tool for testing callbacks.

Synchronous Synthesis

NodeJS

1 2 3 4 5 6 7 const Resemble = require('@resemble/node') const resemble = new Resemble('v2', 'YOUR_API_TOKEN') const response = await resemble.clips.createSync(projectUuid, { body: 'This audio was synthesized', voice_uuid: 'my_voice_uuid' })

Try it out

API Key:

Project UUID:

JSON Body:

{ "title": "My clip", "body": "This audio was synthesized", "voice_uuid": "<voice_uuid>", "is_public": false, "is_archived": false, "callback_uri": "<your_callback_uri>" }