Skip to content

Endpoints Reference

API Key Authentication

POST /api/api-key

Generate a new API key.

Request

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

Response

Response Body
{
    "api_key": "your-api-key"
}

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
{
  "email": "user@example.com",
  "password": "string"
}

Response

Response Body
{
  "user": {...},
  "csrf_token": "string"
}

POST /api/logout

End your session.

Response

Response Body
{
  "detail": "OK"
}

Calibration

POST /api/calibration

Create a new calibration.

Request

Headers:

Header Value
Content-Type multipart/form-data

Form data fields:

Name Description
name Unique name for the calibration.
data The audio binary data.

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

Response

Response Body
{
  "id": "string",
  "name": "string",
  "user_id": "string",
  "f0": 0,
  "algorithm": "string",
  "bucket": "string",
  "key": "string",
  "state": "processing",
  "error": "string",
  "created_at": "2022-06-27T14:21:43.569Z",
  "calibrated_at": "2022-06-27T14:21:43.569Z",
  "enabled": true
}

PUT /api/calibration/{calibration_id}/enable

Set a calibration as the default enabled calibration.

Response

Response Body
{
  ...
  "enabled": true
}

POST /api/calibration/auto

Set auto as the default calibration.

Response

Response Body
{
  User Profile
}

GET /api/calibration/{calibration_id}

Get a calibration by its ID.

Response

Response Body
{
  "id": "string",
  "name": "string",
  "user_id": "string",
  "f0": 0,
  "algorithm": "string",
  "bucket": "string",
  "key": "string",
  "state": "processing",
  "error": "string",
  "created_at": "2022-06-27T14:21:43.569Z",
  "calibrated_at": "2022-06-27T14:21:43.569Z",
  "enabled": true
}

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
{
  "credits": 0,
  "initial_credits": 0
}

Projects

GET /api/projects

Get a list of your projects.

Request

Optional query parameters:

Parameter Description
limit The maximum number of projects to list.
offset The number of projects to offset the list by.
sort Sort by name, created_at or last_recording_at.
direction Order projects by asc or desc.
owner List projects for a specific owner ID.

Response

Response Body
{
  "list": [
    {
      "name": "string",
      "slug": "string",
      "owner": "00000000-0000-0000-0000-000000000001",
      "url": "string",
      "models": {},
      "id": "00000000-0000-0000-0000-000000000001",
      "active": true,
      "created_at": "2023-11-07T20:08:17.885Z",
      "last_recording_at": "2023-11-07T20:08:17.885Z"
    }
  ],
  "pagination": {
    "count": 0,
    "limit": 0,
    "offset": 0
  }
}

POST /api/projects

Create a new project.

Request

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

Response

Response Body
{
  "name": "string",
  "slug": "string",
  "owner": "00000000-0000-0000-0000-000000000001",
  "url": "string",
  "models": {},
  "id": "00000000-0000-0000-0000-000000000001",
  "active": true,
  "created_at": "2022-06-27T14:21:43.569Z",
  "last_recording_at": "2022-06-27T14:21:43.569Z"
}

PATCH /api/projects/{project_id}

Change the name of a project.

Request

Request Body
{
  "name": "string"
}

Response

The updated project.

DELETE /api/projects/{project_id}

Delete a project.

Response

Response Body
{
  "id": "00000000-0000-0000-0000-000000000001"
}

GET /api/projects/by-url

Get a project by its URL.

Request

Query parameters:

Parameter Description
project_url The 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:

Parameter Description
starred_only When 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:

Parameter Description
project_id The URL of the project you want to fetch. Required.
limit Limit the number of folders in the response. Defaults to 50.
offset Offset the location where the list starts. Defaults to 0.
direction The sort direction. asc or desc.

Response

Response Body
{
  "list": [
    {
      "name": "string",
      "project_id": "00000000-0000-0000-0000-000000000001",
      "parent_id": "00000000-0000-0000-0000-000000000001",
      "id": "00000000-0000-0000-0000-000000000001",
      "active": true,
      "created_at": "2023-10-08T15:51:35.209Z"
    }
  ],
  "pagination": {
    "count": 0,
    "limit": 0,
    "offset": 0
  }
}

POST /api/folders

Create a folder.

Request

Request Body
{
  "name": "string",
  "project_id": "00000000-0000-0000-0000-000000000001"
}

Response

Response Body
{
  "name": "string",
  "project_id": "00000000-0000-0000-0000-000000000001",
  "parent_id": "00000000-0000-0000-0000-000000000001",
  "id": "00000000-0000-0000-0000-000000000001",
  "active": true,
  "created_at": "2023-10-08T16:00:49.476Z"
}

PATCH /api/folders/{folder_id}

Rename a folder.

Request

Request Body
{
  "name": "string",
}
  • 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
[
    {"id": "00000000-0000-0000-0000-000000000001"}
]

GET /api/folders/{folder_id}

Get a folder by its ID.

Response

Response Body
{
  "name": "string",
  "project_id": "00000000-0000-0000-0000-000000000001",
  "parent_id": "00000000-0000-0000-0000-000000000001",
  "id": "00000000-0000-0000-0000-000000000001",
  "active": true,
  "created_at": "2023-10-08T16:08:34.131Z"
}

Recordings

GET /api/recordings

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

Request

Query parameters:

Parameter Description
project_id ID of the project to get a list of recordings from.
folder_id ID of the folder to get a list of recordings from.
limit The maximum number of recordings to list.
offset The number of recordings to offset the list by.
direction Order recordings by asc or desc.

Response

Response Body
{
  "list": [
    {
      "id": "00000000-0000-0000-0000-000000000001",
      "project_id": "00000000-0000-0000-0000-000000000001",
      "parent_folder_id": "00000000-0000-0000-0000-000000000001",
      "type": "original",
      "url": "string",
      "waveform_url": "string",
      "file_name": "string",
      "label": "string",
      "state": "done",
      "original_id": "00000000-0000-0000-0000-000000000001",
      "model_id": "00000000-0000-0000-0000-000000000001",
      "model_name": "string",
      "calibration_id": "00000000-0000-0000-0000-000000000001",
      "calibration_value": 0,
      "calibration_name": "string",
      "microphone": "string",
      "size": 0,
      "duration": 0,
      "starred": false,
      "tts": true,
      "tts_voice": "string",
      "tts_voice_id": "string",
      "text": "string",
      "params": {},
      "error": "string",
      "active": true,
      "created_at": "2023-10-08T16:12:55.753Z",
      "converted_at": "2023-10-08T16:12:55.753Z",
      "listen_count": 0,
      "process_stage": "string",
      "note": {
        "id": "string",
        "text": "string",
        "active": true
      }
    }
  ],
  "pagination": {
    "count": 0,
    "limit": 0,
    "offset": 0
  }
}

GET /api/recordings/originals

Get a list of the original recordings in a folder.

Request

Query parameters:

Parameter Description
folder_id ID of the folder to get a list of recordings from.
limit The maximum number of recordings to list.
offset The number of recordings to offset the list by.
direction Order 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:

Parameter Description
original_id ID of the original to get a list of conversions from.
limit The maximum number of recordings to list.
offset The number of recordings to offset the list by.
direction Order recordings by asc or desc.

Response

Same as for the GET /api/recordings endpoint.

POST /api/recordings

Create an original recording.

Request

Headers:

Header Value
Content-Type multipart/form-data

Form data fields:

Name Description
data The audio binary data.
parent_folder_id The parent folder that the recording should belong to.
microphone Name of the microphone used to capture the audio. If uploading a file set this field to file.
label Label for the recording.

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

Response

Response Body
{
  "id": "00000000-0000-0000-0000-000000000001",
  "project_id": "00000000-0000-0000-0000-000000000001",
  "parent_folder_id": "00000000-0000-0000-0000-000000000001",
  "type": "original",
  "url": "string",
  "waveform_url": "string",
  "file_name": "string",
  "label": "string",
  "state": "done",
  "original_id": "00000000-0000-0000-0000-000000000001",
  "model_id": "00000000-0000-0000-0000-000000000001",
  "model_name": "string",
  "calibration_id": "00000000-0000-0000-0000-000000000001",
  "calibration_value": 0,
  "calibration_name": "string",
  "microphone": "string",
  "size": 0,
  "duration": 0,
  "starred": false,
  "tts": true,
  "tts_voice": "string",
  "tts_voice_id": "string",
  "text": "string",
  "params": {},
  "error": "string",
  "active": true,
  "created_at": "2023-10-08T16:26:28.630Z",
  "converted_at": "2023-10-08T16:26:28.630Z",
  "listen_count": 0,
  "process_stage": "string",
  "note": {
    "id": "string",
    "text": "string",
    "active": true
  }
}

POST /api/recordings/tts

This endpoint is deprecated.

Create an original text-to-speech recording.

Request

Request Body
{
  "project_id": "00000000-0000-0000-0000-000000000001",
  "parent_folder_id": "00000000-0000-0000-0000-000000000001",
  "label": "string",
  "voice_id": "00000000-0000-0000-0000-000000000001",
  "text": "string"
}
  • 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
{
  "label": "string",
  "starred": true
}

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
[
  {"id": "00000000-0000-0000-0000-000000000001"}
]

GET /api/recordings/export

Export all conversions for an original recording.

Request

Query parameters:

Parameter Description
original_id The ID of the original recording to export.
starred_only When 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
{
  "parent_folder_id": "00000000-0000-0000-0000-000000000001",
  "text": "string"
  "text_language": "ISO 639 language code", (Optional)
  "label": "string" (Optional)
}
  • 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

POST /api/v2/recordings/tts

Create an original text-to-speech recording.

Request

Request Body
{
  "parent_folder_id": "00000000-0000-0000-0000-000000000001",
  "text": "string"
  "text_language": "ISO 639 language code", (Optional)
  "label": "string" (Optional)
}
  • 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.

GET /api/tts-voices

Get a list of the available TTS voices.

Response

Response Body
[
    {
        "id": "00000000-0000-0000-0000-000000000001",
        "visibility": "public",
        "name": "string",
        "f0": 0,
        "is_default": true
    }
]

Notes

POST /api/notes

Request

Request Body
{
  "recording_id": "string",
  "text": "string"
}

Response

Response Body
{
  "recording_id": "string",
  "text": "string",
  "id": "string",
  "active": true
}

PUT /api/notes

Request

Request Body
{
  "recording_id": "string",
  "text": "string"
}

Response

A JSON object containing the updated note.

DELETE /api/notes

Delete a note.

Request

Request Body
{
  "recording_id": "string",
}

Response

A JSON object containing the deleted note.

Statistics

GET /api/stats

Get the statistics for your account.

Response

Response Body
{
  "time_converted": {
    "total": 0,
    "current_month": 0,
    "previous_monthes": [
      {
        "month": "2023-11-08",
        "duration": 0
      }
    ]
  },
  "conversions": {
    "total": 0,
    "completed": 0,
    "in_progress": 0,
    "failed": 0
  },
  "models": [
    {
      "id": "string",
      "name": "string",
      "conversions_count": 0,
      "converted_time": 0
    }
  ]
}

GET /api/stats/projects

Get statistics for a list of projects.

Request

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

Response

Response Body
[
  {
    "project_id": "00000000-0000-0000-0000-000000000001",
    "time_converted": {
      "total": 0,
      "current_month": 0
    },
    "conversions": {
      "total": 0,
      "completed": 0,
      "in_progress": 0,
      "failed": 0
    }
  }
]

GET /api/stats/folders

Get statistics for a list of folders.

Request

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

Response

Response Body
[
  {
    "folder_id": "00000000-0000-0000-0000-000000000001",
    "stats": {
      "total": 0,
      "completed": 0,
      "in_progress": 0,
      "failed": 0
    }
  }
]

Orders

POST /api/v2/orders

Request

Request Body
{
  "original_id": "00000000-0000-0000-0000-000000000001",
  "conversions": [
    {
      "voice_id": "00000000-0000-0000-0000-000000000001",
      "narration_style_id": "00000000-0000-0000-0000-000000000001" (Required for TTS),
      "accent_id": "00000000-0000-0000-0000-000000000001" (Optional),
      "semitones_correction": 0 (Optional),
      "label": "string" (Optional)
    }
  ],
  "calibration_id": "00000000-0000-0000-0000-000000000001" (Optional),
  "use_calibration": false (Optional)
}
  • 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:

Name Description
limit Limit the number of voices in the response. Defaults to 25.
offset Offset the location where the list starts. Defaults to 0
sort Sort by parameter. name, pitch, rating or created_at
direction The sort direction. asc or desc
visibility Filter by visibility. public, paid, private or kids
species Filter by species. human, animal or other
gender Filter by gender. male or female
age_group Filter by age group. child, young, adult or senior
pitch_group Filter by pitch group. low, mid or high
nationality Filter by nationality.

Response

Response Body
{
"list": [
    {
    "id": "00000000-0000-0000-0000-000000000001",
    "owner_id": "00000000-0000-0000-0000-000000000001",
    "name": "string",
    "slug": "string",
    "visibility": "public",
    "species": "human",
    "artist": "string",
    "verified_artist": true,
    "gender": "male",
    "pitch": 0,
    "age_group": "child",
    "pitch_group": "low",
    "nationality": "string",
    "image_url": "string",
    "thumbnail_url": "string",
    "description": "string",
    "rating": 0,
    "active": true,
    "created_at": "2024-02-28T11:21:32.401Z",
    "favorite": false,
    "available": false,
    "accents": [
        {
        "id": "00000000-0000-0000-0000-000000000001",
        "is_default": true,
        "native": true,
        "info": {
            "name": "string",
            "short_name": "string",
            "locale": "string"
        },
        "tiers": [
            {
            "name": "string"
            }
        ],
        "available": false,
        "settings": {
            "favorite": false,
            "semitones_correction": 0
        }
        }
    ],
    "narration_styles": [
        {
        "id": "00000000-0000-0000-0000-000000000001",
        "is_default": true,
        "info": {
            "name": "string"
        },
        "settings": {
            "favorite": false
        }
        }
    ],
    "tiers": [
        {
        "name": "string"
        }
    ]
    }
],
"pagination": {
    "count": 0,
    "limit": 0,
    "offset": 0
}
}

GET /api/v2/voices/search

Search for a voice by its name.

Request

Optional query parameters:

Parameter Description
name The name of the voice.
limit Limit the number of search results.

Response

Response Body
[
    {
    "id": "00000000-0000-0000-0000-000000000001",
    "owner_id": "00000000-0000-0000-0000-000000000001",
    "name": "string",
    "slug": "string",
    "visibility": "public",
    "species": "human",
    "artist": "string",
    "verified_artist": true,
    "gender": "male",
    "pitch": 0,
    "age_group": "child",
    "pitch_group": "low",
    "nationality": "string",
    "image_url": "string",
    "thumbnail_url": "string",
    "description": "string",
    "rating": 0,
    "active": true,
    "created_at": "2024-02-28T11:21:32.401Z",
    "favorite": false,
    "available": false,
    "accents": [
        {
        "id": "00000000-0000-0000-0000-000000000001",
        "is_default": true,
        "native": true,
        "info": {
            "name": "string",
            "short_name": "string",
            "locale": "string"
        },
        "tiers": [
            {
            "name": "string"
            }
        ],
        "available": false,
        "settings": {
            "favorite": false,
            "semitones_correction": 0
        }
        }
    ],
    "narration_styles": [
        {
        "id": "00000000-0000-0000-0000-000000000001",
        "is_default": true,
        "info": {
            "name": "string"
        },
        "settings": {
            "favorite": false
        }
        }
    ],
    "tiers": [
        {
        "name": "string"
        }
    ]
    }
]

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

Mark a voice as a favorite.

Request

Request Body
{
  "favorite": true
}

Response

A JSON object containing the updated voice.

POST /api/v2/voices/settings

Set the settings for a voice.

Request

Body parameters:

Name Description
voice_id Id of voice to update. Required
`narration_style_id Id of narration_style to mark as favorite. Optional
accent_id Id of accent to mark as favorite. Optional
semitones_correction If accent_id is specified - save semitone_correction value. Optional
Request Body
{
    "voice_id": "00000000-0000-0000-0000-000000000001",
    "narration_style_id": "00000000-0000-0000-0000-000000000001"
    "accent_id": "00000000-0000-0000-0000-000000000001",
    "semitones_correction": 0,
}

Response

A JSON object containing the updated voice.

Accents

GET /api/v2/accents/samples

Samples available for an accent

Request

Query parameters:

Name Description
accent_id Id of accent. Required

Response

Response Body
{
  "samples": { ... }
}