Speech to speech

Convert a source speech recording into a target Beatra voice while preserving the original timing, pauses, cadence, and vocal performance.

Primary agent path

Use the Universal Skill with the MCP tool beatra.speech.convert. The tool is billable and returns an asynchronous task.

1. Pick an eligible target voice first: call beatra.voices.list with supports_speech_to_speech: true (REST: GET /v1/voices?supports_speech_to_speech=true). Only voices with capabilities.supports_speech_to_speech: true — ElevenLabs preset voices and ready ElevenLabs cloned voices — can perform speech-to-speech conversion.
2. Upload the source speech recording with beatra.assets.upload and use the returned artifact_id (or pass an https_url).
3. Create one opaque client_request_id and submit the final arguments once.
4. Poll the returned task with beatra.tasks.get until it is terminal.

AI guide

Tool arguments

{
  "audio": { "type": "artifact", "artifact_id": "artifact_01JX..." },
  "voice": "voice_preset_elevenlabs_001",
  "model": "auto",
  "remove_background_noise": true,
  "format": "mp3",
  "client_request_id": "sts-opaque-1"
}

• audio (required; source accepted as an input alias on both MCP and REST): an artifact reference ({"type": "artifact", "artifact_id": "..."}) or HTTPS URL ({"type": "https_url", "url": "https://..."}). Accepted formats are MP3, WAV, M4A, AAC, FLAC, OGG, and Opus. Duration must be 1.0 second to 300.0 seconds (5 minutes), and file size at most 50 MiB. Inputs shorter than 1.0 second, longer than 5 minutes, or larger than 50 MiB are rejected before billing with 422 invalid_request.
• voice (required; voice_id accepted as an input alias on both MCP and REST): voice_id of an eligible target voice (see voices). Passing a MiniMax or Doubao voice returns 422 invalid_request (details.reason: "voice_unsupported_for_speech_to_speech", details.required_capability: "supports_speech_to_speech") before billing with zero credit charge. Passing a voice waiting for activation or expired returns 422 invalid_request (details.reason: "voice_pending_activation" or "voice_expired").
• model (optional, default "auto"): "auto" or "elevenlabs-sts-v2".
• remove_background_noise (optional, boolean, default false): strip light room tone and background noise from the source recording before conversion. For heavy background music or outdoor noise, run voice isolation first.
• stability (optional, 0.0–1.0), similarity_boost (optional, 0.0–1.0), style (optional, 0.0–1.0), use_speaker_boost (optional, boolean): optional target-voice expressiveness controls forwarded as ElevenLabs voice_settings.
• format (optional, default "mp3"): "mp3" (44.1 kHz), "wav" (24 kHz 16-bit mono PCM in a RIFF WAVE audio/wav container), "opus" (48 kHz), or "pcm" (raw 24 kHz 16-bit signed little-endian mono PCM, audio/pcm).
• seed (optional, integer 0–4,294,967,295): best-effort determinism hint.
• model_options (optional, object): forward-compatible bag for model-specific extension options.

Models, concurrency, and cost

beatra.models.list with capability: "speech_to_speech" is the live source for selectable models, formats, limits, and prices.

• elevenlabs-sts-v2: prepaid by started input minute (ceil(duration_seconds / 60)) at 721 credits per started minute (<= 60s reserves 721 credits; a 5-minute clip reserves 3,605 credits).
• Speech-to-speech shares the per-account 2-in-flight ElevenLabs voice-use limit (429 rate_limited, details.reason: speech_inflight_limit) with ElevenLabs text to speech.
• When voice is an ElevenLabs cloned voice, Beatra automatically prepares or restores the voice from its saved sample before conversion when needed.

Result

Speech-to-speech is an atomic audio capability: it outputs the converted target audio without adding a hidden transcription step.

{
  "type": "speech_to_speech",
  "model": "elevenlabs-sts-v2",
  "voice_id": "voice_preset_elevenlabs_001",
  "audio": {
    "artifact_id": "artifact_01JY...",
    "url": "https://cdn.beatra.ai/tenants/.../converted.mp3",
    "duration_seconds": 14.2,
    "mime_type": "audio/mpeg",
    "size_bytes": 227840
  }
}

When captions or timestamps are also needed for the converted clip, pass the returned audio.artifact_id to speech to text.

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. Failed tasks automatically refund the reserved credits. Artifact URLs are CDN addresses — copy them to your own storage promptly.

REST API

Direct protocol integrations may use POST /v1/audio/speech-to-speech with a stable Idempotency-Key header and the shared task endpoints. Follow the generated API reference. Skill + MCP is the recommended integration; use REST for custom, non-agent applications.