API de transcription vidéo et de notes

Démarrage rapide

Ces étapes mènent un fichier de votre disque jusqu’à une transcription et des notes. Il vous faut une formule Basic ou Plus active, un terminal et, pour le client d’exemple, Python 3.12 ou plus récent.

1. Créer une clé API

Connectez-vous sur le site (par exemple sur la page des tarifs), ouvrez Clés API dans la barre du compte, nommez la clé et, si vous le souhaitez, fixez une date d’expiration. Copiez le secret dès qu’il apparaît : il n’est affiché qu’une fois. Jusqu’à trois clés peuvent être actives en même temps.

2. Stocker la clé dans une variable d’environnement

Gardez la clé hors du code source, des arguments de ligne de commande et des journaux. Les exemples lisent la clé dans VTN_API_KEY et l’URL de base dans 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. Vérifier votre compte

Cet appel confirme que la clé fonctionne et renvoie votre formule, les secondes restantes de votre formule, les formats pris en charge et les limites actuelles.

# 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. Transcrire un fichier

Téléchargez le client Python d’exemple. Il n’a besoin que de la bibliothèque standard. Il envoie le fichier en plusieurs parties, lance la tâche, attend sa fin et enregistre chaque page de résultats.

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

Pour ne traiter qu’une partie d’un enregistrement, ajoutez --start et --end en secondes depuis le début du fichier. --audio-language donne une indication de langue et --notes-language choisit la langue des notes. Sans ces options, tout le fichier est traité et les langues sont détectées automatiquement.

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

Le fichier d’état conserve l’ID d’envoi et l’identité de la requête, jamais la clé. Si la commande s’arrête, relancez-la avec le même fichier d’état : elle retrouve la même tâche et rien ne vous est facturé deux fois. Utilisez un nouveau fichier d’état pour chaque nouvelle tâche.

5. Lire les résultats

meeting.jsonl contient une page de résultats JSON par ligne : texte de transcription avec horodatage, notes en Markdown, lacunes et avertissements. meeting-files contient les téléchargements, comme la transcription en TXT et les notes en Markdown, HTML et PDF. Le client propose aussi ces commandes :

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

Vous préférez curl ? Le démarrage rapide Bash exécute les mêmes étapes d’envoi, de tâche et de résultat avec curl et jq.

bash quickstart.sh meeting.mp4

Fonctionnement d’une tâche

Toute intégration suit les mêmes six étapes. La référence de l’API montre chaque appel avec un exemple de requête et de réponse.

1. Vérifier le compte. GET /api/v1/account renvoie votre formule, les secondes restantes, les formats pris en charge et les limites.
2. Créer un envoi. POST /api/v1/uploads avec la taille du fichier en octets et son extension. La réponse indique la taille des parties et leur nombre.
3. Envoyer les parties. Obtenez des URL signées avec POST /api/v1/uploads/{upload_id}/parts, envoyez chaque partie par HTTP PUT directement dans le stockage, conservez chaque ETag, puis appelez POST /api/v1/uploads/{upload_id}/complete.
4. Lancer la tâche. POST /api/v1/jobs avec l’ID d’envoi et un en-tête Idempotency-Key. Le serveur vérifie le fichier réel, planifie le travail et réserve le temps sur votre formule.
5. Suivre l’état. GET /api/v1/jobs/{job_id} jusqu’à ce que l’état soit final, en attendant au moins poll_after_seconds entre deux appels.
6. Lire le résultat. GET /api/v1/jobs/{job_id}/result, puis suivez next_cursor jusqu’à ce qu’il soit null. Téléchargez les fichiers listés dans artifacts avant l’expiration de leurs liens.

Une tâche se termine en completed, completed_with_gaps, interrupted, cancelled, failed ou expired. charged_seconds indique ce que la tâche a utilisé de votre formule.

Bonnes pratiques

Ces habitudes protègent vos clés, évitent les doubles facturations et fiabilisent les longues tâches.

Garder les clés secrètes

• N’appelez l’API que depuis un serveur ou un script que vous contrôlez. Ne mettez jamais une clé dans du code de navigateur, une application mobile, une URL ou un dépôt de code.
• Chargez la clé depuis une variable d’environnement ou un gestionnaire de secrets, et gardez-la hors des journaux, des rapports d’erreur et des arguments de ligne de commande.
• Utilisez une clé par intégration avec une date d’expiration, pour pouvoir remplacer ou révoquer une clé sans toucher aux autres.
• Pour remplacer une clé, créez la nouvelle, déployez-la, puis révoquez l’ancienne. Les tâches déjà lancées continuent.
• Si une clé a pu fuiter, par exemple dans une discussion, un ticket ou un commit, révoquez-la immédiatement dans le panneau Clés API.

Rendre la création de tâche sûre à répéter

• Générez une Idempotency-Key aléatoire, par exemple un UUID, pour chaque nouvelle tâche et enregistrez-la avec l’ID d’envoi avant d’envoyer la requête.
• Si la réponse est perdue, renvoyez la même requête avec la même clé. Vous récupérez la tâche d’origine et rien n’est facturé deux fois.
• Ne réutilisez jamais une clé pour un autre fichier ou d’autres options : l’API répond 409 IDEMPOTENCY_CONFLICT.

Interroger avec mesure et gérer les limites

• Attendez au moins cinq secondes entre deux appels d’état, et plus longtemps si poll_after_seconds le demande.
• En cas de 429 ou 503, attendez l’en-tête Retry-After ou error.retry_after_seconds, puis réessayez avec un léger délai aléatoire.
• Ne répétez une requête à l’identique que si error.retryable vaut true. Sinon, corrigez d’abord la requête.
• Un compte exécute un envoi et une tâche à la fois. Mettez vos fichiers en file d’attente et envoyez le suivant quand la tâche en cours est terminée.

Maîtriser les heures utilisées

• Vérifiez remaining_seconds avant d’envoyer un fichier. Une tâche qui demande plus de temps que vous n’en avez échoue avec INSUFFICIENT_BALANCE ; l’API ne raccourcit jamais votre sélection pour la faire tenir.
• Envoyez un range lorsque vous n’avez besoin que d’une partie d’un enregistrement. Seul l’audio sélectionné est facturé.
• Annulez les tâches dont vous n’avez plus besoin. Les parties terminées restent disponibles et le temps réservé non utilisé est restitué.
• Abandonnez les envois que vous n’utiliserez pas, pour que l’envoi suivant puisse démarrer.

Récupérer des résultats complets

• Suivez next_cursor jusqu’à ce qu’il soit null. Une page contient au plus 32 éléments.
• Traitez les éléments gap comme de l’audio qui n’a pas pu être traité, pas comme du silence, et vérifiez les warnings.
• Téléchargez les fichiers de artifacts tant que leurs liens sont valides (jusqu’à dix minutes) ; redemandez la page pour obtenir de nouveaux liens.
• Enregistrez ce dont vous avez besoin : les fichiers de résultats sont conservés environ 24 heures et la récupération de la transcription environ 48 heures.
• Lisez les champs dont vous avez besoin et ignorez les autres.

Questions fréquentes

Fichiers et exemples

Les exemples et les fichiers de contrat sont publiés avec le site et correspondent à l’API en production.

• client.py : client d’exemple Python 3.12+, bibliothèque standard uniquement
• quickstart.sh : exemple Bash avec curl et jq
• openapi.json : description OpenAPI 3.1 de chaque point de terminaison, avec exemples
• paid-api.schema.json : JSON Schema de chaque requête et réponse

Aide

Quelque chose n’est pas clair ou ne fonctionne pas ? Contactez-nous en indiquant le request_id de la réponse d’erreur, l’heure et le point de terminaison. Ne nous envoyez jamais votre clé API.