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. Max size of 3,000 characters excluding SSML tags.
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. If provided, the request is considered "asynchronous", otherwise it's considered "syncronous".
precision	(optional) one of the following values: PCM_32, PCM_24, PCM_16, or MULAW. Default is PCM_32 unless output_format is set to mp3 - then the default is PCM_16	The audio bit depth of generated audio
sample_rate	(optional) one of the following values: 8000, 16000, 22050 or 44100. Default is 22050	The sample rate (Hz) of the generated audio
output_format	(optional) one of the following values: wav or mp3. Default is wav.	The format of the generated audio
include_timestamps	(optional) boolean. Default is false.	Whether to include timestamps for the generated content -- see the documentation on timestamps for more information
raw	(optional) boolean. Default is false.	Whether to return raw audio data in the response
suggestions	(optional) boolean. Default is false.	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

info

Ensure that that your callback endpoint returns a 200 HTTP response code. If a non 200 response code is returned, we'll retry the callback 2 times with an exponentially increasing delay between retries. If a 404 response code is returned, the callback is not retried.

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 9 import { Resemble } from '@resemble/node' Resemble.setApiKey('YOUR_API_TOKEN') await Resemble.v2.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 8 import { Resemble } from '@resemble/node' Resemble.setApiKey('YOUR_API_TOKEN') const response = await Resemble.v2.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>" }