API de transcrição de áudio e vídeo

Transcreva mídias locais, privadas ou enviadas por usuários com o fluxo de upload direto do Fast Transcriber. Seu aplicativo prepara um destino de upload, envia os bytes diretamente ao armazenamento de objetos e coloca a referência retornada do objeto na fila para iniciar a transcrição.

Por que os arquivos são enviados diretamente ao armazenamento de objetos?

Arquivos grandes de mídia não devem passar pelo corpo de uma solicitação do framework. O Fast Transcriber retorna um destino de upload pré-assinado, de uma única parte ou multipart, para que seu backend transfira os bytes diretamente. Depois, basta enviar uma pequena referência JSON ao endpoint de transcrição.

Etapa 1: prepare o destino de upload

Envie o nome do arquivo, o tipo de conteúdo e o tamanho exato em bytes. A resposta informa o provedor de armazenamento, a chave do objeto e as instruções de upload vinculadas à conta autenticada.

curl --request POST https://fast-transcriber.com/api/v1/uploads \
  --header "Authorization: Bearer $FAST_TRANSCRIBER_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "filename": "interview.mp3",
    "content_type": "audio/mpeg",
    "size": 1234567
  }'

Para um upload de uma única parte, a resposta contém a URL pré-assinada data.upload.url, os cabeçalhos de solicitação obrigatórios e os valores data.storage e data.key necessários na etapa 3.

{
  "data": {
    "content_type": "audio/mpeg",
    "key": "transcriptions/account-id/upload-id/interview.mp3",
    "storage": "r2",
    "upload": {
      "headers": { "Content-Type": "audio/mpeg" },
      "method": "PUT",
      "type": "single",
      "url": "https://presigned-storage.example/..."
    }
  }
}

Etapa 2: envie os bytes da mídia

Para um destino single, envie os bytes do arquivo à URL retornada com os cabeçalhos fornecidos. A URL abaixo substitui data.upload.url no exemplo. Não envie sua chave Bearer do Fast Transcriber à URL de armazenamento.

UPLOAD_URL="PASTE_DATA_UPLOAD_URL"
curl --request PUT "$UPLOAD_URL" \
  --header "Content-Type: audio/mpeg" \
  --upload-file "./interview.mp3"

Para um destino multipart, envie cada intervalo de bytes à URL data.upload.parts[].url correspondente, registre cada ETag da resposta e conclua o upload antes de colocá-lo na fila:

curl --request POST https://fast-transcriber.com/api/v1/uploads/multipart \
  --header "Authorization: Bearer $FAST_TRANSCRIBER_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "storage": "RETURNED_STORAGE_PROVIDER",
    "key": "RETURNED_STORAGE_KEY",
    "upload_id": "RETURNED_UPLOAD_ID",
    "parts": [
      { "part_number": 1, "etag": "RETURNED_ETAG" }
    ]
  }'

Mantenha os valores storage e key retornados sem alterações. Se a transferência de alguma parte falhar, tente essa parte novamente ou cancele o upload multipart em vez de colocar um objeto incompleto na fila.

Etapa 3: coloque o objeto enviado na fila

Substitua os valores em letras maiúsculas abaixo por data.storage e data.key da resposta do upload, em vez de fixar um provedor no código. O nome do arquivo, o tipo de conteúdo e o tamanho precisam descrever o objeto armazenado.

curl --request POST https://fast-transcriber.com/api/v1/transcriptions \
  --header "Authorization: Bearer $FAST_TRANSCRIBER_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "upload": {
      "storage": "RETURNED_STORAGE_PROVIDER",
      "key": "RETURNED_STORAGE_KEY",
      "filename": "interview.mp3",
      "content_type": "audio/mpeg",
      "size": 1234567
    },
    "speaker_diarization": false
  }'

Uma solicitação de fila bem-sucedida retorna 202 Accepted e um cabeçalho Location. Atribua esse caminho a LOCATION_PATH e consulte-o com qualquer chave Bearer ativa da mesma conta até a tarefa ser concluída ou falhar.

LOCATION_PATH="/api/v1/transcriptions/95c3fdd8-..."
curl --request GET "https://fast-transcriber.com$LOCATION_PATH" \
  --header "Authorization: Bearer $FAST_TRANSCRIBER_API_TOKEN"

Pronto para enviar esta solicitação? Crie uma chave de API ou consulte todos os endpoints na documentação da API.

Propriedade e validação da mídia

Antes de colocar a tarefa na fila, o servidor confirma que o objeto pertence à conta autenticada e verifica o tamanho armazenado e o tipo de mídia. Uma chave de upload emitida para outra conta é recusada. Assim, as referências de upload permanecem limitadas à conta que as criou.

Uploads de uma única parte ou multipart

Arquivos menores podem usar o destino de upload único retornado. Arquivos maiores podem receber instruções multipart para que uma transferência interrompida possa tentar partes individuais novamente. Conclua todas as partes obrigatórias e preserve os ETags retornados antes de chamar o endpoint de conclusão multipart.

Trabalhe com a transcrição concluída

As tarefas concluídas contêm o texto da transcrição, a duração e os segmentos com marcação de tempo disponíveis conforme os limites do plano da conta. Use o resultado para arquivos pesquisáveis, fluxos de legendagem, análise de entrevistas, notas de reunião ou processamento posterior autorizado por IA.

{
  "data": {
    "id": "95c3fdd8-...",
    "filename": "video-source.mp4",
    "status": "completed",
    "duration_seconds": 84,
    "text": "Texto completo da transcrição...",
    "segments": [
      { "start": 0, "end": 3.8, "text": "Primeiro segmento..." }
    ]
  }
}

Quando enviar um arquivo em vez de uma URL?

A mídia é local, enviada por um usuário ou gerada dentro do seu aplicativo.
A fonte é privada, mas seu aplicativo tem autorização para recuperá-la e processá-la.
Você prefere uma transferência estável do objeto em vez de depender de um link público de terceiros.
A URL original exige uma sessão, cookie ou token de acesso que nunca deve ser enviado ao Fast Transcriber.

Perguntas frequentes

A mídia passa pelo corpo de uma solicitação do Next.js?

Não. O upload vai diretamente ao armazenamento de objetos usando o destino retornado pelo endpoint de uploads.

O que o servidor valida antes de colocar a tarefa na fila?

Ele valida a propriedade do objeto, o tamanho armazenado e o tipo de mídia. Referências pertencentes a outra conta são recusadas.

Gravações enviadas podem usar diarização de locutores?

Sim. Defina speaker_diarization como true. A diarização exige o plano Pro.

Quais limites se aplicam aos uploads pela API?

As tarefas da API usam os limites normais do plano da conta autenticada, inclusive as regras de tamanho de arquivo e uso diário.