Batch e reprocessamento

Pergunta: "como reprocesso o áudio final e leio o resultado tipado?"

Batch é uma capability estrutural: não é um membro opcional de TranscriptionSession. Depois de stop(), descubra-a com isReprocessCapable() e então chame reprocessAudio().

import {
  connectTranscription,
  isReprocessCapable,
  type TranscriptResult,
} from '@sofya-sdk/transcription';

const session = await connectTranscription({
  provider: 'sofya_as_service',
  endpoint: '<wss-url>',
  overrides: { languages: { transcription: 'pt-BR' }, externalId: '<uuid>' },
});

await session.stop();
if (!isReprocessCapable(session)) throw new Error('reprocessamento indisponível');

const result: TranscriptResult = await session.reprocessAudio();
for (const item of result.data.words) {
  console.log(item.word, item.start, item.end, item.probability);
}

O sucesso contém apenas data.text, data.language e data.words[]. Cada palavra tem word, start, end e probability. start e end são segundos em ponto flutuante, não milissegundos. word pode conter espaço inicial; preserve-o se precisar reconstruir o texto. Não presuma segments, duration, id, model ou diarização: eles não fazem parte do contrato público.

Idiomas e endpoint

O request envia transcription_language=portuguese para languages.transcription: 'pt-BR'. Já data.language retorna código ISO-639-1, como pt. São vocabulários diferentes; não os modele como um único enum. O POST é síncrono, multipart no campo file, e produz a resposta final. O endpoint observado é /api/transcriber, sem versão no path ou header de versão. Logo, a estabilidade é um compromisso social do time dono, não uma garantia técnica de schema versionado.

Erros e autenticação

Para resposta não-2xx, o upload falha de forma opaca (FinalUploadError internamente, que a capability converte em BatchReprocessError): há status quando ele foi lido, mas o corpo não é parseado. Isso é uma decisão explícita — não existe contrato de erro do backend — e não uma omissão documental.

É conhecido que a chamada observada não trazia Authorization. Não há evidência de que /api/transcriber aceite um Bearer injetado; portanto esta documentação não promete esse modo de autenticação. Confirme a autenticação do seu ambiente com o time dono antes de usar batch em produção.