Voice Enhance

Voice Enhance part d’une voix existante (une voix phare, un clone ou une voix créée avec Voice Design) et produit des candidats plus propres du même locuteur, dans la même langue. Un clone issu d’un enregistrement bruité revient avec un bruit de fond réduit et une cible de qualité appliquée ; le locuteur, la langue et le débit sont conservés. Vous écoutez les candidats, convertissez celui qui vous plaît, et il fonctionne comme n’importe quel autre voice_id : REST, WebSocket et Speech-to-Speech.

Comparez chaque candidat à sa source avant de le convertir.

Vous partez d'un enregistrement ?

Clonez d’abord le locuteur, puis améliorez le clone.

Vous partez d'une description ?

Voice Design crée une nouvelle voix à partir de mots. Enhance améliore une voix que vous avez déjà.

Fonctionnement

1. Choisir une source

Une voix phare, l’un de vos clones ou un candidat Voice Design.

2. Améliorer

Une seule requête, aucun autre réglage. Les candidats sont prêts en une vingtaine de secondes.

3. Écouter

Comparez chaque candidat à la source sur la même phrase en synthèse vocale.

4. Convertir

Transformez votre choix en voice_id permanent.

La source n’est jamais modifiée. Chaque requête crée n_samples nouveaux candidats, des brouillons dotés d’un identifiant vox_emb_, exactement comme les candidats Voice Design : vous les écoutez via POST /post/speech/tts, les convertissez avec POST /voices/from-embedding, et ils expirent au bout de 30 jours s’ils ne sont pas convertis.

Accès

URL de base https://api.gradium.ai/api, clé API dans l’en-tête x-api-key.

Appel	Endpoint
Améliorer une voix	`POST /voice-generator/enhance`
Vérifier la disponibilité ou lister les candidats	`GET /voice-generator/embeddings`
Écouter un candidat	`POST /post/speech/tts`
Convertir un candidat	`POST /voices/from-embedding`
Supprimer un candidat	`DELETE /voice-generator/embeddings/{embedding_id}`

Démarrage rapide

L’exemple améliore un clone français. Remplacez $SOURCE par n’importe quel identifiant de voix ou de candidat qui vous appartient, ou par l’identifiant d’une voix phare.

Améliorer la voix

curl -s -X POST https://api.gradium.ai/api/voice-generator/enhance \
  -H "x-api-key: $GRADIUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"src_voice\": \"$SOURCE\",
    \"n_samples\": 2
  }" > candidates.json

CAND0=$(jq -r '.embeddings[0].embedding_id' candidates.json)

import os
import requests

API_KEY = os.environ["GRADIUM_API_KEY"]
BASE = "https://api.gradium.ai/api"
SOURCE = os.environ["SOURCE"]  # a voice id or a vox_emb_ candidate id

resp = requests.post(
    f"{BASE}/voice-generator/enhance",
    json={"src_voice": SOURCE, "n_samples": 2},
    headers={"x-api-key": API_KEY},
)
resp.raise_for_status()
candidates = [e["embedding_id"] for e in resp.json()["embeddings"]]

201 Created

{
  "embeddings": [
    { "embedding_id": "vox_emb_XeBcXDgoigTfL9Cv", "ready": false, "expires_at": "2026-10-21T13:03:52Z" },
    { "embedding_id": "vox_emb_ni8lehVHTb35siXI", "ready": false, "expires_at": "2026-10-21T13:03:53Z" }
  ]
}

Champ
`src_voice`	obligatoire	Un identifiant de voix (votre clone, un candidat converti ou une voix phare) ou un identifiant de candidat `vox_emb_`.
`n_samples`	facultatif	De 1 à 5 candidats, 1 par défaut.

Il n’y a rien d’autre à régler : la langue vient de la voix source, tout comme le locuteur. La requête est vérifiée avant toute mise en file d’attente : une source inconnue ou une source qui ne peut pas être améliorée échoue dès cette étape avec 404 ou 409, et rien n’est facturé.

Attendre les candidats

until curl -s -H "x-api-key: $GRADIUM_API_KEY" \
    "https://api.gradium.ai/api/voice-generator/embeddings?embedding_id=$CAND0" \
    | jq -e '.embeddings[0].ready' > /dev/null; do
  sleep 2
done

import time

def wait_until_ready(embedding_id, timeout_s=120):
    deadline = time.monotonic() + timeout_s
    while time.monotonic() < deadline:
        resp = requests.get(
            f"{BASE}/voice-generator/embeddings",
            params={"embedding_id": embedding_id},
            headers={"x-api-key": API_KEY},
        )
        resp.raise_for_status()
        found = resp.json()["embeddings"]
        if found and found[0]["ready"]:
            return found[0]
        time.sleep(2)
    raise TimeoutError(embedding_id)

for embedding_id in candidates:
    wait_until_ready(embedding_id)

200 OK

{
  "embeddings": [{
    "embedding_id": "vox_emb_XeBcXDgoigTfL9Cv",
    "ready": true,
    "kind": "enhance",
    "language": "fr",
    "created_at": "2026-09-21T13:03:52.591128",
    "expires_at": "2026-10-21T13:03:52.495534",
    "enhance_config": {
      "src_voice": "H5oin0KHqRTAxaeL",
      "src_language": "fr"
    },
    "prompt": null
  }]
}

Les candidats améliorés sont généralement prêts en quinze à vingt secondes. Dans la liste, kind vaut enhance et enhance_config contient l’identifiant de la source et sa langue. language est la langue de la voix source, que le candidat conserve. prompt est vide pour un candidat amélioré.

Écouter un candidat

Passez l’identifiant du candidat comme voice_id sur l’endpoint de synthèse vocale, avec un texte dans la langue de la voix. Synthétisez aussi la même phrase avec la voix source : la différence entre les deux fichiers correspond à ce qu’a fait Enhance.

for VOICE in "$CAND0" "$SOURCE"; do
  curl -s -X POST https://api.gradium.ai/api/post/speech/tts \
    -H "x-api-key: $GRADIUM_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{
      \"text\": \"Bonjour, c'est Constance. Même voix, un peu plus propre, j'espère.\",
      \"voice_id\": \"$VOICE\",
      \"model_name\": \"default\",
      \"output_format\": \"wav\",
      \"only_audio\": true
    }" --output "$VOICE.wav"
done

LINE = "Bonjour, c'est Constance. Même voix, un peu plus propre, j'espère."

for voice_id, path in [(candidates[0], "candidate-0.wav"), (SOURCE, "source.wav")]:
    resp = requests.post(
        f"{BASE}/post/speech/tts",
        json={
            "text": LINE,
            "voice_id": voice_id,
            "model_name": "default",
            "output_format": "wav",
            "only_audio": True,
        },
        headers={"x-api-key": API_KEY},
    )
    resp.raise_for_status()
    with open(path, "wb") as f:
        f.write(resp.content)

Les candidats sont soumis aux mêmes restrictions que les candidats Voice Design : REST uniquement, texte d’écoute plafonné, et une erreur opaque 404 Embedding not found tant qu’ils ne sont pas prêts.

Convertir le candidat en voix

curl -s -X POST https://api.gradium.ai/api/voices/from-embedding \
  -H "x-api-key: $GRADIUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"voxium_embedding_id\": \"$CAND0\",
    \"name\": \"Constance (enhanced)\",
    \"description\": \"French support voice, enhanced\"
  }" > voice.json

VOICE=$(jq -r '.uid' voice.json)

resp = requests.post(
    f"{BASE}/voices/from-embedding",
    json={
        "voxium_embedding_id": candidates[0],
        "name": "Constance (enhanced)",
        "description": "French support voice, enhanced",
    },
    headers={"x-api-key": API_KEY},
)
resp.raise_for_status()
voice_id = resp.json()["uid"]

201 Created

{
  "uid": "w0F73K2fcf3X2Vcn",
  "name": "Constance (enhanced)",
  "description": "French support voice, enhanced",
  "filename": "vox_emb_XeBcXDgoigTfL9Cv",
  "start_s": 0.0,
  "is_catalog": false,
  "is_pro_clone": false,
  "language": "fr",
  "tags": []
}

uid est votre voice_id permanent. Conservez-le. La nouvelle voix garde la language de la source. La conversion est gratuite, occupe un emplacement de voix personnalisée et supprime l’expiration du candidat. Les candidats issus d’une même requête sont des variations : si l’un d’eux vous plaît, convertissez-le plutôt que de relancer la requête. La voix source n’est pas modifiée : vous pouvez donc conserver les deux, ou supprimer la source une fois satisfait de la version améliorée.

Exemple complet

Définissez GRADIUM_API_KEY et SOURCE, puis lancez le script. Il crée une vraie voix dans votre compte.

voice_enhance.py

import os
import time

import requests

BASE_URL = "https://api.gradium.ai/api"
HEADERS = {"x-api-key": os.environ["GRADIUM_API_KEY"]}
SOURCE = os.environ["SOURCE"]
LINE = "Hi, this is your assistant. How can I help you today?"  # in the source voice's language
N_SAMPLES = 3


def check(resp):
    if not resp.ok:
        raise RuntimeError(f"HTTP {resp.status_code}: {resp.text}")
    return resp


def enhance(src_voice, n_samples=1):
    resp = check(requests.post(
        f"{BASE_URL}/voice-generator/enhance",
        headers=HEADERS,
        json={"src_voice": src_voice, "n_samples": n_samples},
    ))
    return [c["embedding_id"] for c in resp.json()["embeddings"]]


def wait_until_ready(candidate_ids, timeout_s=120.0):
    deadline = time.monotonic() + timeout_s
    pending = set(candidate_ids)
    while pending:
        for candidate_id in sorted(pending):
            resp = check(requests.get(
                f"{BASE_URL}/voice-generator/embeddings",
                headers=HEADERS,
                params={"embedding_id": candidate_id},
            ))
            embeddings = resp.json()["embeddings"]
            if not embeddings:
                raise RuntimeError(f"candidate {candidate_id} not found")
            if embeddings[0]["ready"]:
                pending.discard(candidate_id)
        if pending:
            if time.monotonic() > deadline:
                raise TimeoutError(f"still not ready: {sorted(pending)}")
            time.sleep(2.0)


def synthesise(voice_id, text, path):
    resp = check(requests.post(
        f"{BASE_URL}/post/speech/tts",
        headers=HEADERS,
        json={"text": text, "voice_id": voice_id, "output_format": "wav", "only_audio": True},
    ))
    with open(path, "wb") as f:
        f.write(resp.content)


def convert(candidate_id, name, description=None):
    resp = check(requests.post(
        f"{BASE_URL}/voices/from-embedding",
        headers=HEADERS,
        json={"voxium_embedding_id": candidate_id, "name": name, "description": description},
    ))
    return resp.json()["uid"]


if __name__ == "__main__":
    print("[1/4] enhancing")
    candidates = enhance(SOURCE, N_SAMPLES)

    print("[2/4] waiting until ready")
    wait_until_ready(candidates)

    print("[3/4] auditioning")
    synthesise(SOURCE, LINE, "source.wav")  # the same line without enhancement
    for i, candidate_id in enumerate(candidates):
        synthesise(candidate_id, LINE, f"candidate-{i}.wav")
        print(f"      candidate-{i}.wav vs source.wav")

    # Listen, then convert the one you keep. This example keeps the first.
    print("[4/4] converting")
    voice_id = convert(candidates[0], "Assistant (enhanced)", f"Enhanced from {SOURCE}")
    print(f"      voice_id={voice_id}")
    print("done")

Sources compatibles

Source	Compatible	Remarques
Voix phare	Oui	N’importe quel identifiant des voix phares.
Clone instantané	Oui, s’il a une langue	Les clones créés sans `language` renvoient `409 The source voice has no language`. Définissez-la une fois avec `PUT /voices/{voice_id}` et réessayez. La langue doit être celle parlée dans l’enregistrement : une mauvaise étiquette est acceptée mais dégrade discrètement le résultat.
Candidat ou voix convertie issus de Voice Design	Oui	Utilisez l’identifiant `vox_emb_` ou le `voice_id` converti.
Candidat amélioré	Oui	Le candidat doit être prêt (`409` sinon).
Clone pro	Non	`409 This voice has no embedding the voice generator can edit.`
Voix d’un autre compte	Non	`404` opaque.

Conseils issus de nos tests

Comparez avec la source lisant le même texte. Enhance change la façon dont la voix sonne, pas ce qu’elle dit ni la langue dans laquelle elle parle. Placez la source et le candidat côte à côte dans votre interface de validation, sur la même phrase.
Commencez par un clone. Les voix phares sont déjà produites à partir d’enregistrements propres ; le clone que vous aimeriez entendre plus propre est la source naturelle.
Les candidats varient. Cinq échantillons issus d’une requête, ou cinq requêtes distinctes, donnent cinq résultats légèrement différents. Convertissez celui qui vous plaît ; ne comptez pas sur une nouvelle exécution pour le reproduire.
Conservez la source. Convertir un candidat ne remplace pas la voix source. Basculez votre voice_id une fois que vous avez écouté, et supprimez l’ancienne voix lorsque vous n’en avez plus besoin.
Prévoyez l’attente. Les candidats améliorés prennent quinze à vingt secondes, plus que les candidats Voice Design. Interrogez régulièrement leur état plutôt que de bloquer une requête dessus.

Cycle de vie des candidats

Les candidats améliorés suivent le cycle de vie des candidats Voice Design : conservation de 30 jours, levée à la conversion, et DELETE /voice-generator/embeddings/{embedding_id} pour en supprimer un plus tôt. Supprimer la voix ou le candidat source après le 201 ne fait jamais échouer la requête : chaque candidat conserve sa propre copie de la source.

Limites

Limite	Valeur
Candidats par requête	De 1 à 5, 1 par défaut
Langues	La langue de la voix source : `en`, `fr`, `es`, `pt` ou `de`
Texte d’écoute	REST uniquement, même plafond que pour les candidats Voice Design
Conservation des candidats	30 jours, levée une fois le candidat converti
Voix converties	Décomptées du quota de voix personnalisées

Erreurs

Les erreurs prennent la forme {"detail": "..."}, sauf 422, qui contient une liste d’erreurs par champ.

Statut	Où	Signification
`401`	Partout	Clé API invalide ou expirée
`404`	Enhance	Source inconnue, ou voix ou candidat d’un autre compte
`404`	Écoute	Candidat pas encore prêt, inconnu ou supprimé
`409`	Enhance	La source n’a pas de langue, la source est un candidat qui n’est pas prêt, ou la source est un clone pro. `detail` précise le cas.
`409`	Conversion	Déjà converti, pas prêt, ou quota de voix personnalisées atteint
`422`	Enhance	`n_samples` invalide, ou `src_voice` vide
`503`	Enhance	L’audio source n’a pas pu être copié, ou aucun générateur de voix n’est disponible. Réessayez.

Étapes suivantes

Voix personnalisées

Clonez un locuteur, avec une langue, afin que le clone puisse être amélioré.

Voice Design

Créez plutôt une voix à partir d’une description.

Gérer les voix

Définissez une langue sur un ancien clone, listez et supprimez des voix.

Référence API

L’endpoint enhance dans son intégralité.

Premiers pas

Synthèse vocale (TTS)

Transcription (STT)

Speech-to-Speech

Commun

Recettes temps réel

Migrations

Voix

Auto-hébergé

Ressources

Vous partez d'un enregistrement ?

Vous partez d'une description ?

Fonctionnement

1. Choisir une source

2. Améliorer

3. Écouter

4. Convertir

Accès

Démarrage rapide

Exemple complet

Sources compatibles

Conseils issus de nos tests

Cycle de vie des candidats

Limites

Erreurs

Étapes suivantes

Voix personnalisées

Voice Design

Gérer les voix

Référence API

Vous partez d'un enregistrement ?

Vous partez d'une description ?

​Fonctionnement

1. Choisir une source

2. Améliorer

3. Écouter

4. Convertir

​Accès

​Démarrage rapide

​Exemple complet

​Sources compatibles

​Conseils issus de nos tests

​Cycle de vie des candidats

​Limites

​Erreurs

​Étapes suivantes

Voix personnalisées

Voice Design

Gérer les voix

Référence API

Fonctionnement

Accès

Démarrage rapide

Exemple complet

Sources compatibles

Conseils issus de nos tests

Cycle de vie des candidats

Limites

Erreurs

Étapes suivantes