Download OpenAPI specification:Download
Descript API uses a personal token to authenticate your request. You can get your personal token by contacting us. The personal token should be used as a bearer token in the authorization header.
curl -H "authorization: Bearer ${YOUR_PERSONAL_TOKEN}" https://descriptapi.com/v1/overdub/voices
In this part, we will generate our first audio with the Overdub API.
You will first need to find the id of the Voice with which to generate:
curl --request GET \
--url https://descriptapi.com/v1/overdub/voices \
--header 'authorization: Bearer ${YOUR_PERSONAL_TOKEN}'
Once you pick your voice-id, generate an async task:
curl --request POST \
--url https://descriptapi.com/v1/overdub/generate_async \
--header 'authorization: Bearer ${YOUR_PERSONAL_TOKEN}' \
--header 'content-type: application/json' \
--data '{
"text": "Hey everyone, this is a generated audio",
"voice_id": "${VOICE_ID}"
}'
### Result {"id": "fc0a16f9-9bac-46f5-8917-ef9ea50531bb","state": "queued"}
Now fetch the result of the task (should be available after a few seconds):
curl --request GET \
--url https://descriptapi.com/v1/overdub/generate_async/fc0a16f9-9bac-46f5-8917-ef9ea50531bb \
--header 'authorization: Bearer ${YOUR_PERSONAL_TOKEN}'
### Result {"id": "fc0a16f9-9bac-46f5-8917-ef9ea50531bb","state": "done", "url":"https:url-to-audio.wav"}
It will create an Overdub generate async task. Use the get
endpoint to fetch the job result.
Usually, a task should take a few seconds. You can provide an optional callback_url as a parameter to this request. We will do a post to this url once the overdub is ready.
There are two types of Overdub: standalone and contextual.
By standalone Overdub, we mean the standard text-to-speech setup where you only provide the input text and voice-id (and, optionally, a voice-style-id that is associated with the voice). If no voice-style-id is provided, we use the default style associated with the Voice in the app as the style for standalone Overdub generation.
Contextual Overdub is for such use-cases where you need to replace a few words within a given audio segment. For this, you should provide the audio segments and the text string for the context (prefix and suffix). The audio for these contexts should be provided as a URL from where they can be downloaded. Both of these context items (prefix and suffix) are optional. If neither of the two are provided then it becomes a standalone Overdub, which will use the requested voice style. However, if one or both of them provided, they would be used for two purposes:
Currently, we have a limit of 500 overdubs per minute.
Overdub async request body.
text required | string <= 1000 characters The text you want to generate. |
voice_id required | string <uuid> The voice id. |
voice_style_id | string <uuid> The ID of the desired style associated with the voice. If not provided, the default voice style is used. This parameter is ignored if |
prefix_text | string The transcript of the prefix audio. |
prefix_audio_url | string <url> The prefix audio url. |
suffix_text | string The transcript of the suffix audio. |
suffix_audio_url | string <url> The suffix audio url. |
callback_url | string <url> when the overdub is ready, we do a post on that endpoint with a json object: {state, id}. Then user will have to get the result as usual |
{- "text": "Hey everyone, this is a generated audio.",
- "voice_id": "2235c634-e4db-4ad6-aa15-066fb69b1c8f",
- "voice_style_id": "b9a0ebf3-b259-4b98-975c-a847678f9faf",
- "prefix_text": "string",
- "prefix_audio_url": "string",
- "suffix_text": "string",
- "suffix_audio_url": "string",
- "callback_url": "string"
}
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "state": "queued",
}
It takes a few seconds for the Overdub audio to get generated. Once the state of the response is "done", your generate Overdub audio will be available at the "url" in the response.
The generated Overdub audio always has the sample-rate of 44100 kHz and has a single channel (mono).
If you provided any or both of the context (prefix and suffix) when posting an Overdub request, then those would be concatenated in the generated Overdub output. Note that the concatenation is a bit overlapping in both directions, i.e. we generate a little longer on both ends, and when concatenating with prefix/suffix, we use a Hann smoothing to add the generated audio into its context.
overdubId required | string ID of the Overdub to return. |
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "state": "queued",
}
[- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "styles": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string"
}
], - "is_public": true,
- "status": "active"
}
]
Edit in Descript API enables partners to give their users the ability to transfer audio or video content to Descript for editing.
Edit in Descript buttons work by generating one-time use, public Import URLs to the Descript import UI that users can be automatically sent to. On that page, they can make a few simple selections before kicking off a Partner cloud storage to Descript cloud storage transfer. This will redirect them to a Descript Project ready for editing.
Partners can initiate the request by securely sending an information schema backend-to-backend to the Descript API using a token, in exchange for the Import URL to redirect the user. Partners do not need to store this schema, as Descript will do so and use it to start fetching the files when the user confirms the action
Edit in Descript
, partner’s backend service makes POST request to:
https://descriptapi.com/v1/edit_in_descript/schema
with an authorization bearer token header and JSON schema bodySome guidelines for partners as you consider this integration:
Edit in Descript
option next to your download optionsEdit in Descript
CTA and ask
that you don’t edit the assets beyond what we provide. We are happy to work with you on getting you the right
assets for your placement.When users are directed to a Descript Import URL, they’ll be asked to either create an account or login in order to proceed.
Next, they will be presented with a few options about how they’d like to import the data, such as where the new Descript Project should be created.
They’ll then be redirected to the Project, where they can monitor the progress of the import and start editing.
Create an Import URL by sending a Project schema to Descript API from your service's backend.
Our import schemas are specified as a minimal JSON list of files which is detailed in full at the bottom of this section. At it’s smallest, the request body looks like:
{
"partner_drive_id": "162c61d1-6ced-4b25-a622-7dba922983ee",
"project_schema": {
"schema_version": "1.0.0",
"files": [{"uri": "https://descriptusercontent.com/jane.wav?signature=d182bca64bf94a1483d2fd16b579f955"}]
}
}
The file paths provided in the schema need to either be public or pre-signed URIs with enough time before expiration for failures and retries, we suggest URIs that won’t expire for 48 hours. We ask that the files have already been saved when the import link is generated to minimize cases where we’re waiting for eventually consistent storage of files that will never be written. We will, however, wait for eventual consistency of the storage layer and retry fetching files before eventually timing out.
Files must be hosted on preapproved hosts as our import process has an allow list which it checks URIs against.
Files will be requested with User-Agent: Descriptbot/1.0
(version may change) for tracking purposes.
Import links are no longer valid after a user imports their data once. Viewing an already used import link will not allow for importing again and will not provide access to a previously created Descript Project. Partners are able to generate a new import link at any time, regardless of if a previous import link has been used.
The API does not currently provide partners with a link to the Descript Project, though users will be redirected to it from Descript’s web interface the first time they import files, and can always find the Project in Descript.
Import links expire after 3 hours and attempting to use an import link after the pre-signed links in the schema file have expired will result in an error, so we recommend generating the import link after the user has clicked the Edit in Descript button.
We recommend sending the highest quality, uncompressed versions of files available to you. If you have multiple tracks, we recommend prioritizing sending us the full multi-track sequence over a combined file.
Edit in Descript schema POST body.
partner_drive_id required | uuid The drive id associated with the auth token. |
required | object The Project schema |
{- "partner_drive_id": "aa3b2d8d-e5ca-41c2-8801-683328293fb9",
- "project_schema": {
- "schema_version": "1.0.0",
- "source_id": "06b3f5bb-68a2-468a-a5d9-df155c1e3588",
- "files": [
- {
- "name": "Jane's studio recording",
- "start_offset": {
- "seconds": 10
}
}
]
}
}
Users of Descript currently have three options to export their edited content. They can export files in various formats, share a Descript link, or use our one-click cloud export to publish directly to a partner.
If Project data previously came from a partner via an Edit in Descript schema then any Descript Export pages
will include <meta/>
tags which contains the partner_drive_id
and source_id
provided when originally
importing into Descript. This allows partners to deduplicate data returning back to partner systems after
editing in Descript. Both partner and source properties are included on all public Descript Export pages.
<meta property="descript:partner" content="9121bf3a-60fe-4a31-ad59-ed32df610cc3" />
<meta property="descript:source" content="409148bd-81aa-4af6-a9c3-29b761506f3a" />