API de transcripción de vídeo y apuntes

Inicio rápido

Estos pasos llevan un archivo de tu disco a una transcripción y unos apuntes. Necesitas un plan Basic o Plus activo, una terminal y, para el cliente de ejemplo, Python 3.12 o posterior.

1. Crea una clave API

Inicia sesión en la web (por ejemplo, en la página de precios), abre Claves API en la barra de la cuenta, ponle un nombre a la clave y, si quieres, una fecha de caducidad. Copia el secreto en cuanto aparezca: solo se muestra una vez. Puede haber hasta tres claves activas a la vez.

2. Guarda la clave en una variable de entorno

Mantén la clave fuera del código fuente, de los argumentos de línea de comandos y de los registros. Los ejemplos leen la clave de VTN_API_KEY y la URL base de VTN_API_BASE.

export VTN_API_BASE="https://api.video-to-notes.com"
read -rs VTN_API_KEY && export VTN_API_KEY   # paste the key, press Enter

$env:VTN_API_BASE = "https://api.video-to-notes.com"
$env:VTN_API_KEY = Read-Host "API key" -MaskInput

3. Comprueba tu cuenta

Esta llamada confirma que la clave funciona y devuelve tu plan, los segundos que te quedan, los formatos admitidos y los límites actuales.

# Sends the key through stdin, so it never appears in the process list.
vtn() {
  printf 'header = "Authorization: Bearer %s"\n' "$VTN_API_KEY" |
    curl -s --config - "$@"
}

vtn "$VTN_API_BASE/api/v1/account"

$headers = @{ Authorization = "Bearer $env:VTN_API_KEY" }
Invoke-RestMethod "$env:VTN_API_BASE/api/v1/account" -Headers $headers |
  ConvertTo-Json -Depth 5

4. Transcribe un archivo

Descarga el cliente de ejemplo en Python. Solo necesita la biblioteca estándar. Sube el archivo por partes, inicia la tarea, espera a que termine y guarda cada página de resultados.

python client.py run meeting.mp4 --state meeting.state.json \
  --output meeting.jsonl --download meeting-files

Para procesar solo una parte de una grabación, añade --start y --end en segundos desde el inicio del archivo. --audio-language da una pista sobre el idioma y --notes-language elige el idioma de los apuntes. Sin estas opciones se procesa todo el archivo y los idiomas se detectan automáticamente.

python client.py run lecture.webm --state lecture.state.json \
  --start 30 --end 3630 --audio-language ru --notes-language en

El archivo de estado guarda el ID de la subida y la identidad de la solicitud, nunca la clave. Si el comando se detiene, vuelve a ejecutarlo con el mismo archivo de estado: recupera la misma tarea y no se te cobra dos veces. Usa un archivo de estado nuevo para cada tarea nueva.

5. Lee los resultados

meeting.jsonl contiene una página de resultados JSON por línea: texto de la transcripción con tiempos, apuntes en Markdown, huecos y avisos. meeting-files contiene las descargas, como la transcripción en TXT y los apuntes en Markdown, HTML y PDF. El cliente tiene además estos comandos:

python client.py account
python client.py status JOB_ID
python client.py result JOB_ID --output results.jsonl --download files
python client.py cancel JOB_ID
python client.py resume JOB_ID

¿Prefieres curl? El inicio rápido en Bash ejecuta los mismos pasos de subida, tarea y resultado con curl y jq.

bash quickstart.sh meeting.mp4

Cómo funciona una tarea

Toda integración sigue los mismos seis pasos. La referencia de la API muestra cada llamada con un ejemplo de solicitud y de respuesta.

1. Comprueba la cuenta. GET /api/v1/account devuelve tu plan, los segundos restantes, los formatos admitidos y los límites.
2. Crea una subida. POST /api/v1/uploads con el tamaño del archivo en bytes y su extensión. La respuesta indica el tamaño de cada parte y el número de partes.
3. Sube las partes. Obtén URL firmadas con POST /api/v1/uploads/{upload_id}/parts, envía cada parte con un PUT HTTP directamente al almacenamiento, guarda cada ETag y después llama a POST /api/v1/uploads/{upload_id}/complete.
4. Inicia la tarea. POST /api/v1/jobs con el ID de la subida y una cabecera Idempotency-Key. El servidor comprueba el archivo real, planifica el trabajo y reserva el tiempo de tu plan.
5. Consulta el estado. GET /api/v1/jobs/{job_id} hasta que el estado sea final, esperando al menos poll_after_seconds entre llamadas.
6. Lee el resultado. GET /api/v1/jobs/{job_id}/result y sigue next_cursor hasta que sea null. Descarga los archivos de artifacts antes de que caduquen sus enlaces.

Una tarea termina como completed, completed_with_gaps, interrupted, cancelled, failed o expired. charged_seconds indica cuánto de tu plan ha usado la tarea.

Buenas prácticas

Estos hábitos protegen tus claves, evitan cobros dobles y hacen fiables las tareas largas.

Mantén las claves en secreto

• Llama a la API solo desde un servidor o un script que controles. Nunca pongas una clave en código del navegador, en una app móvil, en una URL o en el control de versiones.
• Carga la clave desde una variable de entorno o un gestor de secretos, y mantenla fuera de registros, informes de errores y argumentos de línea de comandos.
• Usa una clave por integración con fecha de caducidad, para poder cambiar o revocar una clave sin tocar las demás.
• Para cambiar una clave, crea la nueva, despliégala y revoca la antigua. Las tareas ya iniciadas siguen en marcha.
• Si una clave puede haberse filtrado, por ejemplo en un chat, un ticket o un commit, revócala de inmediato en el panel Claves API.

Haz que crear tareas sea seguro de repetir

• Genera una Idempotency-Key aleatoria, como un UUID, para cada tarea nueva y guárdala con el ID de la subida antes de enviar la solicitud.
• Si se pierde la respuesta, envía la misma solicitud con la misma clave. Recibes la tarea original y no se te cobra dos veces.
• Nunca reutilices una clave para otro archivo u otras opciones: la API responde con 409 IDEMPOTENCY_CONFLICT.

Consulta con moderación y respeta los límites

• Espera al menos cinco segundos entre consultas de estado, y más si poll_after_seconds lo pide.
• Ante un 429 o un 503, espera lo que indique la cabecera Retry-After o error.retry_after_seconds y reintenta con un pequeño retardo aleatorio.
• Repite una solicitud sin cambios solo si error.retryable es true. Si no, corrige antes la solicitud.
• Una cuenta ejecuta una subida y una tarea a la vez. Pon tus archivos en cola y envía el siguiente cuando termine la tarea actual.

Controla las horas que usas

• Comprueba remaining_seconds antes de subir. Una tarea que necesita más tiempo del que tienes falla con INSUFFICIENT_BALANCE; la API nunca acorta tu selección para que encaje.
• Envía un range cuando solo necesites una parte de una grabación. Solo se cobra el audio seleccionado.
• Cancela las tareas que ya no necesites. Las partes terminadas siguen disponibles y el tiempo reservado que no se usó se devuelve.
• Anula las subidas que no vayas a usar, para que pueda empezar la siguiente.

Recoge resultados completos

• Sigue next_cursor hasta que sea null. Una página contiene como máximo 32 elementos.
• Trata los elementos gap como audio que no se pudo procesar, no como silencio, y revisa los warnings.
• Descarga los archivos de artifacts mientras sus enlaces sean válidos (hasta diez minutos); vuelve a pedir la página para obtener enlaces nuevos.
• Guarda lo que necesites: los archivos de resultados se conservan unas 24 horas y la recuperación de la transcripción unas 48 horas.
• Lee los campos que necesites e ignora el resto.

Preguntas frecuentes

Archivos y ejemplos

Los ejemplos y los archivos del contrato se publican con la web y coinciden con la API en producción.

• client.py: cliente de ejemplo para Python 3.12+, solo biblioteca estándar
• quickstart.sh: ejemplo en Bash con curl y jq
• openapi.json: descripción OpenAPI 3.1 de todos los endpoints, con ejemplos
• paid-api.schema.json: JSON Schema de todas las solicitudes y respuestas

Ayuda

¿Algo no está claro o no funciona? Escríbenos e incluye el request_id de la respuesta de error, la hora y el endpoint. Nunca nos envíes tu clave API.