Edição de transcrições

Visão geral

A edição de transcrições permite adicionar uma instrução em linguagem natural a uma solicitação de transcrição. Depois que o áudio é transcrito, sua instrução é aplicada à transcrição, e o texto editado é retornado junto com o original.

Isso substitui uma etapa separada de pós-processamento no seu próprio pipeline. Os usos mais comuns incluem padronizar a forma como datas, horários ou unidades são escritos, expandir abreviações, remover conteúdo desnecessário, aplicar um estilo ou tom diferente ou reformatar a transcrição.

Por exemplo, transcrever uma mensagem de voz com a instrução Write all dates in ISO 8601 format (YYYY-MM-DD) retorna as duas versões do texto:

{
  "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."
  }
}

Os campos text e words sempre descrevem a transcrição original. A versão editada é retornada separadamente em edited_transcript.

Como integrar a edição de transcrições

A edição de transcrições é integrada à API de Speech to Text ao passar o parâmetro transcript_edit para o método convert. A instrução pode ter até 2.000 caracteres.

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_v2",
        # 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)

A edição de transcrições funciona tanto com solicitações síncronas quanto com solicitações de webhook. Para solicitações de webhook, edited_transcript é incluído no objeto transcription da carga útil do webhook.

O Scribe v2 Realtime oferece suporte às mesmas instruções em cada transcrição confirmada. Consulte o guia de edição de transcrições em tempo real.

Como escrever instruções

A instrução é aplicada à transcrição inteira sempre que for relevante, e todas as ocorrências correspondentes são editadas, não apenas a primeira. Uma instrução pode alterar palavras ou frases específicas e deixar todo o resto intacto, ou pode reescrever ou anotar o texto completo. Uma única instrução pode combinar várias edições.

Os exemplos a seguir ilustram a variedade de instruções compatíveis:

Lembre-se do seguinte ao escrever instruções:

• Seja explícito sobre o resultado desejado. Write all dates in ISO 8601 format (YYYY-MM-DD) é mais confiável do que fix the dates.
• A instrução pode ser escrita em qualquer idioma, embora as instruções em inglês funcionem melhor. A transcrição editada permanece no idioma do original.
• Apenas a instrução é executada. O conteúdo falado no áudio é tratado como dados e não pode alterar a forma como a instrução é aplicada.
• Se nada na transcrição for afetado pela instrução, a transcrição editada será idêntica à original.

Formato da resposta

Quando transcript_edit é definido, a resposta contém um objeto edited_transcript. O campo kind indica se a edição foi bem-sucedida:

O campo não está presente quando nenhum transcript_edit foi solicitado.

{
  "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."
  }
}

Comportamentos importantes:

• A transcrição editada é texto simples. Os timestamps no nível das palavras, os rótulos de falante e additional_formats continuam descrevendo a transcrição original.
• A edição é executada após a conclusão da transcrição, portanto adiciona latência que aumenta conforme o tamanho da transcrição.
• A cobrança adicional é aplicada à duração do áudio da solicitação, com um mínimo de 10 segundos cobrados por solicitação.

Próximas etapas