Conception d'API de traitement vidéo : Interfaces RESTful et API de streaming en temps réel

Principes de conception des API de traitement vidéo

Les API de traitement vidéo diffèrent des API CRUD classiques : elles impliquent des scénarios complexes tels que le transfert de fichiers volumineux, le traitement de longue durée et le suivi d'état. Une API de traitement vidéo bien conçue doit respecter les principes suivants :

• Priorité à l'asynchrone : le traitement vidéo étant généralement long, il faut adopter un mode asynchrone pour éviter les timeouts de requête
• Idempotence : la soumission répétée de la même requête ne doit pas avoir d'effets secondaires ; utiliser un ID de tâche unique pour garantir l'idempotence
• Observabilité : fournir des capacités de consultation d'état de tâche, de rappel de progression et d'accès aux logs
• Évolutivité élastique : prendre en charge la mise à l'échelle horizontale, ajuster dynamiquement la capacité de traitement selon la charge de tâches
• Récupération sur erreur : prendre en charge la reprise de tâche et la reprise sur interruption, améliorer la tolérance aux pannes du système
• Stratification claire : séparation des couches d'accès, métier et traitement, pour faciliter la maintenance et l'extension

Normes d'interfaces RESTful

Il est recommandé aux API de traitement vidéo de suivre le style de conception RESTful, d'utiliser les méthodes et codes d'état HTTP standard, pour offrir une expérience d'interface claire et cohérente.

Nommage des ressources

• Ressource de tâche : /api/v1/tasks, tâches de traitement vidéo
• Ressource de fichier : /api/v1/files, fichiers vidéo téléchargés
• Ressource de modèle : /api/v1/templates, modèles/présélections de traitement
• Ressource de job : /api/v1/jobs, jobs de traitement spécifiques

Utilisation des méthodes HTTP

• POST : créer une tâche, télécharger un fichier, soumettre une demande de traitement
• GET : consulter l'état d'une tâche, obtenir le résultat du traitement, lister les tâches
• PUT : mettre à jour la configuration d'une tâche (avant son démarrage)
• DELETE : annuler une tâche, supprimer un fichier

Flux de téléchargement/traitement/rappel

Le flux typique de traitement vidéo comprend quatre étapes : téléchargement de fichier, soumission de tâche, traitement asynchrone et rappel de résultat.

Étape 1 : Téléchargement de fichier

Pour le téléchargement de fichiers volumineux, il est recommandé d'utiliser une solution de téléchargement par segments (Multipart Upload) :

# 1. Initialiser le téléchargement
POST /api/v1/uploads
{
  "filename": "video.mp4",
  "file_size": 1073741824,
  "content_type": "video/mp4"
}

# Réponse
{
  "upload_id": "upl_abc123",
  "chunk_size": 5242880,
  "chunks": 205
}

# 2. Télécharger un segment
PUT /api/v1/uploads/upl_abc123/chunks/1
Content-Range: bytes 0-5242879/1073741824

# 3. Terminer le téléchargement
POST /api/v1/uploads/upl_abc123/complete
{
  "checksum": "sha256:abc123..."
}

# Réponse
{
  "file_id": "file_xyz789",
  "filename": "video.mp4",
  "size": 1073741824
}

Étape 2 : Soumettre une tâche de traitement

POST /api/v1/tasks
Content-Type: application/json

{
  "input_file": "file_xyz789",
  "output_format": "mp4",
  "video": {
    "codec": "h264",
    "bitrate": "2000k",
    "resolution": "1920x1080",
    "fps": 30
  },
  "audio": {
    "codec": "aac",
    "bitrate": "128k"
  },
  "callback_url": "https://example.com/webhook",
  "callback_secret": "my-secret-key"
}

# Réponse 202 Accepted
{
  "task_id": "task_abc123",
  "status": "queued",
  "created_at": "2026-04-28T12:00:00Z",
  "estimated_time": 180
}

Étape 3 : Consulter l'état de la tâche

GET /api/v1/tasks/task_abc123

# Réponse
{
  "task_id": "task_abc123",
  "status": "processing",
  "progress": 45,
  "current_stage": "encoding",
  "created_at": "2026-04-28T12:00:00Z",
  "started_at": "2026-04-28T12:00:10Z",
  "estimated_completion": "2026-04-28T12:03:10Z",
  "input_file": "file_xyz789",
  "output_file": null,
  "error": null
}

Étape 4 : Notification de rappel

# Le serveur envoie une requête POST à callback_url
POST https://example.com/webhook
X-Signature: sha256=abc123...

{
  "task_id": "task_abc123",
  "status": "completed",
  "progress": 100,
  "output_file": {
    "file_id": "file_output_123",
    "url": "https://cdn.example.com/output.mp4",
    "size": 250000000,
    "duration": 600.5
  },
  "completed_at": "2026-04-28T12:03:05Z"
}

Conception des API de streaming en temps réel

Les API de streaming en temps réel diffèrent grandement des API de traitement vidéo classiques : elles doivent gérer des connexions longues, la transmission de données en temps réel et l'ajustement dynamique du débit binaire.

API de gestion des flux en direct

# Créer un flux en direct
POST /api/v1/live/streams
{
  "title": "Différence en direct de lancement produit",
  "publish_type": "rtmp",
  "resolution": ["1080p", "720p", "480p"],
  "record": true,
  "callback_url": "https://example.com/live/webhook"
}

# Réponse
{
  "stream_id": "live_abc123",
  "push_url": "rtmp://push.example.com/live/abc123",
  "push_key": "live_abc123?token=xyz789",
  "play_urls": {
    "hls": "https://play.example.com/live/abc123/index.m3u8",
    "flv": "https://play.example.com/live/abc123.flv",
    "webrtc": "webrtc://play.example.com/live/abc123"
  },
  "status": "waiting"
}

# Obtenir l'état du flux en direct
GET /api/v1/live/streams/live_abc123

# Réponse
{
  "stream_id": "live_abc123",
  "status": "live",
  "viewer_count": 1250,
  "bitrate": 2500000,
  "resolution": "1920x1080",
  "started_at": "2026-04-28T12:00:00Z",
  "duration": 1800
}

API de statistiques en temps réel

Pour le streaming en temps réel, il faut fournir des données statistiques à granularité fine :

• Nombre de spectateurs en ligne en temps réel, utilisation de la bande passante
• Données en temps réel de fréquence d'images, débit binaire, résolution
• Indicateurs QoE tels que taux de saccade, temps de première image
• Surveillance de l'état de santé du côté de l'édition

Authentification et sécurité

Méthodes d'authentification API

Les API de traitement vidéo utilisent généralement plusieurs méthodes d'authentification :

1. API Key + Signature

Utilisation d'Access Key + Secret Key pour la vérification de signature, adapté aux appels côté serveur :

# Exemple d'en-têtes de requête
X-Access-Key: your_access_key
X-Timestamp: 1714305600
X-Signature: HMAC-SHA256:...
X-Nonce: random_string

2. JWT Token

Adapté aux appels frontend ou aux scénarios à courte durée de validité :

• Obtenir un Token après la connexion de l'utilisateur
• Le Token contient les autorisations et la date d'expiration
• Vérification sans état côté serveur

3. Signature URL

Utilisé pour protéger les adresses de lecture vidéo et empêcher le détournement de lien :

https://cdn.example.com/video.mp4?sign=abc123&t=1714305600

# Logique de vérification
sign = md5(uri + expire_time + secret_key)
si temps non expiré && sign vérifié:
    renvoyer le contenu vidéo
sinon:
    renvoyer 403 Forbidden

Bonnes pratiques de sécurité

• Tous les appels API doivent utiliser HTTPS
• Les opérations sensibles (suppression, traitement par lots) nécessitent une vérification secondaire
• Vérification du type de fichier et analyse antivirus lors du téléchargement
• Liste blanche IP et contrôle d'accès géographique
• Rotation régulière des clés et des identifiants

Gestion des erreurs

Format de réponse d'erreur unifié

# Exemple de réponse d'erreur
{
  "error": {
    "code": "TASK_LIMIT_EXCEEDED",
    "message": "Le nombre de tâches traitées simultanément a atteint la limite",
    "details": {
      "current_tasks": 5,
      "max_tasks": 5
    },
    "request_id": "req_abc123",
    "retryable": true,
    "retry_after": 60
  }
}

Classification des codes d'erreur courants

• 400 Bad Request : paramètre incorrect, format de fichier non pris en charge
• 401 Unauthorized : échec de l'authentification, Token expiré
• 403 Forbidden : autorisations insuffisantes, IP restreinte
• 404 Not Found : tâche ou fichier inexistant
• 409 Conflict : conflit d'état de tâche, soumission en double
• 429 Too Many Requests : requêtes trop fréquentes
• 500 Internal Server Error : erreur interne du serveur
• 503 Service Unavailable : service temporairement indisponible

Stratégies de limitation de débit

Les services de traitement vidéo consomment beaucoup de ressources ; il est essentiel de mettre en œuvre des stratégies de limitation de débit raisonnables pour protéger la stabilité du système.

Dimensions de la limitation de débit

• Fréquence d'appel API : limite du nombre de requêtes par minute/heure
• Nombre de tâches simultanées : limite du nombre de tâches traitées simultanément par utilisateur
• Limite de taille de fichier : limite de taille de fichier unique, limite de volume de traitement quotidien total
• Limite de bande passante : limite de bande passante de téléchargement/téléversement
• Quota de stockage : limite de capacité de stockage totale

Algorithmes de limitation de débit

• Seau à jetons : adapté au trafic en rafale, traitement lisse
• Seau à fuites : traitement à vitesse constante, adapté à une sortie stable
• Fenêtre glissante : comptage précis de fenêtre temporelle
• Limitation distribuée : utilisation de Redis pour implémenter une limitation au niveau du cluster

Recommandations pour la documentation API

Contenu de la documentation

• Guide de démarrage rapide : authentification, premier appel API
• Documentation détaillée des interfaces : paramètres, valeurs de retour, codes d'erreur
• Exemples de code : SDK ou exemples de code dans plusieurs langages
• Bonnes pratiques : solutions d'implémentation pour les scénarios courants
• FAQ : réponses aux questions fréquentes

Outils de documentation recommandés

• Swagger / OpenAPI : format standard de description d'API
• Postman : collection d'API exécutable directement
• API Blueprint : documentation API de style Markdown
• Console interactive : déboguer l'API directement sur la page de documentation

Conclusion

La conception des API de traitement vidéo doit tenir compte pleinement des spécificités du scénario vidéo : fichiers volumineux, longue durée, forte concurrence, consommation de ressources importante. L'adoption de mécanismes tels que le mode de traitement asynchrone, le téléchargement par segments et les notifications de rappel peut offrir une bonne expérience utilisateur. Parallèlement, un système d'authentification complet, une stratégie de limitation de débit raisonnable et une gestion des erreurs claire sont les garantes du fonctionnement stable de l'API.

Suivre les normes RESTful, fournir une documentation détaillée et des SDK, maintenir la compatibilité ascendante des interfaces, peut grandement réduire le coût d'intégration des développeurs et améliorer la facilité d'utilisation et la compétitivité de l'API.

Vous voulez en savoir plus sur les technologies vidéo ? Consultez notre Guide d'utilisation de HLS.js, ou utilisez directement notre Lecteur M3U8 en ligne pour expérimenter la lecture en streaming.