Intégration API
API de sous-titres vidéo pour une automatisation de sous-titrage à haut volume et sécurisée par le QA
Automatisez la génération de sous-titres avec des états de job explicites, des contrôles de langue et des retries sûrs en production pour les équipes livrant de gros volumes au format court.
Problème
À grande échelle, les opérations de sous-titrage échouent souvent au niveau du QA et de la cohérence : les vérifications manuelles de timing, les décalages de langue et les révisions répétées deviennent un goulot d'étranglement de production caché.
Résultat avec Ssemble
Ssemble permet un traitement de sous-titres déterministe avec des contrats de statut/erreur clairs afin que les équipes d'ingénierie puissent automatiser le QA de routine et n'escalader que les véritables cas limites.
Éléments essentiels d'implémentation
URL de base: https://aiclipping.ssemble.com/api/v1
Architecture d'intégration (ingestion → traitement → polling/webhook → publication)
1) Ingestion
Stockez l'URL source/URL de fichier ainsi que les champs de configuration des sous-titres (language, captionLanguage, templateId, preferredLength).
2) Traitement
Appelez POST /shorts/create avec les paramètres de sous-titres et persistez requestId + correlation id.
3) Polling / Webhook
Vérifiez GET /shorts/:id/status (ou l'endpoint list) à une cadence contrôlée jusqu'à l'état terminal.
4) Publication
Récupérez les assets finalisés, exécutez des vérifications QA automatisées des sous-titres et transmettez-les à la file d'attente de publication.
Exemples d'endpoint
POST /shorts/create— Créer un short sous-titré avec des options de langue/templateGET /shorts/:id/status— Suivre l'étape de traitement et failureReasonGET /shorts— Surveiller les jobs par lot sans surcharge d'un appel par job
Recommandations d'authentification
Utilisez uniquement X-API-Key côté serveur. Gardez des clés distinctes pour le staging et la production afin de réduire le risque de rotation et le couplage d'environnement.
Rate limits et retries
Évitez les boucles de polling trop serrées. Utilisez des vérifications de statut par lot, mettez en cache les résultats stables et, en cas de 429, respectez reset/retryAfter avant les retries avec backoff.
Exemple de requête
POST /shorts/create
{
"url": "https://www.youtube.com/watch?v=abc123",
"start": 0,
"end": 540,
"language": "en",
"captionLanguage": "en",
"templateId": "660b8531aedb346bbe26eb43",
"preferredLength": "under60sec",
"layout": "auto"
}Exemple de réponse
200 OK
{
"data": {
"requestId": "665a1b2c3d4e5f6a7b8c9d0e",
"status": "processing",
"creditsUsed": 1,
"estimatedCompletionTime": "2026-03-10T06:05:00.000Z"
}
}Exemple de scénario d'erreur
400 Bad Request
{
"error": {
"code": "invalid_request",
"message": "Invalid captionLanguage code",
"details": { "captionLanguage": "xx" }
}
}Gestion des versions
Épinglez les versions d'endpoint et validez les schémas de requête en CI pour détecter la dérive d'intégration avant la mise en production.
Support
Pour les jobs échoués, conservez le hash du payload de requête + requestId + error.details afin que les équipes puissent distinguer les mauvaises entrées des incidents de pipeline.
Démarrage rapide
- Créez SSEMBLE_API_KEY dans le dashboard et stockez-la dans le runtime backend.
- Envoyez un payload POST /shorts/create minimal avec source + timing + langue.
- Effectuez un polling de GET /shorts/:id/status toutes les 10 secondes jusqu'à completed/failed/cancelled.
- Récupérez la sortie depuis GET /shorts/:id et exécutez des assertions de QA de sous-titres.
- Ajoutez des retries bornés pour les 429/5xx transitoires et routez les jobs épuisés vers la DLQ.
Workflow en 3 étapes
- Capturez le média source et les paramètres de sous-titres (langue/template/longueur préférée) dans votre modèle de file d'attente.
- Soumettez les requêtes create, surveillez les transitions de statut et routez automatiquement les états terminaux.
- Publiez les sorties finalisées après des vérifications automatisées de lisibilité des sous-titres et de conformité.
Pourquoi les équipes choisissent Ssemble
- Conçu pour les équipes où la cohérence des sous-titres impacte la qualité de la marque et la rétention des spectateurs.
- Prend en charge un routage QA piloté par les états au lieu d'un triage manuel de boîte de réception.
- Passe à l'échelle sur plusieurs marques en externalisant la politique de style/langue dans votre couche d'intégration.
Étape suivante
FAQ
Qu'est-ce qui provoque généralement les échecs du pipeline de sous-titres ?
Les causes fréquentes sont des fenêtres de timing invalides, des URL source indisponibles et des valeurs de langue/template invalides. Validez-les avant la mise en file d'attente.
Faut-il faire un polling de chaque job individuellement à grande échelle ?
Uniquement pour de faibles volumes. À volume plus élevé, une surveillance de statut agrégée réduit la charge sur l'API et améliore la fiabilité.
Comment rendre les retries sûrs ?
Ne réessayez que les conditions transitoires (429/5xx/timeouts) et utilisez des empreintes de requête pour empêcher un traitement en double.
Les délais de finalisation sont-ils fixes ?
Non. La finalisation peut varier selon la durée de la source, les conditions de la file d'attente et les options. Considérez l'ETA comme indicative.
Peut-on imposer des styles de sous-titres par client ?
Oui. Conservez les correspondances style/template dans votre couche de configuration et injectez-les par tenant lors de la création de la requête.
Quelles alertes de production comptent le plus ?
Surveillez le taux d'échec par code d'erreur, l'âge de la file d'attente et le nombre de jobs bloqués en traitement pour détecter les incidents tôt.
