# Speech to speech
> Convert a source voice recording into a target voice while preserving natural timing, phrasing, and emotion.

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

AI integration guide: https://docs.beatra.ai/llms/audio-speech-to-speech.md

## Tool arguments

```json
{
  "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](https://docs.beatra.ai/en/docs/capabilities/speech/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](https://docs.beatra.ai/en/docs/capabilities/speech/audio-processing#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](https://docs.beatra.ai/en/docs/capabilities/speech/text-to-speech#limits-and-errors).
- When `voice` is an ElevenLabs [cloned voice](https://docs.beatra.ai/en/docs/capabilities/speech/voice-clone#elevenlabs-explicit-ready-on-success-cloning),
  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.

```json
{
  "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](https://docs.beatra.ai/en/docs/capabilities/speech/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](https://docs.beatra.ai/en/docs/api-reference). Skill + MCP is the recommended
integration; use REST for custom, non-agent applications.