Voice clone

Primary agent path

Use the Universal Skill with the MCP tool beatra.voices.clone. The tool is billable, consent-gated, and returns an asynchronous task.

1. Confirm with the user that they hold the rights to this voice. Set consent_attested: true only after that explicit confirmation.
2. Upload the local sample with beatra.assets.upload and use its artifact ID. 10 seconds to 5 minutes of clean, single-speaker audio works best.
3. Create one opaque client_request_id and submit the final arguments once.
4. Poll the returned task with beatra.tasks.get; the terminal response returns the new voice_id.

AI guide

Tool arguments

{
  "sample": { "type": "artifact", "artifact_id": "artifact_01JX..." },
  "display_name": "Brand narration - female",
  "consent_attested": true,
  "client_request_id": "voice-clone-opaque-1"
}

sample accepts an artifact, HTTPS URL, or data URI. display_name is required (≤255 characters). A request without consent_attested: true is rejected.

Models, controls, and cost

Omit model (or use auto) unless the user names one. beatra.models.list with capability: "voice_clone" is the current source for selectable models, accepted sample kinds, and the fixed price.

Voice cloning has one fixed charge when the activated voice is created successfully. Success means Beatra already ran a short formal synthesis to activate the clone — that activation is included in the charge; later speech synthesis is billed separately. A failed clone or activation does not retain the charge.

Task status and recovery

queued and running are not failures. Keep polling the same task_id; never submit a replacement because work is still running. On a lost create response, retry the identical arguments with the same client_request_id. If any input changes, use a new ID. The returned voice_id works directly as the voice field in text to speech, stays valid long-term, and can be inspected or deleted in voices.

REST API

Direct protocol integrations may use POST /v1/voices and the shared task endpoints. Follow the generated API operation. Skill + MCP is the recommended integration; use REST for custom, non-agent applications.