API de transcripción de audio y video

Transcribe contenido multimedia local, privado o enviado por usuarios mediante el flujo de carga directa de Fast Transcriber. Tu aplicación prepara un destino de carga, envía los bytes directamente al almacenamiento de objetos y pone en la cola la referencia del objeto devuelta para su transcripción.

Por qué las cargas van directamente al almacenamiento de objetos

Los archivos multimedia grandes no deben pasar por el cuerpo de una solicitud del framework. Fast Transcriber devuelve un destino de carga prefirmado, de una sola parte o multipart, para que tu backend transfiera los bytes directamente y después envíe una pequeña referencia JSON al endpoint de transcripción.

Paso 1: prepara el destino de carga

Envía el nombre exacto del archivo, el tipo de contenido y el tamaño en bytes. La respuesta identifica el proveedor de almacenamiento, la clave del objeto y las instrucciones de carga asociadas a la cuenta 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 una carga de una sola parte, la respuesta incluye una URL prefirmada en data.upload.url, los encabezados necesarios de la solicitud y los valores data.storage y data.key que se usan en el paso 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/..."
    }
  }
}

Paso 2: carga los bytes del contenido

Para un destino single, envía los bytes del archivo a la URL devuelta con los encabezados proporcionados. La URL siguiente es un marcador para data.upload.url; no envíes tu clave Bearer de Fast Transcriber a la URL de almacenamiento.

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

Para un destino multipart, envía cada intervalo de bytes a su URL data.upload.parts[].url correspondiente, registra cada ETag de la respuesta y completa la carga antes de ponerla en la cola:

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" }
    ]
  }'

Mantén sin cambios los valores devueltos de storage y key. Si falla la transferencia de alguna parte, vuelve a intentar esa parte o cancela la carga multipart en lugar de poner un objeto incompleto en la cola.

Paso 3: pon el objeto cargado en la cola

Sustituye los marcadores en mayúsculas siguientes por data.storage y data.key de la respuesta de carga, en lugar de fijar un proveedor en el código. El nombre del archivo, el tipo de contenido y el tamaño deben describir el objeto almacenado.

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
  }'

Una solicitud correcta para poner la tarea en la cola devuelve 202 Accepted y un encabezado Location. Asigna esa ruta a LOCATION_PATH y consúltala con cualquier clave Bearer activa de la misma cuenta hasta que la tarea termine o falle.

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

¿Todo listo para ejecutar esta solicitud? Crea una clave de API o consulta todos los endpoints en la documentación de la API.

Propiedad y validación del contenido

Antes de poner la tarea en la cola, el servidor comprueba que el objeto pertenece a la cuenta autenticada y verifica su tamaño almacenado y tipo de contenido. Se rechazan las claves de carga emitidas para otra cuenta. De esta forma, las referencias de carga quedan limitadas a la cuenta que las creó.

Cargas de una sola parte y multipart

Los archivos más pequeños pueden usar el destino de carga de una sola parte devuelto. Los archivos más grandes pueden recibir instrucciones multipart para que una transferencia interrumpida pueda reintentar partes individuales. Completa todas las partes requeridas y conserva los ETags devueltos antes de llamar al endpoint de finalización multipart.

Trabaja con la transcripción completada

Las tareas completadas contienen el texto de la transcripción, la duración y los segmentos con marcas de tiempo disponibles según los límites del plan de la cuenta. Usa el resultado para archivos que se puedan buscar, flujos de subtítulos, análisis de entrevistas, notas de reuniones o procesamiento posterior autorizado con IA.

{
  "data": {
    "id": "95c3fdd8-...",
    "filename": "video-source.mp4",
    "status": "completed",
    "duration_seconds": 84,
    "text": "Texto completo de la transcripción...",
    "segments": [
      { "start": 0, "end": 3.8, "text": "Primer segmento..." }
    ]
  }
}

Cuándo cargar un archivo en lugar de enviar una URL

El contenido es local, lo envió un usuario o se generó dentro de tu aplicación.
La fuente es privada, pero tu aplicación tiene autorización para obtenerla y procesarla.
Prefieres una transferencia estable del objeto en lugar de depender de un enlace público de terceros.
La URL original requiere una sesión, cookie o token de acceso que nunca se debe enviar a Fast Transcriber.

Preguntas frecuentes

¿El contenido pasa por el cuerpo de una solicitud de Next.js?

No. La carga va directamente al almacenamiento de objetos mediante el destino devuelto por el endpoint de cargas.

¿Qué valida el servidor antes de poner la tarea en la cola?

Valida la propiedad del objeto, el tamaño almacenado y el tipo de contenido. Se rechazan las referencias que pertenecen a otra cuenta.

¿Las grabaciones cargadas pueden usar diarización de hablantes?

Sí. Establece speaker_diarization en true. La diarización de hablantes requiere Pro.

¿Qué límites se aplican a las cargas por la API?

Las tareas de la API usan los límites normales del plan de la cuenta autenticada, incluidas las reglas de tamaño de archivo y uso diario.