Intégration API
API de traduction vidéo pour des opérations de sortie multi-régions
Localisez une vidéo source en plusieurs sorties prêtes pour le marché avec une automatisation pilotée par le statut, une isolation des échecs au niveau de la locale et des workflows de déploiement contrôlés.
Problème
Les lancements mondiaux échouent souvent sur la synchronisation, pas sur la qualité de traduction : la langue principale est publiée en premier tandis que les variantes régionales prennent du retard et le timing de campagne se rompt.
Résultat avec Ssemble
Ssemble permet des opérations source-once, localize-many avec un suivi d'état spécifique à chaque locale afin que les équipes puissent publier par vagues contrôlées et récupérer rapidement des échecs partiels.
É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
Créez un manifeste de traduction : source, liste de locales, politique de déploiement et comportement de fallback.
2) Traitement
Soumettez des requêtes create spécifiques à chaque locale et persistez un parent release id pour une traçabilité de bout en bout.
3) Polling / Webhook
Suivez l'état de chaque locale indépendamment pour identifier rapidement les scénarios de succès partiel et d'échec partiel.
4) Publication
Publiez les locales qui passent les portes de QA/conformité et remettez en file les locales échouées avec une stratégie de retry bornée.
Exemples d'endpoint
POST /shorts/create— Créer des jobs de traitement spécifiques à chaque localeGET /shorts/:id/status— Suivre l'état du cycle de vie de chaque localeGET /shorts/:id— Récupérer la sortie localisée finalisée pour la sortie
Recommandations d'authentification
Gardez les clés API et les contrôles de déploiement uniquement dans les services backend. Segmentez les clés par environnement et restreignez étroitement l'accès au déploiement en production.
Rate limits et retries
Mettez en file les soumissions de locales par lots contrôlés, pas en rafales de fan-out complet. Utilisez un backoff exponentiel en cas de 429/5xx et plafonnez les retries.
Exemple de requête
POST /shorts/create
{
"fileUrl": "https://cdn.example.com/master-campaign.mp4",
"start": 30,
"end": 420,
"language": "ko",
"captionLanguage": "ja",
"preferredLength": "under60sec",
"layout": "auto"
}Exemple de réponse
200 OK
{
"data": {
"requestId": "665a1b2c3d4e5f6a7b8c9d0e",
"status": "processing",
"creditsUsed": 1,
"estimatedCompletionTime": "2026-03-10T07:00:00.000Z"
}
}Exemple de scénario d'erreur
500 Internal Server Error
{
"error": {
"code": "internal_error",
"message": "An internal error occurred. Please try again.",
"details": null
}
}Gestion des versions
Enregistrez les métadonnées de schéma/version pour chaque requête de locale afin que les régressions inter-locales soient diagnosticables après des changements d'API.
Support
Persistez parent release id + locale + requestId à chaque transition de statut pour une récupération rapide des incidents de lancement partiel.
Démarrage rapide
- Définissez la matrice de locales et la stratégie de déploiement dans la configuration backend.
- Créez une requête de traitement par locale en utilisant les champs language/captionLanguage.
- Effectuez un polling du statut et mettez à jour le tableau de sortie jusqu'à ce que chaque locale soit terminale.
- Récupérez les sorties finalisées et exécutez des vérifications QA spécifiques à chaque locale.
- Publiez immédiatement les locales validées et routez les locales échouées vers une file de retry bornée.
Workflow en 3 étapes
- Ingérez un asset source unique avec une matrice de locales cibles et une politique de déploiement.
- Traitez les jobs de locale de manière asynchrone avec un suivi de statut indépendant par locale.
- Publiez les locales finalisées via des files d'attente régionales tandis que les locales échouées sont routées vers des retries contrôlés.
Pourquoi les équipes choisissent Ssemble
- Conçu pour les équipes de canaux régionaux où la coordination des sorties est aussi critique que la qualité du contenu.
- Isole les échecs par locale afin qu'un seul problème ne bloque pas l'ensemble des lancements de campagne.
- Fonctionne avec l'automatisation de publication pour des workflows de distribution follow-the-sun.
Étape suivante
FAQ
Comment empêcher qu'une locale bloque toutes les régions ?
Utilisez des machines à états par locale et des portes de sortie afin que chaque locale puisse être publiée indépendamment, sauf si la politique exige une synchronisation de toutes les locales.
Faut-il soumettre toutes les locales en même temps ?
Généralement non. Un traitement par lots contrôlé protège les budgets de rate limit et simplifie le triage d'incidents lorsqu'un chemin de locale se dégrade.
Quel est le payload d'observabilité minimum ?
Suivez le parent release id, le code de locale, le requestId, les transitions de statut, le code d'erreur et le nombre de retries pour chaque job.
Quelles erreurs doivent être réessayées automatiquement ?
Réessayez les erreurs de transport transitoires, 429 et 5xx avec backoff. Échouez rapidement sur les erreurs de validation et routez pour correction de config/données.
La traduction et la publication peuvent-elles être séparées ?
Oui. De nombreuses équipes gardent la finalisation de traduction et la publication sur les canaux dans des files d'attente distinctes pour un meilleur contrôle et une sécurité de rollback.
Cela garantit-il des résultats équivalents sur toutes les locales ?
Aucune garantie ne doit être supposée. Mesurez le délai de finalisation, le taux d'échec et le taux de réussite au QA par locale et ajustez la politique de déploiement en conséquence.
