Getting Started

This guide walks through a complete Voice ReGen flow.

Choose Your Environment

The Voice ReGen API is available in Sandbox and Production environments. In the examples below, replace <api-base-url> with the base URL for the environment you want to target.

Use Sandbox while developing and testing your integration. Switch to Production when you are ready for live workloads. Both environments expose the same endpoints and behave identically.

Overview

The diagram below illustrates the steps for the first use of the service:

The following sections describe each step.

Note: The examples use cURL commands, so no API client code is required.

Create an account

Create an account in the Developer Portal: https://api.waves.com

Note: Creating an account also creates a user. If you already have a user, the system will take you to the account where you are registered.

Create an account:

Create an API key

The next step is to create an API key that allows you to authenticate and access the service from an API client.

In the Developer Portal, generate your OAuth2 clientId and clientSecret in API Keys.

Go to the API Keys tab
Click Create API Key
Give the key a name. This is a convenience that allows you to manage your API keys.
Click the Create API Key button
After the API key is created, copy the API key secret shown in the dialog. This secret is shown only once.

Notes:

The API key secret expires after 2 years.
You can create a new API key secret at any time using the Regenerate action in the API keys table.

Authenticate - Use the API key to get an access token

Voice ReGen uses Microsoft Entra ID bearer tokens. Follow Authentication for the full token request example.

The authentication request requires these parameters:

Parameter	Description
Tenant ID	Identifies the Microsoft Entra ID tenant used for authentication. You can find the value of this parameter in the API Keys tab.
Client ID	The client identifier for the API key/application credentials. You can find the value of this parameter in the API key you created.
Client Secret	This is the API key secret you copied in the previous step.
Scope	The fixed default scope for Voice ReGen API access. You can find this value in the API Keys tab.

cURL: get an access token
TENANT_ID="<tenantId>"
CLIENT_ID="<clientId>"
CLIENT_SECRET="<clientSecret>"
SCOPE="api://<application-id-uri>/.default"

curl -s -X POST "https://login.microsoftonline.com/$TENANT_ID/oauth2/v2.0/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "client_id=$CLIENT_ID" \
  --data-urlencode "client_secret=$CLIENT_SECRET" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "scope=$SCOPE"

Command result:

{"token_type":"Bearer","expires_in":3599,"ext_expires_in":3599,"access_token":<access_token>}%

Upload a file

The next step is to upload your input file.

Use registerFile to get a signed upload URL, then upload your local file to that URL. registerFile returns registered_file.file_id and registered_file.file_upload_link.

registered_file.file_id is the unique file ID assigned by the Voice ReGen service. Use it to check processing status and retrieve the related output.

Note: If your file is already hosted, you can use registerFileFromUrl instead.

cURL: registerFile
API_BASE_URL="<api-base-url>"
ACCESS_TOKEN="<access_token>"

curl -s -X POST "$API_BASE_URL/api/v1/registerFile" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "file_to_register": {
      "client_file_id": "my-file-001"
    }
  }'

Command result:

{"registered_file":{"file_id":"<file_id>","client_file_id":"my-file-001","file_name":"<file_id>","file_upload_link":"<registered_file.file_upload_link>","file_upload_expiry":1780984920,"success":true,"error_code":0}}

Use the signed upload URL to upload the input file bytes before starting processing.

cURL: upload file to signed URL
UPLOAD_URL="<registered_file.file_upload_link>"
INPUT_FILE="./input.wav"

curl -s -X PUT "$UPLOAD_URL" \
  -H "x-ms-blob-type: BlockBlob" \
  -H "Content-Type: application/octet-stream" \
  --upload-file "$INPUT_FILE"

Initiate File Processing

The next step is to process the file.

Start processing with startProcess.

Set the optional options.output_type field to wav, mp3, flac, aiff, ogg, opus, aac, or m4a to select the output audio format. If you omit this field, the output uses the original file format.

There are two options for tracking the file processing status:

Polling: poll getFilesStatus until the file reaches Succeeded.
Webhook: configure a webhook URL in the Developer Portal and enable it via startProcess options.webhook to receive status/progress updates as callbacks.

For simplicity, we will use the polling method in our example.

cURL: startProcess (polling flow)
API_BASE_URL="<api-base-url>"
ACCESS_TOKEN="<access_token>"
FILE_ID="<file_id>"

curl -s -X POST "$API_BASE_URL/api/v1/startProcess" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d "{\"file_id\": \"$FILE_ID\",\"options\": { \"model\": \"voice_regen_v1\", \"output_type\": \"wav\" } \
  }"

cURL: startProcess response
{"file_id":"<file_id>","error":null}

For reference, here is an example using the webhook option:

cURL: startProcess (webhook flow)
# Configure your webhook URL in the Developer Portal first.
API_BASE_URL="<api-base-url>"
ACCESS_TOKEN="<access_token>"
FILE_ID="<file_id>"

curl -s -X POST "$API_BASE_URL/api/v1/startProcess" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d "{
    \"file_id\": \"$FILE_ID\",
    \"options\": { \"model\": \"voice_regen_v1\", \"webhook\": true, \"webhook_secret\": \"my-webhook-secret\" }
  }"

Wait for Processing to Complete

Poll the file processing status until it completes.

You can request status for up to 100 files in a single call by providing multiple fileIds.

cURL: getFilesStatus (polling)
API_BASE_URL="<api-base-url>"
ACCESS_TOKEN="<access_token>"
FILE_ID="<file_id>"

curl -s -X POST "$API_BASE_URL/api/v1/getFilesStatus" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d "{ \"fileIds\": [\"$FILE_ID\"] }"

cURL: getFilesStatus response while waiting to start processing
[{"id":"<file_id>","status":"Pending","errorCode":0,"progress":0}]

cURL: getFilesStatus response while processing
[{"id":"<file_id>","status":"InProgress","errorCode":0,"progress":<progress_percentage>}]

cURL: getFilesStatus response when processing completed
[{"id":"7DF15674-C1EF-404F-B4CA-67DDA15DA1FB","status":"Succeeded","errorCode":0,"progress":100}]

Download the Output

When status is Succeeded, call getOutputFileUrl to get a signed URL and download the processed file.

cURL: get download URL + download output
API_BASE_URL="<api-base-url>"
ACCESS_TOKEN="<access_token>"
FILE_ID="<file_id>"

curl -s -X POST "$API_BASE_URL/api/v1/getOutputFileUrl" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d "{ \"fileId\": \"$FILE_ID\" }"

cURL: getOutputFileUrl response 
{"url":"<download_url>","expiry":1782194400}

cURL: download output
# Download the processed file, assuming a WAV input file
ODOWNLOAD_URL=<download_url>
curl -L "$DOWNLOAD_URL" -o "./output.wav"

cURL: download response 
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
 46 5630k   46 2607k    0     0   105k      0  0:00:53  0:00:24  0:00:29  108k

Choose Your Environment#

Overview#

Create an account#

Create an API key#

Authenticate - Use the API key to get an access token#

Upload a file#

Initiate File Processing#

Wait for Processing to Complete#

Download the Output#