Skip to main content
Version: 2.0.0

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 ParametersTypeDescription
project_uuidstringUUID of the project to which the clip should belong
JSON BodyTypeDescription
title(optional) stringTitle for this clip
bodystringContent to be synthesized
voice_uuidstringUUID of the voice to use for synthesizing
is_publicbooleanWhether this clip should be accessible publically
is_archivedbooleanWhether this clip should be archived
callback_uri(optional, see description) stringThe 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, PCM_16, or ULAWThe audio bit depth of generated audio
sample_rate(optional) one of the following values: 8000, 16000, 22050 or 44100The sample rate (Hz) of the generated audio
output_format(optional) one of the following values: wav or mp3The format of the generated audio
include_timestamps(optional) booleanWhether to include timestamps for the generated content -- see the documentation on timestamps for more information
raw(optional) booleanWhether to return raw audio data in the response
suggestions(optional) booleanWhether 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 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: