registerFileFromUrl

The registerFileFromUrl endpoint registers a new file for processing from a source URL provided by the user. After registration, call startProcess to begin processing. This endpoint requires authentication.

💡Tip

If you need to upload a file from your local system, use registerFile instead, which provides you with an upload URL.

Endpoint

POST/api/v1/registerFileFromUrl

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,
    "source_url": "string"
  }
}

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.
file_to_register.source_url	string	Yes	The URL where your file is hosted. Must be publicly accessible and must remain valid (not expire) for at least 1 hour.

Response

Success Response (200)

200Success

Returns a RegisterFileFromUrlResponse object with registered file information:

{
  "registered_file": {
    "file_id": "string",
    "client_file_id": "string",
    "file_name": "string",
    "success": true,
    "error_code": 0
  }
}

Response Fields

Field	Type	Description
registered_file	object	Registered file object.
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.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 import job ID, or another stable value you already use on the client. Voice Regen does not require this value to match the source URL or 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 sourceFile = {
  id: "asset-42",
  url: "https://example.com/speech-sample.wav",
};

const registerResponse = await registerFileFromUrl({
  file_to_register: {
    client_file_id: sourceFile.id,
    source_url: sourceFile.url,
  },
});

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",
    "source_url": "https://example.com/my-audio-file.wav"
  }
}

cURL Example

cURL Example

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

curl -s -X POST "$API_BASE_URL/api/v1/registerFileFromUrl" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
  "file_to_register": {
    "client_file_id": "my-file-001",
    "source_url": "https://example.com/my-audio-file.wav"
  }
}'

Example Response

Example Response

{
  "registered_file": {
    "file_id": "file-abc123",
    "client_file_id": "my-file-001",
    "file_name": "audio",
    "success": true,
    "error_code": 0
  }
}

Notes

• This endpoint requires an API key for authentication.
• After registration, call startProcess to begin processing.
• The source_url must be publicly accessible for the server to download the file.
• If your source_url is time-limited (signed URL), ensure its expiry time is at least 1 hour from when you call this endpoint.