API de Transcripción

🎙️ API de Transcripción

El flujo de transcripción tiene tres recursos:

• File (/api/files/) — el audio que subes. Una vez subido, la transcripción comienza automáticamente.
• Transcript (/api/transcripts/) — el resultado, con metadatos (idioma, duración, número de palabras) y enlaces de descarga para SRT y DOCX.
• Task (/api/tasks/) — el trabajo en segundo plano que hizo el procesamiento (útil para reintentos).

Todos los endpoints de esta sección requieren una cookie de sesión o una clave API — consulta Autenticación.

---

Visión general del flujo

1. POST /api/files/ — sube un archivo de audio dentro de un proyecto existente. La respuesta te da un file.id. La transcripción se encola automáticamente.
2. Consulta GET /api/files/{id}/ hasta que status pase a transcribed (éxito) o failed.
3. GET /api/transcripts/ o GET /api/transcripts/{id}/ — lee el registro de transcripción resultante.
4. GET /api/transcripts/{id}/download/?type=srt|docx — obtén una URL de descarga temporal para el archivo.

---

POST /api/files/

Sube un archivo de audio. Dispara automáticamente la transcripción cuando la suscripción del usuario tiene minutos disponibles.

Auth: clave API o sesión.

Content-Type: multipart/form-data

Campos del formulario:

Campo	Obligatorio	Descripción
project	sí	ID del proyecto al que pertenece el archivo. Debe ser visible para quien llama.
file	sí	El archivo de audio. Se admiten los formatos habituales (mp3, wav, m4a, flac, ogg, mp4, …).
file_type	sí	Usa audio para transcripción. Otros valores (csv, xlsx, srt, vtt) se utilizan para subidas que no son de audio.

Respuesta (201 Created):

{
  "id": 4217,
  "project": 312,
  "original_filename": "interview.wav",
  "file_type": "audio",
  "status": "transcribing",
  "duration_seconds": 1834.2,
  "uploaded_at": "2026-05-17T14:02:11Z"
}

Ejemplo:

curl -X POST https://app.uspeech.io/api/files/ \
  -H "Authorization: Api-Key abc123.longersecretstringhere" \
  -F "project=312" \
  -F "file_type=audio" \
  -F "file=@./interview.wav"

⚠️ Importante: un 201 solo significa que la subida fue aceptada y el trabajo encolado. La transcripción en sí se produce de forma asíncrona — consulta el patrón de polling más abajo.

---

GET /api/files/{id}/

Lee un archivo concreto, incluyendo su status actual.

Auth: clave API o sesión.

Respuesta (200 OK): misma forma que la respuesta del POST anterior.

Referencia de estados de archivo

Estado	Significado
uploaded	Archivo guardado, transcripción todavía no encolada (se usa para subidas que no son de audio).
transcribing	Transcripción en curso.
transcribed	Transcripción completada correctamente. Ya existe un registro Transcript.
failed	La transcripción falló. Revisa Transcript.error_reason para los detalles — consulta Códigos de estado y errores.
analyzing, completed	Se establecen cuando un análisis posterior está corriendo o ha terminado (no aplica al flujo de solo transcripción).

Patrón de polling

file_id=4217
while :; do
  status=$(curl -sS "https://app.uspeech.io/api/files/${file_id}/" \
    -H "Authorization: Api-Key $USPEECH_KEY" | jq -r .status)
  echo "$(date -u +%H:%M:%S) status=$status"
  case "$status" in
    transcribed|failed) break ;;
  esac
  sleep 10
done

💡 Consejo: la transcripción suele tardar ~1/8 de la duración del audio. Una llamada de 10 minutos se completa normalmente en menos de dos minutos.

---

GET /api/transcripts/

Lista las transcripciones visibles para quien llama (limitadas a los proyectos a los que tiene acceso).

Auth: clave API o sesión.

Respuesta (200 OK): lista paginada. Cada elemento:

{
  "id": 901,
  "uploaded_file": 4217,
  "language": "en",
  "duration_seconds": 1834.2,
  "word_count": 3120,
  "srt_path": "tenant/312/results/transcripts/interview.srt",
  "docx_path": "tenant/312/results/transcripts/interview.docx",
  "status": "completed",
  "created_at": "2026-05-17T14:05:33Z",
  "updated_at": "2026-05-17T14:08:47Z"
}

status aquí pasa por queued → processing → completed | failed.

---

GET /api/transcripts/{id}/

Obtén una sola transcripción por ID. Misma estructura de campos que la respuesta de la lista.

curl https://app.uspeech.io/api/transcripts/901/ \
  -H "Authorization: Api-Key abc123.longersecretstringhere"

Si la transcripción existe pero no es visible para quien llama, la respuesta es 404 Not Found.

---

GET /api/transcripts/{id}/download/

Devuelve una URL temporal para el artefacto de la transcripción (SRT o DOCX). La URL apunta a almacenamiento privado — úsala desde la misma máquina que recibió la respuesta.

Auth: clave API o sesión.

Parámetros de consulta:

Parámetro	Obligatorio	Descripción
type	no	srt (por defecto) o docx.

Respuesta (200 OK):

{
  "download_url": "https://…/interview.srt?X-Amz-Signature=…"
}

Si el artefacto solicitado no se ha generado (por ejemplo, la transcripción falló), la respuesta es 404 Not Found.

Ejemplo:

# Obtén la URL …
url=$(curl -sS "https://app.uspeech.io/api/transcripts/901/download/?type=srt" \
  -H "Authorization: Api-Key abc123.longersecretstringhere" | jq -r .download_url)

# … y descarga.
curl -o interview.srt "$url"

---

Reintentar una transcripción fallida

Si un archivo termina en failed, puedes reintentarlo a través de la API de Tasks.

1. Encuentra la Task de transcripción correspondiente al archivo en GET /api/tasks/?task_type=transcription (o sigue el enlace desde la aplicación web).
2. Llama a POST /api/tasks/{task_id}/retry/ para volver a encolarla.

No reintentes ante fallos terminales como audio_too_short — consulta Códigos de estado y errores para la lista completa de valores de error_reason.

---

Ejemplo de principio a fin

# 1. Subir
resp=$(curl -sS -X POST https://app.uspeech.io/api/files/ \
  -H "Authorization: Api-Key $USPEECH_KEY" \
  -F "project=312" -F "file_type=audio" \
  -F "file=@./interview.wav")
file_id=$(echo "$resp" | jq -r .id)

# 2. Polling
while :; do
  status=$(curl -sS "https://app.uspeech.io/api/files/${file_id}/" \
    -H "Authorization: Api-Key $USPEECH_KEY" | jq -r .status)
  [ "$status" = "transcribed" ] && break
  [ "$status" = "failed" ] && { echo "transcripción fallida"; exit 1; }
  sleep 10
done

# 3. Encuentra la transcripción y descarga el SRT
transcript_id=$(curl -sS "https://app.uspeech.io/api/transcripts/?uploaded_file=${file_id}" \
  -H "Authorization: Api-Key $USPEECH_KEY" | jq -r '.results[0].id')

url=$(curl -sS "https://app.uspeech.io/api/transcripts/${transcript_id}/download/?type=srt" \
  -H "Authorization: Api-Key $USPEECH_KEY" | jq -r .download_url)

curl -o interview.srt "$url"