Spring til hovedindhold
Dansk— Vælg et sprog
Menu

Voices-API'en

Lektion 4 af 14 Opdateret 3. november 2026 Udvikler
På denne side
  1. Endepunktet /v1/voices
  2. Oprettelse af en stemme
  3. Listning, hentning og modificering
  4. Sletning og hentning af prøven
  5. Organisering af dit stemmekatalog
  6. Vigtige pointer

Kurset opdateret 3. november 2026 til Voxtral TTS 3, baseret på guiden Migrate from Voxtral 2 og Mistral-siderne om Text to Speech: voxtral-mini-tts-2603, deprecateret 31. oktober 2026 og fjernet 30. april 2027, erstattes i eksemplerne af voxtral-mini-tts-3-0. Foruddefinerede Voxtral 2-stemmer (gb_jane_neutral…) accepteres stadig; Voxtral 3 tilføjer [emotion=…]- og [pace=…]-tags i teksten, indstillingen expressiveness, brugerdefineret udtale (phoneme_hints) og 35 sprog. Mistral anbefaler at genmåle ventetiden efter migrationen. Kilder: Migrate from Voxtral 2 · Speech generation.

Endepunktet /v1/voices

Mistrals Voices-API er dit udgangspunkt for håndtering af brugerdefinerede stemmer. Det eksponerer et komplet sæt CRUD-operationer – Create, Read, Update, Delete – så du kan oprette, liste, hente, modificere og slette stemmer. Hvis du har arbejdet med en standard REST-API før, er du på bekendt grund: Her handler det ikke direkte om lydbehandling, men udelukkende om at administrere et katalog over objekter.

Alle stemmer, der oprettes via API’en, modtager en unik identifikator, voice_id, som du senere bruger til at generere tale. Husk dette: Stemmer er persistente. Når de først er oprettet, forbliver de tilgængelige på din konto, indtil de eksplicit slettes. Du behøver ikke at gensende lydprøven for hver generering, så dine applikationer skal kun gemme en streng i deres konfiguration.

Oprettelse af en stemme

Oprettelsen sker via et POST-kald til endepunktet /v1/voices. Du angiver en lydprøve kodet i base64 sammen med beskrivende metadata:

import base64
from pathlib import Path
from mistralai.client import Mistral

client = Mistral(api_key="your-api-key")

# Encode the audio sample to base64
sample_audio_b64 = base64.b64encode(
    Path("sample.mp3").read_bytes()
).decode()

# Create the voice
voice = client.audio.voices.create(
    name="my-pro-voice",
    sample_audio=sample_audio_b64,
    sample_filename="sample.mp3",
    languages=["fr", "en"],
    gender="female",
    age=35,
    tags=["professional", "podcast"]
)

print(f"Voice created: {voice.id}")

Brug af base64 er nødvendig, fordi anmodningen er et JSON-dokument, og JSON ikke kan bære binære data. API’en returnerer et objekt, der indeholder den voice_id, som du skal gemme til alle genereringsanmodninger. I eksemplet ovenfor udskriver vi den, men i produktion bør du skrive den til din konfiguration eller database.

Listning, hentning og modificering

For at hente en liste over alle dine stemmer understøtter metoden list() paginering:

# Get the first 10 voices
voices = client.audio.voices.list(limit=10, offset=0)

for v in voices.items:
    print(f"{v.id} — {v.name} ({v.gender}, {v.languages})")

Pagineringen er baseret på offset: Du angiver antallet af elementer med limit og startpunktet med offset. For også at gennemse Mistrals foruddefinerede stemmer (Marie på fransk, fr_marie_neutral, Jane på britisk engelsk osv.), lister voices.search begge familier, der skelnes af feltet type: preset eller custom. For at hente den anden side med ti stemmer kalder du metoden med offset=10. Denne mekanisme bliver nyttig, så snart et bureau administrerer stemmer for dusinvis af kunder.

Når du har brug for detaljer om en specifik stemme, returnerer get() dens fulde metadata:

voice = client.audio.voices.get(voice_id="your-voice-id")

print(f"Name: {voice.name}")
print(f"Gender: {voice.gender}")
print(f"Languages: {voice.languages}")
print(f"Tags: {voice.tags}")

Gør det til en vane at kalde denne operation før en større genereringskørsel. Det verificerer, at den voice_id, der er hardcodet i din applikation, peger på den forventede stemme og ikke en fra et gammelt projekt.

Du kan modificere metadataene for en eksisterende stemme uden at røre ved lydprøven:

updated_voice = client.audio.voices.update(
    voice_id="your-voice-id",
    name="my-pro-voice-v2",
    languages=["fr", "en", "es"],
    tags=["professional", "podcast", "multilingual"]
)

print(f"Voice updated: {updated_voice.name}")

Felter, der kan modificeres, inkluderer name, languages, gender, age, tags og description. Den oprindelige lydprøve kan dog ikke ændres. Hvis du vil ændre lyden, skal du oprette en ny stemme. I praksis kan en dårligt optaget stemme ikke repareres – den skal erstattes, og du bliver nødt til at udbrede den nye voice_id på tværs af dine applikationer.

Sletning og hentning af prøven

Sletning er permanent og irreversibel:

client.audio.voices.delete(voice_id="your-voice-id")
print("Voice deleted")

Efter sletning vil enhver genereringsanmodning, der bruger denne voice_id, fejle. Et klassisk mareridtscenarie: En udvikler rydder op i teststemmer, sletter ved et uheld en, der faktisk driver support-IVR’en, og incidenten bryder ud næste morgen ved det første indkommende opkald. Sørg altid for, at dine applikationer er opdateret, før du sletter en stemme i produktion.

Du kan også downloade den originale lyd, der blev brugt til at oprette en stemme:

response = client.audio.voices.get_sample_audio(voice_id="your-voice-id")
Path("retrieved_sample.mp3").write_bytes(response.content)

Denne funktion hjælper dig med at arkivere dine prøver eller verificere kvaliteten af kildelyden, hvis en stemme skuffer dig. Ved at lytte til originalen opdager du ofte, at fejlen, der blev hørt under genereringen, allerede var til stede i optagelsen.

Organisering af dit stemmekatalog

Rydkelig styring koster lidt og forhindrer betydelig forvirring. Navngiv dine stemmer tydeligt med et projektpræfiks efter mønstre som podcast-narrator eller app-assistant-fr i stedet for voice1 og test-final-2. Brug tags til at kategorisere efter anvendelsestilfælde, projekt eller kunde, så listerne forbliver håndterbare, efterhånden som de vokser. Dokumentér voice_id’er i din applikationskonfiguration, aldrig i en isoleret fil på en workstation. Og slet aldrig en produktionsstemme uden først at verificere, at den ikke længere refereres til nogen steder.

Vigtige pointer

  • Voices-API’en eksponerer fuld CRUD-funktionalitet: opret, list, hent, opdater, slet
  • Hver stemme modtager en unik voice_id, der bruges i genereringsanmodninger
  • Offset-baseret paginering lader dig administrere et stort antal stemmer
  • Sletning er permanent – alle anmodninger, der bruger denne voice_id, vil fejle
  • Den originale lydprøve kan hentes via sample-endepunktet