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.
El flujo de un vistazo
Sección titulada «El flujo de un vistazo»Transcripción — cualquier proyecto:
POST /api/files/— sube la grabación. La respuesta te da unfile.id, y la transcripción se encola automáticamente.- Consulta
GET /api/files/{id}/hasta questatuspase atranscribed(éxito) ofailed. GET /api/transcripts/?uploaded_file={id}— lee el registro de transcripción resultante.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:
- 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.
POST /api/files/— sube cada grabación con su agente, o envía antes un manifiesto CSV.- Consulta
GET /calls/api/analysis-status/?project_id=…hasta quein_progressseafalse. - 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.
POST /api/files/
Sección titulada «POST /api/files/»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:
| Campo | Obligatorio | Descripción |
|---|---|---|
project | sí | ID del proyecto al que pertenece el archivo. Debe ser visible para quien llama — consulta Proyectos para saber cómo obtener el ID. |
file | sí | La grabación (mp3, wav, m4a, flac, ogg, mp4, …), o una transcripción srt / vtt que ya tengas. |
file_type | sí | 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_email | recomendado en proyectos de llamadas | Quié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, campaign | no | El 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:
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"import osimport requests
BASE_URL = "https://app.uspeech.io"HEADERS = {"Authorization": f"Api-Key {os.environ['USPEECH_KEY']}"}
with open("interview.wav", "rb") as fh: response = requests.post( f"{BASE_URL}/api/files/", headers=HEADERS, data={"project": 312, "file_type": "audio"}, files={"file": ("interview.wav", fh, "audio/wav")}, timeout=300, )response.raise_for_status()file_id = response.json()["id"]import { openAsBlob } from 'node:fs';
const BASE_URL = 'https://app.uspeech.io';const HEADERS = { Authorization: `Api-Key ${process.env.USPEECH_KEY}` };
const form = new FormData();form.set('project', '312');form.set('file_type', 'audio');form.set('file', await openAsBlob('./interview.wav'), 'interview.wav');
const response = await fetch(`${BASE_URL}/api/files/`, { method: 'POST', headers: HEADERS, // no fijes Content-Type — FormData define el boundary body: form,});if (!response.ok) throw new Error(await response.text());const fileId = (await response.json()).id;Enviar metadatos de llamada
Sección titulada «Enviar metadatos de llamada»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:
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"with open("call_001.mp3", "rb") as fh: response = requests.post( f"{BASE_URL}/api/files/", headers=HEADERS, data={ "project": project_id, "file_type": "audio", "call_datetime": "2026-06-15T09:12:00Z", "agent_id": "A-06", "agent_name": "Ana Diaz", "direction": "inbound", "campaign": "Retention", }, files={"file": ("call_001.mp3", fh, "audio/mpeg")}, timeout=300, )response.raise_for_status()file_id = response.json()["id"]print("subido", file_id)import { openAsBlob } from 'node:fs';
const form = new FormData();form.set('project', String(projectId));form.set('file_type', 'audio');form.set('call_datetime', '2026-06-15T09:12:00Z');form.set('agent_id', 'A-06');form.set('agent_name', 'Ana Diaz');form.set('direction', 'inbound');form.set('campaign', 'Retention');form.set('file', await openAsBlob('./call_001.mp3'), 'call_001.mp3');
const response = await fetch(`${BASE_URL}/api/files/`, { method: 'POST', headers: HEADERS, // no fijes Content-Type — FormData define el boundary body: form,});if (!response.ok) throw new Error(await response.text());const fileId = (await response.json()).id;console.log('subido', fileId);Volver a subir una grabación de llamada
Sección titulada «Volver a subir una grabación de llamada»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.
GET /api/files/{id}/
Sección titulada «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
Sección titulada «Referencia de estados de archivo»| Estado | Significado |
|---|---|
uploaded | Archivo 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. |
transcribing | Transcripción en curso. |
transcribed | Transcripción completada correctamente. Ya existe un registro Transcript. |
failed | La 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, 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
Sección titulada «Patrón de polling»file_id=4217while :; 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 10doneimport time
while True: file_data = requests.get( f"{BASE_URL}/api/files/{file_id}/", headers=HEADERS, timeout=30 ).json() status = file_data["status"] print(f"status={status}") if status == "transcribed": break if status == "failed": raise RuntimeError(f"falló, motivo: {file_data.get('error_reason') or 'unknown'}") time.sleep(10)const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
while (true) { const fileData = await fetch(`${BASE_URL}/api/files/${fileId}/`, { headers: HEADERS, }).then((r) => r.json()); console.log(`status=${fileData.status}`); if (fileData.status === 'transcribed') break; if (fileData.status === 'failed') { throw new Error(`falló, motivo: ${fileData.error_reason || 'unknown'}`); } await sleep(10_000);}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.
Reintentar una transcripción fallida
Sección titulada «Reintentar una transcripción fallida»Si un archivo termina en failed, puedes reintentarlo a través de la API de Tasks.
- 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). - 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.
GET /api/transcripts/
Sección titulada «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", "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.
GET /api/transcripts/{id}/
Sección titulada «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 $USPEECH_KEY"transcript = requests.get( f"{BASE_URL}/api/transcripts/901/", headers=HEADERS, timeout=30).json()const transcript = await fetch(`${BASE_URL}/api/transcripts/901/`, { headers: HEADERS,}).then((r) => r.json());Si la transcripción existe pero no es visible para quien llama, la respuesta es 404 Not Found.
GET /api/transcripts/{id}/download/
Sección titulada «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 $USPEECH_KEY" | jq -r .download_url)
# … y descarga.curl -o interview.srt "$url"# Obtén la URL …url = requests.get( f"{BASE_URL}/api/transcripts/901/download/", headers=HEADERS, params={"type": "srt"}, timeout=30,).json()["download_url"]
# … y descarga. La URL viene firmada, así que no necesita cabecera de autenticación.with open("interview.srt", "wb") as fh: fh.write(requests.get(url, timeout=120).content)import { writeFile } from 'node:fs/promises';
// Obtén la URL …const { download_url: url } = await fetch( `${BASE_URL}/api/transcripts/901/download/?type=srt`, { headers: HEADERS },).then((r) => r.json());
// … y descarga. La URL viene firmada, así que no necesita cabecera de autenticación.const srt = await fetch(url).then((r) => r.arrayBuffer());await writeFile('interview.srt', Buffer.from(srt));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.
Configura el análisis automático
Sección titulada «Configura el análisis automático»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:
| Campo | Tipo | Descripción |
|---|---|---|
auto_analysis_enabled | bool | Interruptor principal. El análisis solo ocurre cuando es true. |
auto_analysis_types | lista | Qué análisis ejecutar por llamada. Uno o varios de calls_analysis_copc, calls_analysis_no_protocol, custom_questions. |
auto_analysis_questions | lista de textos | El conjunto de preguntas que se responde por llamada. Obligatorio cuando custom_questions está activo. |
evaluation_rubric | int | ID de la rúbrica con la que puntuar. Obligatorio cuando calls_analysis_copc está activo. |
auto_analysis_batch_size | int | Envía un lote cuando haya esta cantidad de llamadas esperando. Por defecto 20, rango permitido 1–20. |
auto_analysis_max_wait_seconds | int | Vací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_typedel proyecto no escall— el análisis automático es solo para proyectos de llamadas. auto_analysis_typesestá vacío.- Se solicita
calls_analysis_copcsin unaevaluation_rubric. - Se solicita
custom_questionssin ningunaauto_analysis_questions. auto_analysis_batch_sizeestá fuera de1–20.
Ejemplo — activar el análisis por llamada sin protocolo más dos preguntas personalizadas:
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 }'import osimport requests
BASE_URL = "https://app.uspeech.io"HEADERS = {"Authorization": f"Api-Key {os.environ['USPEECH_KEY']}"}project_id = 312
response = requests.patch( f"{BASE_URL}/api/projects/{project_id}/", headers=HEADERS, json={ "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, }, timeout=30,)response.raise_for_status()print(response.json()["auto_analysis_types"])const BASE_URL = 'https://app.uspeech.io';const HEADERS = { Authorization: `Api-Key ${process.env.USPEECH_KEY}` };const projectId = 312;
const response = await fetch(`${BASE_URL}/api/projects/${projectId}/`, { method: 'PATCH', headers: { ...HEADERS, 'Content-Type': 'application/json' }, body: JSON.stringify({ 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, }),});if (!response.ok) throw new Error(await response.text());console.log((await response.json()).auto_analysis_types);GET /api/projects/{id}/ devuelve los mismos campos, así que puedes consultar la configuración
actual antes de cambiarla.
Cómo funcionan los lotes
Sección titulada «Cómo funcionan los lotes»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_sizellamadas 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.
Sigue el progreso
Sección titulada «Sigue el progreso»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.
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 30doneimport time
while True: status = requests.get( f"{BASE_URL}/calls/api/analysis-status/", headers=HEADERS, params={"project_id": project_id}, timeout=30, ).json() print(f"analizadas={status['analyzed_calls']} in_progress={status['in_progress']}") if not status["in_progress"]: break time.sleep(30)const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
while (true) { const status = await fetch( `${BASE_URL}/calls/api/analysis-status/?project_id=${projectId}`, { headers: HEADERS }, ).then((r) => r.json()); console.log(`analizadas=${status.analyzed_calls} in_progress=${status.in_progress}`); if (!status.in_progress) break; await sleep(30_000);}Lee los resultados
Sección titulada «Lee los resultados»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 agregadoGET /calls/api/calls/?project_id={id}— el explorador de llamadasGET /calls/api/custom-questions/?project_id={id}— respuestas por llamada a tus preguntas personalizadasGET /calls/api/report/pdf/?project_id={id}— la exportación en PDF
Ejemplos de principio a fin
Sección titulada «Ejemplos de principio a fin»Transcribir una grabación y descargar el SRT
Sección titulada «Transcribir una grabación y descargar el SRT»# 1. Subirresp=$(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. Pollingwhile :; 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 10done
# 3. Encuentra la transcripción y descarga el SRTtranscript_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"import osimport time
import requests
BASE_URL = "https://app.uspeech.io"HEADERS = {"Authorization": f"Api-Key {os.environ['USPEECH_KEY']}"}
# 1. Subirwith open("interview.wav", "rb") as fh: response = requests.post( f"{BASE_URL}/api/files/", headers=HEADERS, data={"project": 312, "file_type": "audio"}, files={"file": ("interview.wav", fh, "audio/wav")}, timeout=300, )response.raise_for_status()file_id = response.json()["id"]
# 2. Pollingwhile True: file_data = requests.get( f"{BASE_URL}/api/files/{file_id}/", headers=HEADERS, timeout=30 ).json() if file_data["status"] == "transcribed": break if file_data["status"] == "failed": raise SystemExit( f"transcripción fallida: {file_data.get('error_reason') or 'unknown'}" ) time.sleep(10)
# 3. Encuentra la transcripción y descarga el SRTtranscripts = requests.get( f"{BASE_URL}/api/transcripts/", headers=HEADERS, params={"uploaded_file": file_id}, timeout=30,).json()transcript_id = transcripts["results"][0]["id"]
url = requests.get( f"{BASE_URL}/api/transcripts/{transcript_id}/download/", headers=HEADERS, params={"type": "srt"}, timeout=30,).json()["download_url"]
with open("interview.srt", "wb") as fh: fh.write(requests.get(url, timeout=120).content)import { openAsBlob } from 'node:fs';import { writeFile } from 'node:fs/promises';
const BASE_URL = 'https://app.uspeech.io';const HEADERS = { Authorization: `Api-Key ${process.env.USPEECH_KEY}` };const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
// 1. Subirconst form = new FormData();form.set('project', '312');form.set('file_type', 'audio');form.set('file', await openAsBlob('./interview.wav'), 'interview.wav');
const upload = await fetch(`${BASE_URL}/api/files/`, { method: 'POST', headers: HEADERS, body: form,});if (!upload.ok) throw new Error(await upload.text());const fileId = (await upload.json()).id;
// 2. Pollingwhile (true) { const fileData = await fetch(`${BASE_URL}/api/files/${fileId}/`, { headers: HEADERS, }).then((r) => r.json()); if (fileData.status === 'transcribed') break; if (fileData.status === 'failed') { throw new Error(`transcripción fallida: ${fileData.error_reason || 'unknown'}`); } await sleep(10_000);}
// 3. Encuentra la transcripción y descarga el SRTconst transcripts = await fetch( `${BASE_URL}/api/transcripts/?uploaded_file=${fileId}`, { headers: HEADERS },).then((r) => r.json());const transcriptId = transcripts.results[0].id;
const { download_url: url } = await fetch( `${BASE_URL}/api/transcripts/${transcriptId}/download/?type=srt`, { headers: HEADERS },).then((r) => r.json());
await writeFile('interview.srt', Buffer.from(await fetch(url).then((r) => r.arrayBuffer())));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 bashset -euo pipefail
BASE_URL="https://app.uspeech.io"AUTH="Authorization: Api-Key ${USPEECH_KEY}"project_id=312
# 1. Activar el análisis automáticocurl -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,campaigncurl -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 terminewhile :; 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 30done
# 5. Descargar el informecurl -sS "${BASE_URL}/calls/api/report/?project_id=${project_id}" -H "$AUTH" > report.jsonecho "informe escrito en report.json"import osimport timefrom pathlib import Path
import requests
BASE_URL = "https://app.uspeech.io"HEADERS = {"Authorization": f"Api-Key {os.environ['USPEECH_KEY']}"}project_id = 312
# 1. Activar el análisis automáticorequests.patch( f"{BASE_URL}/api/projects/{project_id}/", headers=HEADERS, json={ "auto_analysis_enabled": True, "auto_analysis_types": ["calls_analysis_no_protocol"], }, timeout=30,).raise_for_status()
# 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,campaignwith open("llamadas_junio.csv", "rb") as fh: manifest = requests.post( f"{BASE_URL}/api/projects/{project_id}/call-manifest/", headers=HEADERS, files={"file": ("llamadas_junio.csv", fh, "text/csv")}, timeout=120, )manifest.raise_for_status()result = manifest.json()print(f"{result['matched']} asociadas, {len(result['unmatched'])} esperando su archivo")
# 3. Subir todas las grabaciones de ./calls/for path in sorted(Path("calls").glob("*.mp3")): with path.open("rb") as fh: response = requests.post( f"{BASE_URL}/api/files/", headers=HEADERS, data={"project": project_id, "file_type": "audio"}, files={"file": (path.name, fh, "audio/mpeg")}, timeout=300, ) response.raise_for_status() body = response.json() print(f"subido {path.name} -> {body['id']}") for warning in body.get("warnings", []): print(f"aviso: {warning['code']}: {warning['detail']}")
# 4. Esperar a que el análisis terminewhile True: status = requests.get( f"{BASE_URL}/calls/api/analysis-status/", headers=HEADERS, params={"project_id": project_id}, timeout=30, ).json() if not status["in_progress"]: break time.sleep(30)
# 5. Descargar el informereport = requests.get( f"{BASE_URL}/calls/api/report/", headers=HEADERS, params={"project_id": project_id}, timeout=60,).json()print(f"{report['headline']['total_calls']} llamadas en el informe")import { readdir } from 'node:fs/promises';import { openAsBlob } from 'node:fs';
const BASE_URL = 'https://app.uspeech.io';const HEADERS = { Authorization: `Api-Key ${process.env.USPEECH_KEY}` };const projectId = 312;const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
// 1. Activar el análisis automáticoawait fetch(`${BASE_URL}/api/projects/${projectId}/`, { method: 'PATCH', headers: { ...HEADERS, 'Content-Type': 'application/json' }, body: JSON.stringify({ auto_analysis_enabled: true, auto_analysis_types: ['calls_analysis_no_protocol'], }),});
// 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,campaignconst manifestForm = new FormData();manifestForm.set('file', await openAsBlob('./llamadas_junio.csv'), 'llamadas_junio.csv');
const manifest = await fetch(`${BASE_URL}/api/projects/${projectId}/call-manifest/`, { method: 'POST', headers: HEADERS, body: manifestForm,});if (!manifest.ok) throw new Error(await manifest.text());const { matched, unmatched } = await manifest.json();console.log(`${matched} asociadas, ${unmatched.length} esperando su archivo`);
// 3. Subir todas las grabaciones de ./calls/const names = (await readdir('calls')).filter((name) => name.endsWith('.mp3'));for (const name of names) { const form = new FormData(); form.set('project', String(projectId)); form.set('file_type', 'audio'); form.set('file', await openAsBlob(`calls/${name}`), name);
const response = await fetch(`${BASE_URL}/api/files/`, { method: 'POST', headers: HEADERS, body: form, }); if (!response.ok) throw new Error(`${name}: ${await response.text()}`); const { id, warnings = [] } = await response.json(); console.log(`subido ${name} -> ${id}`); for (const warning of warnings) console.log(`aviso: ${warning.code}: ${warning.detail}`);}
// 4. Esperar a que el análisis terminewhile (true) { const status = await fetch( `${BASE_URL}/calls/api/analysis-status/?project_id=${projectId}`, { headers: HEADERS }, ).then((r) => r.json()); if (!status.in_progress) break; await sleep(30_000);}
// 5. Descargar el informeconst report = await fetch( `${BASE_URL}/calls/api/report/?project_id=${projectId}`, { headers: HEADERS },).then((r) => r.json());console.log(`${report.headline.total_calls} llamadas en el informe`);Solución de problemas
Sección titulada «Solución de problemas»| Síntoma | Causa probable |
|---|---|
Un archivo se queda en uploaded | La transcripción no empezó, normalmente porque la suscripción no tenía minutos al subirlo. |
Un archivo termina en failed | error_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 nada | auto_analysis_enabled es false, o auto_analysis_types está vacío. Comprueba GET /api/projects/{id}/. |
auto_analysis_error es quota_exceeded | La 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_missing | El 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 cuerpo | El proyecto no es de llamadas, o file_type no es audio/srt/vtt. |
400 al activar el análisis automático | Falta 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 subidos | Los 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 0 | Esas 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.