Marketplace API

Endpoints Reference

API Key Authentication

POST /api/api-key

Generate a new API key.

Request

Request Body
1{
2    "expires_at": "2008-09-15T15:53:00+05:00"
3}

Response

Response Body
1{
2    "api_key": "your-api-key"
3}

DELETE /api/api-key

Delete the API key associated with your account.

Session Authentication

POST /api/login

Log in to an account and start a new session.

Request

Request Body
1{
2  "email": "user@example.com",
3  "password": "string"
4}

Response

Response Body
1{
2  "user": {...},
3  "csrf_token": "string"
4}

POST /api/logout

End your session.

Response

Response Body
1{
2  "detail": "OK"
3}

Calibration

POST /api/calibration

Create a new calibration.

Request

Headers:

HeaderValue
Content-Typemultipart/form-data

Form data fields:

NameDescription
nameUnique name for the calibration.
dataThe audio binary data.

Currently the supported audio formats are wav, ogg, mp3 or flac.

Response

Response Body
1{
2  "id": "string",
3  "name": "string",
4  "user_id": "string",
5  "f0": 0,
6  "algorithm": "string",
7  "bucket": "string",
8  "key": "string",
9  "state": "processing",
10  "error": "string",
11  "created_at": "2022-06-27T14:21:43.569Z",
12  "calibrated_at": "2022-06-27T14:21:43.569Z",
13  "enabled": true
14}

PUT /api/calibration/{calibration_id}/enable

Set a calibration as the default enabled calibration.

Response

Response Body
1{
2  ...
3  "enabled": true
4}

POST /api/calibration/auto

Set auto as the default calibration.

Response

Response Body
1{
2  User Profile
3}

GET /api/calibration/{calibration_id}

Get a calibration by its ID.

Response

Response Body
1{
2  "id": "string",
3  "name": "string",
4  "user_id": "string",
5  "f0": 0,
6  "algorithm": "string",
7  "bucket": "string",
8  "key": "string",
9  "state": "processing",
10  "error": "string",
11  "created_at": "2022-06-27T14:21:43.569Z",
12  "calibrated_at": "2022-06-27T14:21:43.569Z",
13  "enabled": true
14}

GET /api/calibration

Get a list of the calibrations associated with your account.

Response

A JSON list of calibrations.

DELETE /api/calibration/{calibration_id}

Delete a calibration.

Response

A response body containing the deleted calibration.

Credits

GET /api/credits

Get the credits available to your account.

Response

Response Body
1{
2  "credits": 0,
3  "initial_credits": 0
4}

Projects

GET /api/projects

Get a list of your projects.

Request

Optional query parameters:

ParameterDescription
limitThe maximum number of projects to list.
offsetThe number of projects to offset the list by.
sortSort by name, created_at or last_recording_at.
directionOrder projects by asc or desc.
ownerList projects for a specific owner ID.

Response

Response Body
1{
2  "list": [
3    {
4      "name": "string",
5      "slug": "string",
6      "owner": "00000000-0000-0000-0000-000000000001",
7      "url": "string",
8      "models": {},
9      "id": "00000000-0000-0000-0000-000000000001",
10      "active": true,
11      "created_at": "2023-11-07T20:08:17.885Z",
12      "last_recording_at": "2023-11-07T20:08:17.885Z"
13    }
14  ],
15  "pagination": {
16    "count": 0,
17    "limit": 0,
18    "offset": 0
19  }
20}

POST /api/projects

Create a new project.

Request

Request Body
1{
2  "name": "string",
3  "owner": "00000000-0000-0000-0000-000000000001",
4  "models": {}
5}
  • name - The name of the project.
  • owner - Either a user or a group ID.
  • models - No longer used.

Response

Response Body
1{
2  "name": "string",
3  "slug": "string",
4  "owner": "00000000-0000-0000-0000-000000000001",
5  "url": "string",
6  "models": {},
7  "id": "00000000-0000-0000-0000-000000000001",
8  "active": true,
9  "created_at": "2022-06-27T14:21:43.569Z",
10  "last_recording_at": "2022-06-27T14:21:43.569Z"
11}

PATCH /api/projects/{project_id}

Change the name of a project.

Request

Request Body
1{
2  "name": "string"
3}

Response

The updated project.

DELETE /api/projects/{project_id}

Delete a project.

Response

Response Body
1{
2  "id": "00000000-0000-0000-0000-000000000001"
3}

GET /api/projects/by-url

Get a project by its URL.

Request

Query parameters:

ParameterDescription
project_urlThe URL of the project you want to fetch.

Response

A JSON object containing the project.

GET /api/projects/{project_id}/export

Export a project.

Request

Optional query parameters:

ParameterDescription
starred_onlyWhen true only starred recordings are included in the exported zip.

Response

The response will have a Content-Type of application/zip and the Content-Disposition header will be an attachment with the filename directive set to the name of the exported .zip file.

The response body contains the .zip file.

Folders

GET /api/folders

Get a list of the folders in a project.

Request

Query parameters:

ParameterDescription
project_idThe URL of the project you want to fetch. Required.
limitLimit the number of folders in the response. Defaults to 50.
offsetOffset the location where the list starts. Defaults to 0.
directionThe sort direction. asc or desc.

Response

Response Body
1{
2  "list": [
3    {
4      "name": "string",
5      "project_id": "00000000-0000-0000-0000-000000000001",
6      "parent_id": "00000000-0000-0000-0000-000000000001",
7      "id": "00000000-0000-0000-0000-000000000001",
8      "active": true,
9      "created_at": "2023-10-08T15:51:35.209Z"
10    }
11  ],
12  "pagination": {
13    "count": 0,
14    "limit": 0,
15    "offset": 0
16  }
17}

POST /api/folders

Create a folder.

Request

Request Body
1{
2  "name": "string",
3  "project_id": "00000000-0000-0000-0000-000000000001"
4}

Response

Response Body
1{
2  "name": "string",
3  "project_id": "00000000-0000-0000-0000-000000000001",
4  "parent_id": "00000000-0000-0000-0000-000000000001",
5  "id": "00000000-0000-0000-0000-000000000001",
6  "active": true,
7  "created_at": "2023-10-08T16:00:49.476Z"
8}

PATCH /api/folders/{folder_id}

Rename a folder.

Request

Request Body
1{
2  "name": "string",
3}
  • name - the new name of the folder

Response

A JSON object containing the renamed folder.

DELETE /api/folders/{folder_id}

Delete a folder.

Response

Response Body
1[
2    {"id": "00000000-0000-0000-0000-000000000001"}
3]

GET /api/folders/{folder_id}

Get a folder by its ID.

Response

Response Body
1{
2  "name": "string",
3  "project_id": "00000000-0000-0000-0000-000000000001",
4  "parent_id": "00000000-0000-0000-0000-000000000001",
5  "id": "00000000-0000-0000-0000-000000000001",
6  "active": true,
7  "created_at": "2023-10-08T16:08:34.131Z"
8}

Recordings

GET /api/recordings

Get a list of recordings for a specified folder or project.

Request

Query parameters:

ParameterDescription
project_idID of the project to get a list of recordings from.
folder_idID of the folder to get a list of recordings from.
limitThe maximum number of recordings to list.
offsetThe number of recordings to offset the list by.
directionOrder recordings by asc or desc.

Response

Response Body
1{
2  "list": [
3    {
4      "id": "00000000-0000-0000-0000-000000000001",
5      "project_id": "00000000-0000-0000-0000-000000000001",
6      "parent_folder_id": "00000000-0000-0000-0000-000000000001",
7      "type": "original",
8      "url": "string",
9      "waveform_url": "string",
10      "file_name": "string",
11      "label": "string",
12      "state": "done",
13      "original_id": "00000000-0000-0000-0000-000000000001",
14      "model_id": "00000000-0000-0000-0000-000000000001",
15      "model_name": "string",
16      "calibration_id": "00000000-0000-0000-0000-000000000001",
17      "calibration_value": 0,
18      "calibration_name": "string",
19      "microphone": "string",
20      "size": 0,
21      "duration": 0,
22      "starred": false,
23      "tts": true,
24      "tts_voice": "string",
25      "tts_voice_id": "string",
26      "text": "string",
27      "params": {},
28      "error": "string",
29      "active": true,
30      "created_at": "2023-10-08T16:12:55.753Z",
31      "converted_at": "2023-10-08T16:12:55.753Z",
32      "listen_count": 0,
33      "process_stage": "string",
34      "note": {
35        "id": "string",
36        "text": "string",
37        "active": true
38      }
39    }
40  ],
41  "pagination": {
42    "count": 0,
43    "limit": 0,
44    "offset": 0
45  }
46}

GET /api/recordings/originals

Get a list of the original recordings in a folder.

Request

Query parameters:

ParameterDescription
folder_idID of the folder to get a list of recordings from.
limitThe maximum number of recordings to list.
offsetThe number of recordings to offset the list by.
directionOrder recordings by asc or desc.

Response

Same as for the GET /api/recordings endpoint.

GET /api/recordings/conversions

Get a list of the conversions for an original recording.

Request

Query parameters:

ParameterDescription
original_idID of the original to get a list of conversions from.
limitThe maximum number of recordings to list.
offsetThe number of recordings to offset the list by.
directionOrder recordings by asc or desc.

Response

Same as for the GET /api/recordings endpoint.

POST /api/recordings

Create an original recording.

Request

Headers:

HeaderValue
Content-Typemultipart/form-data

Form data fields:

NameDescription
dataThe audio binary data.
parent_folder_idThe parent folder that the recording should belong to.
microphoneName of the microphone used to capture the audio. If uploading a file set this field to file.
labelLabel for the recording.

Currently the supported audio formats are wav, ogg, mp3 or flac.

Response

Response Body
1{
2  "id": "00000000-0000-0000-0000-000000000001",
3  "project_id": "00000000-0000-0000-0000-000000000001",
4  "parent_folder_id": "00000000-0000-0000-0000-000000000001",
5  "type": "original",
6  "url": "string",
7  "waveform_url": "string",
8  "file_name": "string",
9  "label": "string",
10  "state": "done",
11  "original_id": "00000000-0000-0000-0000-000000000001",
12  "model_id": "00000000-0000-0000-0000-000000000001",
13  "model_name": "string",
14  "calibration_id": "00000000-0000-0000-0000-000000000001",
15  "calibration_value": 0,
16  "calibration_name": "string",
17  "microphone": "string",
18  "size": 0,
19  "duration": 0,
20  "starred": false,
21  "tts": true,
22  "tts_voice": "string",
23  "tts_voice_id": "string",
24  "text": "string",
25  "params": {},
26  "error": "string",
27  "active": true,
28  "created_at": "2023-10-08T16:26:28.630Z",
29  "converted_at": "2023-10-08T16:26:28.630Z",
30  "listen_count": 0,
31  "process_stage": "string",
32  "note": {
33    "id": "string",
34    "text": "string",
35    "active": true
36  }
37}

POST /api/recordings/tts

This endpoint is deprecated.

Create an original text-to-speech recording.

Request

Request Body
1{
2  "project_id": "00000000-0000-0000-0000-000000000001",
3  "parent_folder_id": "00000000-0000-0000-0000-000000000001",
4  "label": "string",
5  "voice_id": "00000000-0000-0000-0000-000000000001",
6  "text": "string"
7}
  • project_id is the ID of the project the recording will belong to.
  • parent_folder_id and label are the same as for audio recordings.
  • voice_id is the ID of the TTS voice to use. You can obtain a list of the TTS voices available to you from the GET /api/tts-voices endpoint.
  • text is the text to be converted to speech.

Response

Same as for POST /api/recordings.

PATCH /api/recordings/{recording_id}

Update a recording.

Request

Request Body
1{
2  "label": "string",
3  "starred": true
4}

Response

A JSON object containing the updated recording.

PUT /api/recordings/{recording_id}

Same as PATCH /api/recordings/{recording_id} but all request body fields are required.

DELETE /api/recordings/{recording_id}

Delete a recording.

Response

Response Body
1[
2  {"id": "00000000-0000-0000-0000-000000000001"}
3]

GET /api/recordings/export

Export all conversions for an original recording.

Request

Query parameters:

ParameterDescription
original_idThe ID of the original recording to export.
starred_onlyWhen true only starred recordings are included in the exported zip.

Response

The response will have a Content-Type of application/zip and the Content-Disposition header will be an attachment with the filename directive set to the name of the exported .zip file.

The response body contains the .zip file.

GET /api/recordings/{recording_id}

Get a recording by its ID.

Response

A JSON object containing the recording.

POST /api/v2/recordings/tts

Create an original text-to-speech recording.

Request

Request Body
1{
2  "parent_folder_id": "00000000-0000-0000-0000-000000000001",
3  "text": "string"
4  "text_language": "ISO 639 language code", (Optional)
5  "label": "string" (Optional)
6}
  • parent_folder_id is the ID of the folder the recording will belong to.
  • text is the text to be converted to speech.
  • text_language (Optional) is the language of the text. If not specified the language will be detected automatically.
  • label (Optional) is a label for the recording.

Response

Same as for POST /api/recordings.

TTS

GET /api/tts-voices

Get a list of the available TTS voices.

Response

Response Body
1[
2    {
3        "id": "00000000-0000-0000-0000-000000000001",
4        "visibility": "public",
5        "name": "string",
6        "f0": 0,
7        "is_default": true
8    }
9]

Notes

POST /api/notes

Request

Request Body
1{
2  "recording_id": "string",
3  "text": "string"
4}

Response

Response Body
1{
2  "recording_id": "string",
3  "text": "string",
4  "id": "string",
5  "active": true
6}

PUT /api/notes

Request

Request Body
1{
2  "recording_id": "string",
3  "text": "string"
4}

Response

A JSON object containing the updated note.

DELETE /api/notes

Delete a note.

Request

Request Body
1{
2  "recording_id": "string",
3}

Response

A JSON object containing the deleted note.

Statistics

GET /api/stats

Get the statistics for your account.

Response

Response Body
1{
2  "time_converted": {
3    "total": 0,
4    "current_month": 0,
5    "previous_monthes": [
6      {
7        "month": "2023-11-08",
8        "duration": 0
9      }
10    ]
11  },
12  "conversions": {
13    "total": 0,
14    "completed": 0,
15    "in_progress": 0,
16    "failed": 0
17  },
18  "models": [
19    {
20      "id": "string",
21      "name": "string",
22      "conversions_count": 0,
23      "converted_time": 0
24    }
25  ]
26}

GET /api/stats/projects

Get statistics for a list of projects.

Request

Request Body
1{
2  "project_ids": ["00000000-0000-0000-0000-000000000001"]
3}

Response

Response Body
1[
2  {
3    "project_id": "00000000-0000-0000-0000-000000000001",
4    "time_converted": {
5      "total": 0,
6      "current_month": 0
7    },
8    "conversions": {
9      "total": 0,
10      "completed": 0,
11      "in_progress": 0,
12      "failed": 0
13    }
14  }
15]

GET /api/stats/folders

Get statistics for a list of folders.

Request

Request Body
1{
2  "folder_ids": ["00000000-0000-0000-0000-000000000001"]
3}

Response

Response Body
1[
2  {
3    "folder_id": "00000000-0000-0000-0000-000000000001",
4    "stats": {
5      "total": 0,
6      "completed": 0,
7      "in_progress": 0,
8      "failed": 0
9    }
10  }
11]

Orders

POST /api/v2/orders

Request

Request Body
1{
2  "original_id": "00000000-0000-0000-0000-000000000001",
3  "conversions": [
4    {
5      "voice_id": "00000000-0000-0000-0000-000000000001",
6      "narration_style_id": "00000000-0000-0000-0000-000000000001" (Required for TTS),
7      "accent_id": "00000000-0000-0000-0000-000000000001" (Optional),
8      "semitones_correction": 0 (Optional),
9      "label": "string" (Optional)
10    }
11  ],
12  "calibration_id": "00000000-0000-0000-0000-000000000001" (Optional),
13  "use_calibration": false (Optional)
14}
  • original_id - is the ID of the original recording to create a conversion from.
  • conversions contains a list of the voices and accents you wish to convert your original voice recording to. Each list item has three properties:
    • voice_id - The ID of the voice. A list of the available voices can be obtained with the GET /api/v2/voices endpoint.
    • narration_style_id (Required for TTS) - The ID of the narration_style to use. Each voice has number of narration_styles that you can choose from. Narration styles used in text-to-speech conversions.
    • accent_id (Optional) - The ID of the accent to use. Each voice has number of accents that you can choose from. Accents used in speech-to-speech conversions.
    • semitones_correction (Optional) - The number of semitones to shift the converted output to. By default most voices will shift your voice by an number of semitones. The resultant pitch will be your voice's pitch + default voice shift + semitones_correction. Used only in speech to speech conversion.
    • label (Optional) - A label to identify the conversion.
  • use_calibration (Optional) - if you wish to use a specific calibration set this to true and specify the calibration_id otherwise, if it’s false, it will default to the currently enabled calibration on your account. Used only in speech to speech conversion.
  • calibration_id (Optional) - contains the ID of the calibration to use. Used only in speech to speech conversion.

POST /api/v2/orders/retry/{recording_id}

Retry a conversion order for a specific original.

Voices

GET /api/v2/voices

Get a list of the voices available to you.

Request

Optional query parameters:

NameDescription
limitLimit the number of voices in the response. Defaults to 25.
offsetOffset the location where the list starts. Defaults to 0
sortSort by parameter. name, pitch, rating or created_at
directionThe sort direction. asc or desc
visibilityFilter by visibility. public, paid, private or kids
speciesFilter by species. human, animal or other
genderFilter by gender. male or female
age_groupFilter by age group. child, young, adult or senior
pitch_groupFilter by pitch group. low, mid or high
nationalityFilter by nationality.

Response

Response Body
1{
2"list": [
3    {
4    "id": "00000000-0000-0000-0000-000000000001",
5    "owner_id": "00000000-0000-0000-0000-000000000001",
6    "name": "string",
7    "slug": "string",
8    "visibility": "public",
9    "species": "human",
10    "artist": "string",
11    "verified_artist": true,
12    "gender": "male",
13    "pitch": 0,
14    "age_group": "child",
15    "pitch_group": "low",
16    "nationality": "string",
17    "image_url": "string",
18    "thumbnail_url": "string",
19    "description": "string",
20    "rating": 0,
21    "active": true,
22    "created_at": "2024-02-28T11:21:32.401Z",
23    "favorite": false,
24    "available": false,
25    "accents": [
26        {
27        "id": "00000000-0000-0000-0000-000000000001",
28        "is_default": true,
29        "native": true,
30        "info": {
31            "name": "string",
32            "short_name": "string",
33            "locale": "string"
34        },
35        "tiers": [
36            {
37            "name": "string"
38            }
39        ],
40        "available": false,
41        "settings": {
42            "favorite": false,
43            "semitones_correction": 0
44        }
45        }
46    ],
47    "narration_styles": [
48        {
49        "id": "00000000-0000-0000-0000-000000000001",
50        "is_default": true,
51        "info": {
52            "name": "string"
53        },
54        "settings": {
55            "favorite": false
56        }
57        }
58    ],
59    "tiers": [
60        {
61        "name": "string"
62        }
63    ]
64    }
65],
66"pagination": {
67    "count": 0,
68    "limit": 0,
69    "offset": 0
70}
71}

GET /api/v2/voices/search

Search for a voice by its name.

Request

Optional query parameters:

ParameterDescription
nameThe name of the voice.
limitLimit the number of search results.

Response

Response Body
1[
2    {
3    "id": "00000000-0000-0000-0000-000000000001",
4    "owner_id": "00000000-0000-0000-0000-000000000001",
5    "name": "string",
6    "slug": "string",
7    "visibility": "public",
8    "species": "human",
9    "artist": "string",
10    "verified_artist": true,
11    "gender": "male",
12    "pitch": 0,
13    "age_group": "child",
14    "pitch_group": "low",
15    "nationality": "string",
16    "image_url": "string",
17    "thumbnail_url": "string",
18    "description": "string",
19    "rating": 0,
20    "active": true,
21    "created_at": "2024-02-28T11:21:32.401Z",
22    "favorite": false,
23    "available": false,
24    "accents": [
25        {
26        "id": "00000000-0000-0000-0000-000000000001",
27        "is_default": true,
28        "native": true,
29        "info": {
30            "name": "string",
31            "short_name": "string",
32            "locale": "string"
33        },
34        "tiers": [
35            {
36            "name": "string"
37            }
38        ],
39        "available": false,
40        "settings": {
41            "favorite": false,
42            "semitones_correction": 0
43        }
44        }
45    ],
46    "narration_styles": [
47        {
48        "id": "00000000-0000-0000-0000-000000000001",
49        "is_default": true,
50        "info": {
51            "name": "string"
52        },
53        "settings": {
54            "favorite": false
55        }
56        }
57    ],
58    "tiers": [
59        {
60        "name": "string"
61        }
62    ]
63    }
64]

POST /api/v2/voices/favorite/{voice_id}

Mark a voice as a favorite.

Request

Request Body
1{
2  "favorite": true
3}

Response

A JSON object containing the updated voice.

POST /api/v2/voices/settings

Set the settings for a voice.

Request

Body parameters:

NameDescription
voice_idId of voice to update. Required
`narration_style_idId of narration_style to mark as favorite. Optional
accent_idId of accent to mark as favorite. Optional
semitones_correctionIf accent_id is specified - save semitone_correction value. Optional
Request Body
1{
2    "voice_id": "00000000-0000-0000-0000-000000000001",
3    "narration_style_id": "00000000-0000-0000-0000-000000000001"
4    "accent_id": "00000000-0000-0000-0000-000000000001",
5    "semitones_correction": 0,
6}

Response

A JSON object containing the updated voice.

Accents

GET /api/v2/accents/samples

Samples available for an accent

Request

Query parameters:

NameDescription
accent_idId of accent. Required

Response

Response Body
1{
2  "samples": { ... }
3}