startProcess

The startProcess endpoint starts processing a file. Call this after registering a file with either registerFile or registerFileFromUrl. This endpoint requires authentication.

Endpoint

POST/api/v1/startProcess

Authentication

Bearer token required. Include Authorization: Bearer <token>.

Request Body

The request body must be a JSON object with the following structure:

{
  "file_id": "file-abc123",
  "options": {
    "model": "voice_regen_v1",
    "webhook": true,
    "webhook_secret": "my-webhook-secret",
    "output_type": "wav"
  }
}

Request Parameters

Parameter	Type	Required	Description
`file_id`	string	Yes	File ID to process.
`options`	object	Yes	Processing options object.
`options.model`	string	Yes	The processing model version to use. Currently the only supported value is `voice_regen_v1`. Additional versions will be available in future releases.
`options.webhook`	boolean	No	Whether to send webhook notifications for processing events (progress updates, success, and failure). Configure your webhook URL in the user portal.
`options.webhook_secret`	string	No	Optional webhook secret (max 1000 characters). Use it to secure webhook notifications.
`options.output_type`	string	No	Output audio format. Supported values are `wav`, `mp3`, `flac`, `aiff`, `ogg`, `opus`, `aac`, and `m4a`. If omitted, the output uses the original file format.

Response

Success Response (200)

200Success

Returns an object with the requested file_id and error (null on success).

{ "file_id": "file-abc123", "error": null }

Error Responses

400Bad Request

Returns a ValidationErrorResponse if the request validation fails.

401Unauthorized

Returns an OperationMessage if authentication fails.

403Forbidden

Returns an OperationMessage if access is denied.

404Not Found

Returns an OperationMessage if the file is not found.

Example Request

Example Request
{
  "file_id": "file-abc123",
  "options": {
    "model": "voice_regen_v1",
    "webhook": true,
    "webhook_secret": "my-webhook-secret",
    "output_type": "wav"
  }
}

cURL Example

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

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

Example Response

Example Response
{ "file_id": "file-abc123", "error": null }

Webhook Notifications

When options.webhook is set to true, the service will send HTTP POST requests to your configured webhook URL for processing events. Each webhook notification has the following structure.

Webhook request (POST/PUT)

If your webhook is configured with a secret, it will be sent based on the configured secret_position: header, query, or body.

Secret in header

The secret is sent as Authorization: Bearer <secret>. The JSON body does not include a secret field.

POST /webhook
Authorization: Bearer <webhook_secret>
Content-Type: application/json

{
  "userId": "string",
  "type": "status-updated | progress-updated | error-updated",
  "message": {
    "fileId": "string",
    "status": "Ready | Uploading | Queued | In Progress | Processed | Didn't Pass Validation | Retry Needed | Failed-Not-Deleted | Deleted",
    "progress": "int (0-100)",
    "errorCode": "0 | -1 | -2 | -3 | -4 | -5 | -6 | -7 | -8 | -9 | -10 | -11 | -12 | -13 | -14 | -15 | -16 | -17 | -18"
  }
}

Secret in query

The secret is sent as a query parameter: ?secret=<webhook_secret>.

POST /webhook?secret=<webhook_secret>
Content-Type: application/json

Secret in body

The secret is included in the JSON body as secret.

{
  "secret": "<webhook_secret>",
  "userId": "string",
  "type": "status-updated | progress-updated | error-updated",
  "message": { ... }
}

Webhook request (GET)

If your webhook method is configured as GET, the payload is sent via query parameters. In particular, message is sent as a JSON string (URL-encoded).

GET with secret in header

GET /webhook?userId=<userId>&type=<eventType>&message=<urlencoded_json>
Authorization: Bearer <webhook_secret>

GET with secret in query

GET /webhook?secret=<webhook_secret>&userId=<userId>&type=<eventType>&message=<urlencoded_json>

GET with secret in body

GET requests do not have a request body, so secret_position=body does not apply for GET webhooks.

FileStatus Enum Values

Value	Description
`Ready`	File is ready for processing
`Uploading`	File is being uploaded
`Queued`	File is queued for processing
`In Progress`	File is currently being processed
`Processed`	Processing completed successfully
`Didn't Pass Validation`	File failed validation checks
`Retry Needed`	Processing failed, retry may be needed

FileErrorCode Enum Values

Value	Code	Description
`None`	0	No error
`SystemError`	-1	A system error occurred
`CorruptedFile`	-2	The file is corrupted or unreadable
`NotEnoughVoice`	-3	Not enough voice content detected
`MultiChannelVoiceNotSupported`	-4	Multi-channel voice is not supported
`AudioQualityTooHigh`	-5	Audio quality exceeds supported limits
`AudioQualityTooLow`	-6	Audio quality is below minimum requirements
`UnsupportedCodec`	-7	The media codec is not supported
`MultiTrackAudioNotSupported`	-8	Multi-track audio is not supported
`UnknownValidationError`	-9	An unknown validation error occurred
`NotEnoughCredits`	-10	Not enough credits to process the file
`NotFound`	-11	File not found
`TimeOut`	-12	Processing timed out
`FileSizeTooLarge`	-13	The file size exceeds the allowed limit
`DurationTooShort`	-14	The file duration is below the minimum requirement
`DurationTooLong`	-15	The file duration exceeds the maximum limit
`UnsupportedMediaContainer`	-16	The media container is not supported
`InputFileDownloadFailed`	-17	The service failed to download the input file from your provided URL (e.g., expired URL or not publicly accessible)
`NoAudioStreamsFound`	-18	No audio streams were found in the file

Notes

This endpoint requires an API key for authentication.
Call this endpoint after registering a file with registerFile (after uploading to the provided URL) or registerFileFromUrl.
The file must have been previously registered using registerFile or registerFileFromUrl.
Configure your webhook URL in the user portal to receive webhook notifications.

Endpoint#

Authentication#

Request Body#

Request Parameters#

Response#

Success Response (200)#

Error Responses#

Example Request#

cURL Example#

Example Response#

Webhook Notifications#

Webhook request (POST/PUT)#

Secret in header#

Secret in query#

Secret in body#

Webhook request (GET)#

GET with secret in header#

GET with secret in query#

GET with secret in body#

FileStatus Enum Values#

FileErrorCode Enum Values#

Notes#