registerFile

The registerFile endpoint registers a new file for processing, returning an upload URL for the file. This endpoint requires authentication.

After registering, upload your file to the provided file_upload_link, then call startProcess to begin processing.

💡Tip

If your file is already hosted at a URL, use registerFileFromUrl instead—no need to upload the file yourself.

Endpoint

POST/api/v1/registerFile

Authentication

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

Request Body

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

{
  "file_to_register": {
    "client_file_id": "string",
    "start": 0,
    "end": 0
  }
}

Request Parameters

Parameter	Type	Required	Description
file_to_register	object	Yes	File object to register.
file_to_register.client_file_id	string	Yes	Client-side unique identifier for the file.
file_to_register.start	number	No	Start time in seconds for partial processing.
file_to_register.end	number	No	End time in seconds for partial processing.

Response

Success Response (200)

200Success

Returns a RegisterFileResponse object with upload info:

{
  "registered_file": {
    "file_id": "string",
    "client_file_id": "string",
    "file_name": "string",
    "file_upload_link": "https://storage.example.com/upload?signature=...",
    "file_upload_expiry": 1234567890,
    "success": true,
    "error_code": 0
  }
}

Response Fields

Field	Type	Description
registered_file	object	Registered file object with upload information.
registered_file.file_id	string	Server-generated unique identifier for the file.
registered_file.client_file_id	string	Client-side identifier that was provided in the request.
registered_file.file_name	string	Base name of the file without the extension (e.g. audio.wav becomes audio).
registered_file.file_upload_link	string	Signed URL for uploading the file.
registered_file.file_upload_expiry	integer	Unix timestamp when the upload link expires.
registered_file.success	boolean	Whether the file was registered successfully.
registered_file.error_code	integer	Error code for failed registrations. Possible values: 0 (success) or 500 (internal error).

client_file_id vs file_id

• client_file_id: your own identifier for correlation/deduplication on the client side. It is echoed back in responses.
• file_id: the server-generated identifier returned from registration. Use it in subsequent calls (startProcess, getFilesStatus, download URL requests).

Use client_file_id when you need to connect Voice Regen responses back to records in your own system. For example, it can be the ID of a file row in your database, an upload job ID, or another stable value you already use on the client. Voice Regen does not require this value to match the uploaded file name, and you should not use it in place of file_id when calling later endpoints.

Correlating client_file_id with file_id

const localFile = {
  id: "asset-42",
  name: "speech-sample.wav",
};

const registerResponse = await registerFile({
  file_to_register: {
    client_file_id: localFile.id,
  },
});

const { file_id, client_file_id } = registerResponse.registered_file;

// Store the server file_id next to your own client_file_id.
await saveVoiceRegenFileMapping({
  local_asset_id: client_file_id,
  voiceregen_file_id: file_id,
});

// Use file_id, not client_file_id, in the processing request.
await startProcess({
  file_ids: [file_id],
});

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.

Example Request

Example Request

{
  "file_to_register": {
    "client_file_id": "my-file-001"
  }
}

cURL Example

cURL Example

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"
  }
}'

Example Response

Example Response

{
  "registered_file": {
    "file_id": "file-abc123",
    "client_file_id": "my-file-001",
    "file_name": "audio",
    "file_upload_link": "https://storage.example.com/upload?signature=xyz&expires=1234567890",
    "file_upload_expiry": 1234567890,
    "success": true,
    "error_code": 0
  }
}

Notes

• This endpoint requires an API key for authentication.
• Files must be registered before they can be processed.
• After registering, use the file_upload_link to upload the actual file content, then call startProcess to start processing.