Vai alla navigazione

Modifica delle trascrizioni

Questa guida mostra come modificare le trascrizioni con istruzioni in linguaggio naturale usando l'API Speech to Text.

Guida pratica · Presuppone che tu abbia completato la guida rapida a Speech to Text .

Panoramica

La modifica delle trascrizioni è una funzionalità sperimentale e comporta un costo aggiuntivo del 30% rispetto al costo base della trascrizione, fatturato per un minimo di 10 secondi di audio per richiesta. Consulta la pagina dei prezzi dell’API per informazioni dettagliate sui prezzi.

La modifica delle trascrizioni ti consente di allegare un’istruzione in linguaggio naturale a una richiesta di trascrizione. Dopo la trascrizione dell’audio, l’istruzione viene applicata al testo trascritto e il testo modificato viene restituito insieme all’originale.

Sostituisce una fase separata di post-elaborazione nella tua pipeline. Gli usi tipici includono la normalizzazione della scrittura di date, ore o unità, l’espansione di abbreviazioni, la rimozione di contenuti non necessari, l’applicazione di uno stile o tono diverso oppure la riformattazione della trascrizione.

Ad esempio, trascrivendo un messaggio vocale con l’istruzione Write all dates in ISO 8601 format (YYYY-MM-DD) vengono restituite entrambe le versioni del testo:

{
"language_code": "eng",
"language_probability": 0.9912,
"text": "Hi, this is Jill. Your appointment is confirmed for the twelfth of July twenty twenty-six, and the follow-up is on the third of August.",
"words": [
{ "text": "Hi,", "start": 0.12, "end": 0.38, "type": "word", "logprob": 0.0 },
{ "text": " ", "start": 0.38, "end": 0.41, "type": "spacing", "logprob": 0.0 },
{ "text": "this", "start": 0.41, "end": 0.55, "type": "word", "logprob": 0.0 },
...
],
"transcription_id": "Y2ZX8AxHUzTPCIualYiE",
"edited_transcript": {
"kind": "transcript",
"text": "Hi, this is Jill. Your appointment is confirmed for 2026-07-12, and the follow-up is on 2026-08-03."
}
}

I campi text e words descrivono sempre la trascrizione originale. La versione modificata viene restituita separatamente in edited_transcript.

Integrazione della modifica delle trascrizioni

La modifica delle trascrizioni è integrata nell’API Speech to Text passando il parametro transcript_edit al metodo convert. L’istruzione può contenere fino a 2000 caratteri.

import os
from dotenv import load_dotenv
from elevenlabs.client import ElevenLabs
load_dotenv()
elevenlabs = ElevenLabs(
api_key=os.getenv("ELEVENLABS_API_KEY"),
)
with open("voicemail.mp3", "rb") as audio_file:
transcription = elevenlabs.speech_to_text.convert(
file=audio_file,
model_id="scribe_v3",
# Natural-language instruction applied to the finished transcript.
transcript_edit="Write all dates in ISO 8601 format (YYYY-MM-DD)",
)
print("Original:", transcription.text)
print("Edited:", transcription.edited_transcript)

La modifica delle trascrizioni funziona sia con richieste sincrone sia con richieste webhook. Per le richieste webhook, edited_transcript è incluso nell’oggetto transcription del payload webhook.

Scribe v3 Live e Scribe v2 Realtime supportano le stesse istruzioni per ogni trascrizione confermata. Consulta la guida alla modifica delle trascrizioni in tempo reale.

Scrivere le istruzioni

L’istruzione viene applicata all’intera trascrizione ovunque sia pertinente e ogni occorrenza corrispondente viene modificata, non solo la prima. Un’istruzione può modificare parole o frasi specifiche lasciando invariato tutto il resto, oppure può riscrivere o annotare il testo completo. Una singola istruzione può combinare diverse modifiche.

Gli esempi seguenti illustrano la gamma di istruzioni supportate:

IstruzioneEffetto
Write all dates in ISO 8601 format (YYYY-MM-DD)the twelfth of July twenty twenty-six diventa 2026-07-12
Write times in 24-hour formathalf past two in the afternoon diventa 14:30
Expand abbreviations such as "ETA" and "ASAP" on first useETA diventa estimated time of arrival (ETA)
Add the sentiment of every sentence in brackets at the end. Choose from [positive, negative, neutral]Thanks, that was really helpful. diventa Thanks, that was really helpful. [positive]
Redact every curse word with its first letter followed by stars, e.g. s***That was a damn good call. diventa That was a d*** good call.
Format the transcript as a bulleted list, one sentence per bulletRiformatta l’intera trascrizione

Alcune modifiche dispongono di parametri dedicati, più economici e prevedibili rispetto a un’istruzione di modifica. Usa il keyterm prompting per orientare il riconoscimento verso nomi e termini specifici, no_verbatim per rimuovere parole riempitive e disfluenze e numbers_format (Scribe v3) per scegliere tra cifre e parole. Riserva la modifica delle trascrizioni ai cambiamenti non coperti da queste opzioni.

Tieni presente quanto segue quando scrivi le istruzioni:

  • Indica esplicitamente l’output desiderato. Write all dates in ISO 8601 format (YYYY-MM-DD) è più affidabile di fix the dates.
  • L’istruzione può essere scritta in qualsiasi lingua, anche se quelle in inglese funzionano meglio. La trascrizione modificata rimane nella lingua dell’originale.
  • Viene eseguita solo l’istruzione. Il contenuto pronunciato nell’audio viene trattato come dati e non può modificare il modo in cui l’istruzione viene applicata.
  • Se l’istruzione non influisce su alcun contenuto della trascrizione, la trascrizione modificata è identica all’originale.

Formato della risposta

Quando transcript_edit è impostato, la risposta contiene un oggetto edited_transcript. Il relativo campo kind indica se la modifica è riuscita:

kindCampiDescrizione
transcripttextLa trascrizione modificata. Identica al text originale quando non sono state apportate modifiche.
errorerror_type (edit_failed), messageNon è stato possibile produrre la modifica. La trascrizione è riuscita e viene comunque restituito il text originale.

Il campo non è presente se non è stato richiesto alcun transcript_edit.

Modifica non riuscita
{
"text": "Hi, this is Jill. Your appointment is confirmed for ...",
"edited_transcript": {
"kind": "error",
"error_type": "edit_failed",
"message": "The transcript could not be edited. Please try again."
}
}

Comportamenti da tenere presenti:

  • La trascrizione modificata è testo normale. I timestamp a livello di parola, le etichette dei parlanti e additional_formats continuano a descrivere la trascrizione originale.
  • La modifica viene eseguita dopo il completamento della trascrizione, quindi aggiunge una latenza che aumenta con la lunghezza della trascrizione.
  • Il supplemento si applica alla durata audio della richiesta, con un minimo di 10 secondi fatturati per richiesta.

La modifica delle trascrizioni non può essere combinata con entity_detection, entity_redaction o use_multi_channel. Le richieste che li combinano vengono rifiutate con un errore di parametri non validi.

Passaggi successivi