Ir al contenido

Subir Grabaciones

El endpoint de subida de la API es el mismo que usa la aplicación web. Arrastrar un archivo a la pestaña Archivos y enviarlo con POST a /api/files/ recorren exactamente la misma ruta en el servidor, así que una grabación subida por un script se transcribe — y, en un proyecto de llamadas con análisis automático, se analiza — igual que una subida a mano. No hay nada específico de la API que activar.

Intervienen tres recursos:

  • File (/api/files/) — la grabación o transcripción que subes. Una vez subida, 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 requieren una cookie de sesión o una clave API — consulta Autenticación. Todas las peticiones necesitan el ID numérico del proyecto; Proyectos explica cómo encontrarlo.


Transcripción — cualquier proyecto:

  1. POST /api/files/ — sube la grabación. La respuesta te da un file.id, y 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/?uploaded_file={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.

Análisis automático — proyectos de llamadas:

  1. Configura el proyecto una vez — activa el análisis automático y elige los tipos de análisis. Consulta Proyectos de llamadas: análisis automático.
  2. POST /api/files/ — sube cada grabación con su agente, o envía antes un manifiesto CSV.
  3. Consulta GET /calls/api/analysis-status/?project_id=… hasta que in_progress sea false.
  4. Lee los resultados desde la API de Informes de Llamadas.

Los pasos 2–4 son los únicos que repites en el día a día.


Sube una grabación o una transcripción. Las grabaciones se transcriben automáticamente cuando la suscripción del usuario tiene minutos disponibles.

Auth: clave API o sesión.

Content-Type: multipart/form-data

Campos del formulario:

CampoObligatorioDescripción
projectsíID del proyecto al que pertenece el archivo. Debe ser visible para quien llama — consulta Proyectos para saber cómo obtener el ID.
filesíLa grabación (mp3, wav, m4a, flac, ogg, mp4, …), o una transcripción srt / vtt que ya tengas.
file_typesíaudio para grabaciones, o srt / vtt para transcripciones, que se saltan la transcripción. (csv y xlsx se usan para subidas de encuestas.)
agent_id, agent_name, agent_emailrecomendado en proyectos de llamadasQuién atendió la llamada. Con análisis automático, omitir los tres devuelve un aviso, salvo que un manifiesto ya incluya el archivo. Consulta Metadatos de Llamadas.
call_datetime, direction, ended_by, caller_number, campaignnoEl resto de los metadatos de la llamada. Solo proyectos de llamadas.

Respuesta (201 Created):

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

En los proyectos de llamadas con análisis automático activado, la respuesta también puede incluir una lista warnings.

Ejemplo:

Ventana de terminal
curl -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"

En los proyectos de llamadas, la misma petición puede llevar los metadatos de la llamada: el agente, la fecha y hora, la dirección y la campaña. Aportar metadatos es lo que permite agrupar el informe por agente, dirección, campaña y fecha. Para cargas masivas, envía un manifiesto CSV antes de las grabaciones en lugar de campos por archivo: las filas se emparejan con los archivos por nombre, incluidos los archivos subidos más tarde.

Ejemplo con metadatos de llamada:

Ventana de terminal
curl -X POST https://app.uspeech.io/api/files/ \
-H "Authorization: Api-Key $USPEECH_KEY" \
-F "project=312" \
-F "file_type=audio" \
-F "file=@./call_001.mp3" \
-F "call_datetime=2026-06-15T09:12:00Z" \
-F "agent_id=A-06" \
-F "agent_name=Ana Diaz" \
-F "direction=inbound" \
-F "campaign=Retention"

Un archivo subido con un nombre que el proyecto ya tenía se trata como la misma llamada: el nuevo registro sustituye al anterior en vez de añadir un segundo. Esto hace que los reintentos sean seguros: si una subida masiva falla a medias, repetirla no duplicará llamadas en el informe.


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.

EstadoSignificado
uploadedArchivo guardado, transcripción no iniciada — transcripciones y otras subidas que no son de audio, o audio subido cuando la suscripción no tenía minutos.
transcribingTranscripción en curso.
transcribedTranscripción completada correctamente. Ya existe un registro Transcript.
failedLa transcripción falló. El campo error_reason de esta misma respuesta indica el motivo (audio_too_short, hallucinated_transcript, private_transcription_unavailable, o vacío para otros errores) — consulta Códigos de estado y errores.
analyzing, completedSe establecen cuando un análisis posterior está corriendo o ha terminado (no aplica al flujo de solo transcripción).
Ventana de terminal
file_id=4217
while :; do
resp=$(curl -sS "https://app.uspeech.io/api/files/${file_id}/" \
-H "Authorization: Api-Key $USPEECH_KEY")
status=$(echo "$resp" | jq -r .status)
echo "$(date -u +%H:%M:%S) status=$status"
case "$status" in
transcribed) break ;;
failed)
echo "falló, motivo: $(echo "$resp" | jq -r '.error_reason // "unknown"')"
break ;;
esac
sleep 10
done

En los proyectos de llamadas, el archivo incluye además auto_analysis_error, el motivo por el que se omitió el análisis automático — por ejemplo quota_exceeded cuando la suscripción se quedó sin minutos.


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. Sí conviene reintentar en el caso de private_transcription_unavailable y de fallos con error_reason vacío.


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",
"error_reason": "",
"asr_engine": "external",
"created_at": "2026-05-17T14:05:33Z",
"updated_at": "2026-05-17T14:08:47Z"
}

status aquí pasa por queued → processing → completed | failed. Cuando status es failed, error_reason contiene la causa en formato legible por máquina (audio_too_short, hallucinated_transcript, private_transcription_unavailable) o queda vacío para otros errores — consulta Códigos de estado y errores.

asr_engine registra qué servicio de reconocimiento de voz produjo la transcripción: external (el proveedor por defecto) o private (infraestructura operada por USpeech, usada cuando el proyecto requiere transcripción privada). También se devuelve en el recurso de archivo y permanece vacío hasta que la transcripción termina.


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

Ventana de terminal
curl https://app.uspeech.io/api/transcripts/901/ \
-H "Authorization: Api-Key $USPEECH_KEY"

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


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ámetroObligatorioDescripción
typenosrt (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:

Ventana de terminal
# Obtén la URL …
url=$(curl -sS "https://app.uspeech.io/api/transcripts/901/download/?type=srt" \
-H "Authorization: Api-Key $USPEECH_KEY" | jq -r .download_url)
# … y descarga.
curl -o interview.srt "$url"

Proyectos de llamadas: análisis automático

Sección titulada «Proyectos de llamadas: análisis automático»

Cuando un proyecto de llamadas tiene el análisis automático activado, cada grabación se analiza en cuanto termina de transcribirse: no hace falta ninguna llamada adicional para «ejecutar el análisis». Las subidas funcionan exactamente como se describe más arriba; las secciones siguientes cubren la configuración del proyecto, cómo se agrupan las llamadas en lotes y cómo seguir el progreso y leer los resultados.

El análisis automático se configura en el proyecto, mediante PATCH /api/projects/{id}/. También puedes hacerlo desde el asistente de análisis de la aplicación web: los ajustes son los mismos.

Campos:

CampoTipoDescripción
auto_analysis_enabledboolInterruptor principal. El análisis solo ocurre cuando es true.
auto_analysis_typeslistaQué análisis ejecutar por llamada. Uno o varios de calls_analysis_copc, calls_analysis_no_protocol, custom_questions.
auto_analysis_questionslista de textosEl conjunto de preguntas que se responde por llamada. Obligatorio cuando custom_questions está activo.
evaluation_rubricintID de la rúbrica con la que puntuar. Obligatorio cuando calls_analysis_copc está activo.
auto_analysis_batch_sizeintEnvía un lote cuando haya esta cantidad de llamadas esperando. Por defecto 20, rango permitido 1–20.
auto_analysis_max_wait_secondsintVacía un lote parcial cuando su llamada más antigua alcanza esta antigüedad. Por defecto 300.

Validación — la petición se rechaza con 400 cuando la configuración produciría ejecuciones inservibles:

  • El audio_type del proyecto no es call — el análisis automático es solo para proyectos de llamadas.
  • auto_analysis_types está vacío.
  • Se solicita calls_analysis_copc sin una evaluation_rubric.
  • Se solicita custom_questions sin ninguna auto_analysis_questions.
  • auto_analysis_batch_size está fuera de 1–20.

Ejemplo — activar el análisis por llamada sin protocolo más dos preguntas personalizadas:

Ventana de terminal
curl -X PATCH https://app.uspeech.io/api/projects/312/ \
-H "Authorization: Api-Key $USPEECH_KEY" \
-H "Content-Type: application/json" \
-d '{
"auto_analysis_enabled": true,
"auto_analysis_types": ["calls_analysis_no_protocol", "custom_questions"],
"auto_analysis_questions": ["¿Se ofreció una devolución de llamada?", "¿Se mencionó el descuento?"],
"auto_analysis_batch_size": 20,
"auto_analysis_max_wait_seconds": 300
}'

GET /api/projects/{id}/ devuelve los mismos campos, así que puedes consultar la configuración actual antes de cambiarla.

Las llamadas no se analizan de una en una, sino en lotes pequeños, y por eso los resultados aparecen en grupos en lugar de uno a uno.

Un lote de un tipo de análisis se envía cuando se cumple cualquiera de estas condiciones:

  • Hay auto_analysis_batch_size llamadas esperando — el lote sale de inmediato.
  • La llamada más antigua en espera alcanza auto_analysis_max_wait_seconds — un barrido que se ejecuta cada 60 segundos vacía el lote parcial.

Así, un lote parcial nunca se queda atascado: con los valores por defecto, una llamada suelta subida al final del día se analiza en unos cinco minutos. Si subes en tandas grandes, baja auto_analysis_max_wait_seconds solo si necesitas resultados antes — los lotes más pequeños cuestan más por llamada.

Hay dos niveles de visibilidad:

Por archivo — GET /api/files/{id}/ informa del status de transcripción (transcribing → transcribed | failed) y de un campo auto_analysis_error que expone el motivo por el que se omitió el análisis automático de ese archivo, por ejemplo quota_exceeded cuando la suscripción se quedó sin minutos.

Por proyecto — GET /calls/api/analysis-status/?project_id={id} es el endpoint que el propio panel consulta:

{
"analysis_status": {
"calls_analysis_no_protocol": { "completed": 57, "queued": 3 }
},
"analyzed_calls": 57,
"duplicate_uploads": 2,
"in_progress": true,
"reclustering": false,
"last_analyzed_at": "2026-07-29T02:50:11.127124+00:00"
}

Consúltalo hasta que in_progress sea false y entonces descarga el informe. Consulta Informes de Llamadas para la referencia completa de campos.

Ventana de terminal
while :; do
resp=$(curl -sS "https://app.uspeech.io/calls/api/analysis-status/?project_id=312" \
-H "Authorization: Api-Key $USPEECH_KEY")
in_progress=$(echo "$resp" | jq -r .in_progress)
echo "$(date -u +%H:%M:%S) analizadas=$(echo "$resp" | jq -r .analyzed_calls) in_progress=$in_progress"
[ "$in_progress" = "false" ] && break
sleep 30
done

Cuando in_progress sea false, las llamadas analizadas están disponibles a través de la API de Informes de Llamadas:

  • GET /calls/api/report/?project_id={id} — el informe de calidad agregado
  • GET /calls/api/calls/?project_id={id} — el explorador de llamadas
  • GET /calls/api/custom-questions/?project_id={id} — respuestas por llamada a tus preguntas personalizadas
  • GET /calls/api/report/pdf/?project_id={id} — la exportación en PDF

Transcribir una grabación y descargar el SRT

Sección titulada «Transcribir una grabación y descargar el SRT»
Ventana de terminal
# 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
resp=$(curl -sS "https://app.uspeech.io/api/files/${file_id}/" \
-H "Authorization: Api-Key $USPEECH_KEY")
status=$(echo "$resp" | jq -r .status)
[ "$status" = "transcribed" ] && break
[ "$status" = "failed" ] && {
echo "transcripción fallida: $(echo "$resp" | jq -r '.error_reason // "unknown"')"
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"

Cargar un lote de llamadas en un proyecto de llamadas

Sección titulada «Cargar un lote de llamadas en un proyecto de llamadas»

Configura el proyecto, envía los metadatos de llamada, sube una carpeta de grabaciones, espera al análisis y descarga el informe.

El paso de los metadatos va primero porque el análisis automático necesita el agente de cada llamada en cuanto esta llega. Hay dos formas de aportarlos, y puedes combinarlas:

  • Por archivo al subir, como campos adicionales del formulario en POST /api/files/ — ideal cuando tu sistema ya conoce los datos de cada llamada al subirla. Es lo que muestra el ejemplo con metadatos de llamada más arriba.
  • Por proyecto, como manifiesto CSV en POST /api/projects/{id}/call-manifest/ — ideal para cargas masivas. Las filas se emparejan con los archivos por nombre, y las que aún no coinciden con ninguno se guardan y se aplican a los archivos subidos más tarde. Envíalo antes de las grabaciones, con un agente en cada fila.

El ejemplo de abajo usa el manifiesto, porque encaja con subir una carpeta entera de una vez. Consulta Metadatos de Llamadas para la referencia completa de campos, los formatos de fecha aceptados y cómo corregir los metadatos después.

#!/usr/bin/env bash
set -euo pipefail
BASE_URL="https://app.uspeech.io"
AUTH="Authorization: Api-Key ${USPEECH_KEY}"
project_id=312
# 1. Activar el análisis automático
curl -sS -X PATCH "${BASE_URL}/api/projects/${project_id}/" \
-H "$AUTH" -H "Content-Type: application/json" \
-d '{"auto_analysis_enabled": true, "auto_analysis_types": ["calls_analysis_no_protocol"]}' \
> /dev/null
# 2. Enviar primero los metadatos de llamada de todo el lote, para que cada subida encuentre su agente.
# llamadas_junio.csv: filename,call_datetime,agent_id,agent_name,direction,campaign
curl -sS -X POST "${BASE_URL}/api/projects/${project_id}/call-manifest/" \
-H "$AUTH" -F "file=@./llamadas_junio.csv" \
| jq -r '"\(.matched) asociadas, \(.unmatched | length) esperando su archivo"'
# 3. Subir todas las grabaciones de ./calls/
for path in ./calls/*.mp3; do
curl -sS -X POST "${BASE_URL}/api/files/" \
-H "$AUTH" \
-F "project=${project_id}" \
-F "file_type=audio" \
-F "file=@${path}" \
| jq -r '"subido \(.original_filename) -> \(.id)", (.warnings[]? | "aviso: \(.code): \(.detail)")'
done
# 4. Esperar a que el análisis termine
while :; do
resp=$(curl -sS "${BASE_URL}/calls/api/analysis-status/?project_id=${project_id}" -H "$AUTH")
[ "$(echo "$resp" | jq -r .in_progress)" = "false" ] && break
sleep 30
done
# 5. Descargar el informe
curl -sS "${BASE_URL}/calls/api/report/?project_id=${project_id}" -H "$AUTH" > report.json
echo "informe escrito en report.json"

SíntomaCausa probable
Un archivo se queda en uploadedLa transcripción no empezó, normalmente porque la suscripción no tenía minutos al subirlo.
Un archivo termina en failederror_reason indica el motivo. Reintenta solo si está vacío o es private_transcription_unavailable — consulta Reintentar una transcripción fallida.
El archivo llega a transcribed pero nunca se analiza nadaauto_analysis_enabled es false, o auto_analysis_types está vacío. Comprueba GET /api/projects/{id}/.
auto_analysis_error es quota_exceededLa suscripción se quedó sin minutos. El análisis se omite, no se reintenta automáticamente.
La respuesta de la subida tiene una entrada en warnings con el código call_metadata_missingEl análisis automático está activado y la subida no tiene agente, así que el informe muestra un nombre deducido. Envía agent_id, agent_name o agent_email, o sube un manifiesto que incluya el archivo.
400 en la subida con un campo de metadatos en el cuerpoEl proyecto no es de llamadas, o file_type no es audio/srt/vtt.
400 al activar el análisis automáticoFalta la rúbrica para COPC, faltan preguntas para custom_questions, o el tamaño de lote está fuera de 1–20.
El recuento de llamadas del informe es menor que los archivos subidosLos nombres reutilizados sustituyen a la llamada anterior. duplicate_uploads en la respuesta de estado del análisis los cuenta.
unanalyzed_calls en el informe es mayor que 0Esas llamadas se transcribieron con el análisis automático desactivado; activarlo no las recoge. Analízalas una vez con un análisis manual.

Consulta Códigos de estado y errores para la lista completa de códigos de respuesta.