For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Transcreve um arquivo de áudio ou vídeo. Se webhook estiver definido como true, a solicitação será processada de forma assíncrona e os resultados serão enviados aos webhooks configurados. Quando use_multi_channel for true e o áudio fornecido tiver vários canais, será retornado um objeto 'transcripts' com transcrições separadas para cada canal; defina multichannel_output_style='combined' para receber uma única transcrição com todos os canais mesclados e ordenados por tempo. Caso contrário, retorna uma única transcrição. O parâmetro opcional webhook_metadata permite anexar dados personalizados que serão incluídos nas respostas de webhook para correlação e rastreamento de solicitações.
Cabeçalhos
xi-api-keystringOpcional
Parâmetros de consulta
tokenstring or nullOpcional
Um token de autenticação de uso único criado por POST /v1/single-use-token/batch_scribe. Este token só pode ser usado uma vez e expira após 15 minutos. É uma alternativa à autenticação por chave de API ou token bearer para clientes de frontend.
enable_loggingbooleanOpcionalPadrão é true
Quando enable_logging for definido como false, o modo de retenção zero será usado para a solicitação. Isso significa que os recursos de armazenamento de logs e transcrições não estarão disponíveis para esta solicitação. O modo de retenção zero só pode ser usado por clientes empresariais.
Solicitação
This endpoint expects a multipart form containing an optional file.
model_idstringObrigatório
O ID do modelo a usar para a transcrição.
filefileOpcional
O arquivo a ser transcrito (duração mínima de áudio de 100 ms). Todos os principais formatos de áudio e vídeo são compatíveis. Exatamente um dos parâmetros file ou cloud_storage_url deve ser fornecido. O tamanho do arquivo deve ser inferior a 5,0 GB.
language_codestring or nullOpcional
Um language_code ISO-639-1 ou ISO-639-3 correspondente ao idioma do arquivo de áudio. Às vezes, pode melhorar o desempenho da transcrição se for conhecido de antemão. O padrão é null; nesse caso, o idioma é previsto automaticamente.
transcript_editstring or nullOpcional
Instrução em linguagem natural aplicada à transcrição final (máximo de 2.000 caracteres). O texto editado é retornado em 'edited_transcript' junto à transcrição original. Não pode ser combinado com entity_detection, entity_redaction ou use_multi_channel. O uso deste parâmetro gera uma cobrança adicional de 30% sobre o custo base da transcrição, faturada para pelo menos 10 segundos de áudio.
tag_audio_eventsbooleanOpcionalPadrão é true
Se deve marcar eventos de áudio como (risos), (passos) etc. na transcrição.
num_speakersinteger or nullOpcional1-32
O número máximo de locutores falando no arquivo enviado. Pode ajudar a prever quem fala em cada momento. O número máximo de locutores que pode ser previsto é 32. O padrão é null; nesse caso, o número de locutores é definido como o valor máximo compatível com o modelo.
timestamps_granularityenumOpcionalPadrão é word
A granularidade dos carimbos de tempo na transcrição. ‘word’ fornece carimbos de tempo por palavra, e ‘character’ fornece carimbos de tempo por caractere em cada palavra.
Valores permitidos:
diarizebooleanOpcionalPadrão é false
Indica se deve anotar qual locutor está falando no momento no arquivo enviado.
diarization_thresholddouble or nullOpcional0.1-0.4
Limite de diarização a ser aplicado durante a diarização de falantes. Um valor maior reduz a chance de um falante ser diarizado como dois falantes diferentes, mas aumenta a chance de dois falantes diferentes serem diarizados como um único falante (menos falantes totais previstos). Um valor baixo aumenta a chance de um falante ser diarizado como dois falantes diferentes, mas reduz a chance de dois falantes diferentes serem diarizados como um único falante (mais falantes totais previstos). Só pode ser definido quando diarize=True e num_speakers=None. O padrão é None; nesse caso, escolheremos um limite com base no model_id (geralmente 0.22).
additional_formatslist of objectsOpcional
Uma lista de formatos adicionais para exportar a transcrição.
file_formatenumOpcionalPadrão é other
The format of input audio. Options are ‘pcm_s16le_16’ or ‘other’ For pcm_s16le_16, the input audio must be 16-bit PCM at a 16kHz sample rate, single channel (mono), and little-endian byte order. Latency will be lower than with passing an encoded waveform.
Valores permitidos:
cloud_storage_urlstring or nullOpcionalDeprecated
[Obsoleto] Este parâmetro está obsoleto e será removido no futuro. Use 'source_url'. A URL HTTPS do arquivo a ser transcrito. Exatamente um dos parâmetros file ou cloud_storage_url deve ser fornecido. O arquivo precisa estar acessível via HTTPS e ter menos de 2 GB. Qualquer URL HTTPS válida é aceita, incluindo URLs de provedores de armazenamento em nuvem (AWS S3, Google Cloud Storage, Cloudflare R2 etc.), CDNs ou qualquer outra fonte HTTPS. As URLs podem ser pré-assinadas ou incluir tokens de autenticação nos parâmetros de consulta.
source_urlstring or nullOpcional
A URL de um arquivo de áudio ou vídeo a ser transcrito. Compatível com arquivos de vídeo ou áudio hospedados, URLs de vídeos do YouTube, URLs de vídeos do TikTok e outros serviços de hospedagem de vídeo.
webhookbooleanOpcionalPadrão é false
Se deve enviar o resultado da transcrição para os webhooks de Speech to Text configurados. Se definido, a solicitação retornará antecipadamente sem a transcrição, que será entregue posteriormente via webhook.
webhook_idstring or nullOpcional
ID específico e opcional do webhook para o qual enviar o resultado da transcrição. Válido somente quando webhook estiver definido como true. Se não for informado, a transcrição será enviada a todos os webhooks de Speech to Text configurados.
temperaturedouble or nullOpcional0-2
Controla a aleatoriedade da saída da transcrição. Aceita valores entre 0.0 e 2.0, em que valores mais altos resultam em resultados mais diversos e menos determinísticos. Se omitido, usaremos uma temperatura baseada no modelo selecionado, que geralmente é 0.
seedinteger or nullOpcional0-2147483647
Se especificado, nosso sistema fará o possível para realizar a amostragem de forma determinística, de modo que solicitações repetidas com a mesma semente e os mesmos parâmetros retornem o mesmo resultado. O determinismo não é garantido. Deve ser um número inteiro entre 0 e 2147483647.
use_multi_channelbooleanOpcionalPadrão é false
Se o arquivo de áudio contém vários canais, em que cada canal contém um único falante. Quando ativado, cada canal é transcrito de forma independente. Por padrão, é retornada uma transcrição separada por canal; defina multichannel_output_style='combined' para receber uma única transcrição com todos os canais mesclados e ordenados por tempo. Cada palavra na resposta inclui um campo 'channel_index' que indica em qual canal ela foi falada. Há suporte para no máximo 5 canais. Cada canal é cobrado de forma independente pela duração total do áudio, portanto o custo aumenta linearmente com o número de canais.
multichannel_output_styleenumOpcionalPadrão é separate
Controla o formato da resposta quando use_multi_channel está ativado. 'separate' (padrão) retorna uma transcrição por canal em 'transcripts'. 'combined' une todos os canais em uma única transcrição, cujas palavras são ordenadas pelo horário de início e incluem um 'channel_index', correspondendo ao formato de resposta de canal único. 'combined' exige timestamps (timestamps_granularity não pode ser 'none') e não oferece suporte à detecção ou redação de entidades.
Valores permitidos:
webhook_metadatastring or map from strings to any or nullOpcional
Metadados opcionais para incluir na resposta do webhook. Deve ser uma string JSON que represente um objeto com profundidade máxima de 2 níveis e tamanho máximo de 16 KB. Útil para rastrear IDs internos, referências de tarefas ou outras informações contextuais.
entity_detectionstring or list of strings or nullOpcional
Detecta entidades na transcrição. Pode ser 'all' para detectar todas as entidades, uma única string de tipo ou categoria de entidade, ou uma lista de tipos/categorias de entidades. As categorias incluem 'pii', 'phi', 'pci', 'other' e 'offensive_language'. Quando ativado, as entidades detectadas serão retornadas no campo 'entities', com texto, tipo e posições de caracteres. O uso deste parâmetro gera uma cobrança adicional de 30% sobre o custo base da transcrição.
no_verbatimbooleanOpcionalPadrão é false
Se for true, a transcrição não terá palavras de preenchimento, falsos começos nem sons não verbais. Compatível somente com o modelo scribe_v2.
use_speaker_librarybooleanOpcionalPadrão é false
Se deve usar a biblioteca de locutores para identificar locutores conhecidos durante a diarização. Quando ativado e diarize for true, os locutores detectados serão comparados aos locutores registrados na biblioteca de locutores do workspace.
detect_speaker_rolesbooleanOpcionalPadrão é false
Indica se deve detectar os papéis dos locutores (agente ou cliente). Requer diarize=true. Não pode ser usado com use_multi_channel=true. Quando ativado, os valores de speaker_id serão 'agent' e 'customer' em vez de 'speaker_0', 'speaker_1' etc. O uso gera uma cobrança adicional de 10% sobre o custo base de transcrição.
entity_redactionstring or list of strings or nullOpcional
Oculte entidades do texto da transcrição. Aceita o mesmo formato de entity_detection: 'all', uma categoria ('pii', 'phi') ou tipos específicos de entidade. Deve ser um subconjunto de entity_detection. Quando a ocultação está ativada, o campo entities não é retornado. O uso deste parâmetro gera uma cobrança adicional de 30% sobre o custo base da transcrição.
entity_redaction_modestringOpcionalPadrão é enumerated_entity_type
Como formatar entidades ocultadas. ‘redacted’ substitui por {REDACTED}, ‘entity_type’ substitui por {ENTITY_TYPE} e ‘enumerated_entity_type’ substitui por {ENTITY_TYPE_N}, em que N enumera cada ocorrência. Usado apenas quando entity_redaction está definido.
keytermslist of stringsOpcionalPadrão é []
Uma lista de termos-chave para direcionar a transcrição. Os termos-chave são palavras ou frases que você quer que o modelo reconheça com mais precisão. A quantidade de termos-chave não pode exceder 1000. Cada termo-chave deve ter menos de 50 caracteres. Os termos-chave podem conter no máximo 5 palavras (após a normalização). Por exemplo, ["hello", "world", "technical term"]. Os seguintes caracteres não são compatíveis: `<`, `>`, `{`, `}`, `[`, `]`, `\`. O uso desse parâmetro gera uma cobrança adicional de 20% sobre o custo base da transcrição. Quando são fornecidos mais de 100 termos-chave, aplica-se uma duração mínima faturável de 20 segundos por solicitação.
Resposta
Resultado da transcrição síncrona
SpeechToTextChunkResponseModelobject
Detalhes da transcrição por trecho, com informações de tempo.
OR
MultichannelSpeechToTextResponseModelobject
Modelo de resposta para transcrição de voz para texto multicanal.
Transcreve um arquivo de áudio ou vídeo. Se webhook estiver definido como true, a solicitação será processada de forma assíncrona e os resultados serão enviados aos webhooks configurados. Quando use_multi_channel for true e o áudio fornecido tiver vários canais, será retornado um objeto ‘transcripts’ com transcrições separadas para cada canal; defina multichannel_output_style=‘combined’ para receber uma única transcrição com todos os canais mesclados e ordenados por tempo. Caso contrário, retorna uma única transcrição. O parâmetro opcional webhook_metadata permite anexar dados personalizados que serão incluídos nas respostas de webhook para correlação e rastreamento de solicitações.
Instrução em linguagem natural aplicada à transcrição final (máximo de 2.000 caracteres). O texto editado é retornado em ‘edited_transcript’ junto à transcrição original. Não pode ser combinado com entity_detection, entity_redaction ou use_multi_channel. O uso deste parâmetro gera uma cobrança adicional de 30% sobre o custo base da transcrição, faturada para pelo menos 10 segundos de áudio.
Limite de diarização a ser aplicado durante a diarização de falantes. Um valor maior reduz a chance de um falante ser diarizado como dois falantes diferentes, mas aumenta a chance de dois falantes diferentes serem diarizados como um único falante (menos falantes totais previstos). Um valor baixo aumenta a chance de um falante ser diarizado como dois falantes diferentes, mas reduz a chance de dois falantes diferentes serem diarizados como um único falante (mais falantes totais previstos). Só pode ser definido quando diarize=True e num_speakers=None. O padrão é None; nesse caso, escolheremos um limite com base no model_id (geralmente 0.22).
[Obsoleto] Este parâmetro está obsoleto e será removido no futuro. Use ‘source_url’. A URL HTTPS do arquivo a ser transcrito. Exatamente um dos parâmetros file ou cloud_storage_url deve ser fornecido. O arquivo precisa estar acessível via HTTPS e ter menos de 2 GB. Qualquer URL HTTPS válida é aceita, incluindo URLs de provedores de armazenamento em nuvem (AWS S3, Google Cloud Storage, Cloudflare R2 etc.), CDNs ou qualquer outra fonte HTTPS. As URLs podem ser pré-assinadas ou incluir tokens de autenticação nos parâmetros de consulta.
Se o arquivo de áudio contém vários canais, em que cada canal contém um único falante. Quando ativado, cada canal é transcrito de forma independente. Por padrão, é retornada uma transcrição separada por canal; defina multichannel_output_style=‘combined’ para receber uma única transcrição com todos os canais mesclados e ordenados por tempo. Cada palavra na resposta inclui um campo ‘channel_index’ que indica em qual canal ela foi falada. Há suporte para no máximo 5 canais. Cada canal é cobrado de forma independente pela duração total do áudio, portanto o custo aumenta linearmente com o número de canais.
Controla o formato da resposta quando use_multi_channel está ativado. ‘separate’ (padrão) retorna uma transcrição por canal em ‘transcripts’. ‘combined’ une todos os canais em uma única transcrição, cujas palavras são ordenadas pelo horário de início e incluem um ‘channel_index’, correspondendo ao formato de resposta de canal único. ‘combined’ exige timestamps (timestamps_granularity não pode ser ‘none’) e não oferece suporte à detecção ou redação de entidades.
Detecta entidades na transcrição. Pode ser ‘all’ para detectar todas as entidades, uma única string de tipo ou categoria de entidade, ou uma lista de tipos/categorias de entidades. As categorias incluem ‘pii’, ‘phi’, ‘pci’, ‘other’ e ‘offensive_language’. Quando ativado, as entidades detectadas serão retornadas no campo ‘entities’, com texto, tipo e posições de caracteres. O uso deste parâmetro gera uma cobrança adicional de 30% sobre o custo base da transcrição.
Indica se deve detectar os papéis dos locutores (agente ou cliente). Requer diarize=true. Não pode ser usado com use_multi_channel=true. Quando ativado, os valores de speaker_id serão ‘agent’ e ‘customer’ em vez de ‘speaker_0’, ‘speaker_1’ etc. O uso gera uma cobrança adicional de 10% sobre o custo base de transcrição.
Oculte entidades do texto da transcrição. Aceita o mesmo formato de entity_detection: ‘all’, uma categoria (‘pii’, ‘phi’) ou tipos específicos de entidade. Deve ser um subconjunto de entity_detection. Quando a ocultação está ativada, o campo entities não é retornado. O uso deste parâmetro gera uma cobrança adicional de 30% sobre o custo base da transcrição.
Uma lista de termos-chave para direcionar a transcrição. Os termos-chave são palavras ou frases que você quer que o modelo reconheça com mais precisão. A quantidade de termos-chave não pode exceder 1000. Cada termo-chave deve ter menos de 50 caracteres. Os termos-chave podem conter no máximo 5 palavras (após a normalização). Por exemplo, [“hello”, “world”, “technical term”]. Os seguintes caracteres não são compatíveis: <, >, {, }, [, ], \. O uso desse parâmetro gera uma cobrança adicional de 20% sobre o custo base da transcrição. Quando são fornecidos mais de 100 termos-chave, aplica-se uma duração mínima faturável de 20 segundos por solicitação.
