Passer à la navigation

Gestion des erreurs

Relancer la création d’une génération

Pour POST /v2/generate, envoyez une Idempotency-Key dès la première tentative et réutilisez-la avec le même payload à chaque relance. Le guide couvre les réponses rejouées, les conflits de payload, la rétention et toutes les erreurs IDEMPOTENCY_*. Une réponse perdue ou IDEMPOTENCY_OUTCOME_UNKNOWN n’autorise ni une nouvelle clé ni une relance sans clé. Une réponse au résultat inconnu peut inclure generationId ; interrogez-le quand il est disponible.

Sans clé, un timeout ou un échec de transport lors de la création peut laisser l’acceptation incertaine. Confirmez le résultat avant de soumettre à nouveau. Les conseils généraux sur les délais entre les tentatives ci-dessous ne rendent pas sûre la répétition d’une création sans clé.

Codes de statut HTTP

En appelant l’API sync. labs, vous pouvez rencontrer les codes de statut HTTP suivants. Ils sont renvoyés au niveau HTTP, avant tout code d’erreur propre à une génération.

Code de statutNomCause fréquenteRésolution
401UnauthorizedClé API invalide ou manquante. La variable d’environnement SYNC_API_KEY n’est pas définie ou la clé a été révoquée.Créez une nouvelle clé depuis le Dashboard. Vérifiez que la clé est incluse dans l’en-tête x-api-key.
402Payment RequiredLe compte ne peut pas démarrer une nouvelle génération à cause de l’état de la facturation ou du forfait. Causes fréquentes : générations de l’offre gratuite épuisées, aucun forfait payant actif pour un usage réservé aux plans payants, facture d’usage impayée, ou limite du forfait dépassée.Vérifiez votre forfait et vos factures sur la page Billing. Les comptes gratuits ont droit à 3 générations vidéo partagées par mois, de 15 s maximum chacune, les 3 pouvant utiliser sync-3. Passez à un forfait supérieur, réglez toute facture impayée ou attendez le prochain cycle de facturation.
413Payload Too LargeUn fichier envoyé directement vers POST /v2/generate dépasse la limite de 5 GiB par fichier. Le corps de la réponse contient errorCode: generation_input_validation_failed. Aucune génération n’est créée et aucun crédit n’est réservé.Utilisez un fichier plus petit, ou passez le fichier par URL publique. Les fichiers de 5 GiB maximum doivent aussi respecter la limite de taille de fichier de votre forfait.
429Too Many RequestsLimite de débit dépassée ; consultez la page Limites de débit pour les limites par point de terminaison.Mettez en place une temporisation exponentielle. Consultez la page Limites de débit pour plus de détails.
500Internal Server ErrorErreur côté serveur pendant le traitement.Réessayez après un court délai. Le corps de la réponse contient errorCode: internal_error et un requestId : incluez le requestId quand vous contactez le support, pour que nous puissions retrouver directement la requête en échec. Si le problème persiste, consultez status.sync.so pour l’état du service.
503Service UnavailableService temporairement indisponible pour maintenance, forte charge ou panne d’une dépendance fournisseur.Réessayez avec une temporisation exponentielle, en respectant l’en-tête Retry-After s’il est présent. Consultez status.sync.so pour les incidents en cours.
504Gateway TimeoutUn service sync. labs ou une dépendance fournisseur a expiré avant de pouvoir terminer la requête.Réessayez avec une temporisation exponentielle. Si le corps de la réponse inclut un requestId et que le timeout se répète, incluez-le quand vous contactez le support.

HTML 403 ou Cloudflare Access denied

Si une requête vers api.sync.so renvoie une page HTML mentionnant Cloudflare avec un HTTP 403, Access denied ou l’erreur 1010, traitez-la séparément des erreurs JSON de l’API ci-dessous. Un blocage Cloudflare peut survenir avant la validation de l’API : à lui seul, il n’établit donc pas que votre clé API, votre forfait ou vos médias sont invalides.

Arrêtez les relances répétées et contactez support@sync.so en indiquant la méthode et le point de terminaison de la requête, l’horodatage UTC, le Ray ID Cloudflare, la version du client/SDK et une réponse ou capture d’écran expurgée. Pour les uploads, incluez le type de contenu et la taille des fichiers. N’envoyez pas de clés API, de en-têtes d’autorisation ni d’URL de médias signées. Le support a besoin de la réponse précise pour enquêter ; ne supposez pas que tous les 403 ont la même cause.

Un 403 renvoyé par une URL d’upload de stockage présignée est un cas différent : consultez le guide de dépannage Asset Uploads pour les vérifications de type de contenu et d’expiration d’URL.

Codes d’erreur lisibles par machine

Chaque génération en échec contient un errorCode stable et lisible par machine, en plus du message error lisible par un humain. L’errorCode apparaît à la fois dans la réponse de Get Generation (GET /v2/generate/{id}) et dans le corps du webhook envoyé à la fin d’une tâche.

Basez votre gestion des erreurs sur errorCode, pas sur la chaîne error. Le message error est destiné aux humains et peut être reformulé avec le temps ; errorCode est un identifiant stable que vous pouvez utiliser sans risque dans un switch de votre code.

Une génération en échec se présente ainsi :

{
"id": "550e8400-e29b-41d4-a716-446655440000",
"status": "FAILED",
"error": "We could not read the video file metadata. Please try a different video file.",
"errorCode": "generation_input_video_invalid"
}

Les réponses d’erreur des points de terminaison de requête (assets, voices, TTS et rejets de generate à la soumission) ont la même forme lisible par machine, avec deux champs optionnels en plus : field nomme le champ de la requête à l’origine de l’échec (par exemple voiceId ou input[].assetId), et docsUrl pointe vers la page de documentation concernée. Les erreurs 500 non gérées incluent un requestId à transmettre au support, avec errorCode: internal_error :

{
"statusCode": 422,
"errorCode": "voice_not_found",
"message": "Voice with ID \"abc\" not found. Please verify the voice ID is correct.",
"suggestion": "List valid voice ids via GET /v2/voices. Cloned voice ids are UUIDs scoped to the organization that created them.",
"field": "voiceId"
}

Rechercher un code dans le catalogue d’erreurs

GET /v2/errors renvoie le catalogue complet des codes d’erreur, codes de génération et codes de requête API ci-dessous, sous forme de tableau d’objets { code, message, suggestion }. Le point de terminaison est non authentifié : aucun en-tête x-api-key n’est requis, vous pouvez donc obtenir, à l’exécution, la signification de chaque errorCode et une suggestion de correction.

curl https://api.sync.so/v2/errors

Une entrée typique se présente ainsi :

{
"code": "generation_input_video_invalid",
"message": "We could not read the video file metadata. Please try a different video file.",
"suggestion": "Re-encode the video to a supported format (e.g. h264 mp4) and resubmit."
}

Lire et résoudre un code d’erreur

Quand une génération échoue, lisez son errorCode et recherchez-le dans le catalogue renvoyé par GET /v2/errors.

# 1. Fetch the failed generation
curl https://api.sync.so/v2/generate/550e8400-e29b-41d4-a716-446655440000 \
-H "x-api-key: <SYNC_API_KEY>"
# 2. Look up the returned errorCode in the catalog (no auth required)
curl https://api.sync.so/v2/errors

Erreurs de validation lors de la soumission

Certaines requêtes sont rejetées lors de la soumission : l’API répond par une erreur sur la requête elle-même, avant tout rendu, au lieu d’accepter la tâche et de la faire échouer plus tard. Ces rejets renvoient un statut HTTP et un errorCode lisible par machine dans le corps de la réponse, pour que vous puissiez corriger la requête et la soumettre à nouveau sans gaspiller de génération.

StatutCode d’erreurCauseRésolution
400invalid_generation_idL’id passé à GET /v2/generate/{id} n’est pas un UUID.Utilisez l’id renvoyé par POST /v2/generate.
400unsupported_generation_id_formatL’id passé à GET /v2/generate/{id} utilise un format provider:id provenant d’un autre système.Utilisez l’UUID simple renvoyé par POST /v2/generate.
402generation_plan_duration_exceededLa durée de sortie dépasse la limite par génération de votre forfait. La vérification tient compte de sync_mode : cut_off coupe la sortie à la plus courte des pistes audio et vidéo avant la vérification de la limite.Passez à un forfait supérieur pour une limite plus longue, utilisez un sync_mode (comme cut_off) qui raccourcit la sortie, ou coupez la piste d’entrée la plus longue.
404generation_not_foundL’id passé à GET /v2/generate/{id} est un UUID valide, mais aucune génération ne lui correspond dans votre organisation.Vérifiez l’id, et assurez-vous d’utiliser la même clé API (organisation) que celle qui a créé la génération.
409generation_conflictLe controller a rejeté une soumission interne en double côté backend. Les créations publiques acceptent une Idempotency-Key optionnelle propre à l’organisation ; l’ID de génération reste attribué par le serveur.Ne relancez pas aveuglément après un échec réseau ambigu ; confirmez le résultat de la soumission avant de relancer.
409DUPLICATE_SUBMISSIONUne requête par clé API sans Idempotency-Key est identique à une requête envoyée par votre organisation dans les 60 dernières secondes, et cette requête d’origine n’a pas échoué. Aucune nouvelle génération n’est créée.Interrogez le generationId renvoyé. Pour créer volontairement des générations identiques, envoyez une Idempotency-Key unique avec chacune. Consultez Requests without a key.
422invalid_asset_id_formatUn input[].assetId n’est pas un UUID valide.Utilisez l’id renvoyé par POST /v2/assets, ou fournissez plutôt une url.
422asset_not_foundUn input[].assetId ne correspond à aucun asset accessible avec votre clé.Utilisez un id d’asset de votre organisation (GET /v2/assets) ; les ids d’autres organisations ne sont pas visibles.
422generation_input_asset_type_mismatchLe type réel d’un asset ne correspond pas à l’emplacement d’entrée auquel il a été fourni (par exemple, un asset audio placé dans un emplacement vidéo).Assurez-vous que le type de chaque entrée correspond à l’asset passé, et que l’asset est du type de média attendu par cet emplacement.
422generation_input_too_many_visualLa requête contient plus d’une entrée visuelle ; une seule vidéo ou image est autorisée par génération.Envoyez exactement une entrée vidéo ou image.
422generation_input_segments_invalidLe tableau segments est invalide : des segments se chevauchent, le startTime d’un segment est supérieur à son endTime, ou deux segments réutilisent le même refId. Ce code est aussi renvoyé pour une requête lipsync: false ou outputAudio invalide, par exemple quand chaque segment définit lipsync: false, ou quand plusieurs entrées audio sont envoyées sans outputAudio.Vérifiez vos segments : évitez les chevauchements, assurez-vous que startTime < endTime, et utilisez un refId unique par segment. Pour lipsync: false et outputAudio, consultez Conserver des segments sans synchronisation labiale.
422generation_input_dub_audio_conflictLa requête fournit à la fois dubParams et une entrée audio ou texte explicite. Les deux sont mutuellement exclusifs.Envoyez l’un ou l’autre : soit dubParams (pour doubler), soit une entrée audio/texte explicite, pas les deux.
422cost_estimate_unavailableEstimate Cost (POST /v2/generations/estimate) n’a pas pu renvoyer de prix. Aucune génération n’est créée. La validation des champs de requête renvoie 400.Vérifiez que duration et fps (optionnel) sont des nombres finis et positifs. Si des entrées valides échouent encore, réessayez plus tard ou contactez le support avec l’ID de requête.
429concurrency_limit_reachedVous avez trop de générations en cours par rapport à la limite de concurrence de votre forfait.Attendez la fin des générations en cours, ou passez à un forfait supérieur pour exécuter davantage de générations en parallèle. Consultez Limites de débit.
429rate_limit_exceededVotre débit de requêtes par clé a été dépassé (par exemple sur les requêtes TTS, de clonage de voix ou d’upload).Réduisez votre débit de requêtes et mettez en place une temporisation exponentielle. Consultez Limites de débit.
503generation_media_probe_unavailable / generation_media_probe_timeoutUne vérification des médias d’entrée était indisponible ou a expiré.Réessayez en espaçant les tentatives ; vérifiez que l’hôte des médias est joignable. Incluez l’ID de requête quand vous contactez le support.
503controller_unavailable / controller_dependency_errorLe service de génération (ou l’une de ses dépendances) est temporairement indisponible au moment de la soumission.Pour une création avec clé, relancez avec la même clé et les mêmes entrées, en respectant Retry-After. Pour une création sans clé, confirmez l’acceptation avant de soumettre à nouveau.
503generation_admission_pausedLes nouvelles requêtes de génération sont temporairement suspendues pour maintenance. La requête est rejetée avant tout traitement. Les générations déjà acceptées continuent d’être traitées, et vous pouvez toujours consulter leur statut.Réessayez après l’intervalle Retry-After. Pour une création avec clé, gardez la même Idempotency-Key et les mêmes entrées.
503generation_admission_unavailableL’API ne peut pas confirmer que les nouvelles requêtes de génération sont acceptées : elle rejette donc la requête avant tout traitement.Réessayez après l’intervalle Retry-After. Pour une création avec clé, gardez la même Idempotency-Key et les mêmes entrées.
504controller_timeoutLe service de génération a mis trop de temps à accepter la tâche.Pour une création avec clé, relancez avec la même clé et les mêmes entrées, en respectant Retry-After. Pour une création sans clé, confirmez l’acceptation avant de soumettre à nouveau.

Une erreur à la soumission renvoie errorCode dans la réponse HTTP. Les échecs de validation peuvent survenir avant la création de la génération, mais une soumission incertaine peut déjà avoir une génération. Interrogez generationId quand il est fourni et suivez les recommandations de récupération idempotente avant de relancer.

Les erreurs de limite de débit et de dépendance (429/503/504) reprennent aussi leurs consignes de relance dans des en-têtes : Retry-After (en secondes) et, pour les 429 de concurrence, X-Sync-Concurrency-Limit et X-Sync-Active-Generations.

Codes d’erreur des requêtes API

Au-delà des échecs de génération, les points de terminaison assets, voices, TTS et de téléchargement de génération renvoient leurs propres valeurs errorCode stables dans les réponses d’erreur. Le cas échéant, le corps de la réponse contient aussi field (le champ de requête en cause) et docsUrl (un lien vers la page de documentation concernée). Tous ces codes figurent dans le catalogue d’erreurs (GET /v2/errors).

Assets

StatutCode d’erreurCauseRésolution
422project_not_foundLe projectId n’existe pas dans votre organisation (mauvaise organisation, supprimé ou mal saisi).Omettez projectId, ou utilisez un id de projet appartenant à votre organisation.
404asset_not_foundAucun asset avec cet id n’existe dans votre organisation.Utilisez un id d’asset renvoyé par POST /v2/assets ou GET /v2/assets. Les ids d’assets d’une autre organisation ne sont pas visibles.
403asset_forbiddenVous pouvez voir cet asset mais n’avez pas la permission de le modifier ou de le supprimer.Seul le propriétaire de l’asset ou un admin/propriétaire de l’organisation peut le modifier.
422invalid_asset_id_formatUn assetId (y compris input[].assetId sur generate) n’est pas un UUID valide.Utilisez l’id renvoyé par POST /v2/assets, ou fournissez plutôt une url.
422uploaded_file_not_foundAucun octet de fichier n’a été trouvé à l’URL d’upload présignée.Faites un PUT du fichier vers l’uploadUrl renvoyée par POST /v2/assets/upload avant d’enregistrer l’asset.
422file_not_in_org_storageL’URL enregistrée ne se trouve pas dans le stockage sync. labs de votre organisation.Envoyez d’abord via POST /v2/assets/upload, puis enregistrez l’url renvoyée.
422file_size_exceeds_plan_limitLe fichier dépasse la taille maximale de votre forfait.Envoyez un fichier plus petit ou passez à un forfait supérieur.

Voix et TTS

StatutCode d’erreurCauseRésolution
422 / 404voice_not_foundLe voiceId ne correspond à aucune voix prédéfinie ou clonée de votre organisation. Renvoyé en 422 sur POST /v2/tts et les entrées texte de génération, en 404 sur GET /v2/voices/{id} et DELETE /v2/voices/{id}.Listez les ids valides via GET /v2/voices. Les ids de voix clonées sont des UUID propres à l’organisation qui les a créées.
400 / 422voice_verification_requiredLa voix sélectionnée nécessite une vérification ElevenLabs avant de pouvoir servir à la synthèse. Renvoyé sur POST /v2/tts et les entrées texte de génération : normalement en 422 par la vérification préalable à la synthèse, ou en 400 quand cette vérification était indisponible et que la voix est rejetée pendant la synthèse.Si la voix provient de votre propre compte ElevenLabs connecté, effectuez la vérification dans ElevenLabs (lien sous Settings > Integrations). Sinon, choisissez une autre voix, ou contactez le support Sync pour une voix gérée par Sync.
400 / 422voice_blockedElevenLabs a bloqué la voix sélectionnée. Renvoyé sur POST /v2/tts et les entrées texte de génération : normalement en 422 par la vérification préalable à la synthèse, ou en 400 quand cette vérification était indisponible et que la voix est rejetée pendant la synthèse.Choisissez une autre voix : une voix bloquée ne peut pas servir à la synthèse. Si elle provient de votre propre compte ElevenLabs connecté (Settings > Integrations), contactez ElevenLabs. Sinon, pour une voix gérée par Sync, contactez le support Sync.
400voice_access_deniedElevenLabs a refusé l’accès à la voix sélectionnée : un refus d’accès générique, pas spécifiquement un état de vérification ou de blocage. N’apparaît que pendant la synthèse sur POST /v2/tts et les entrées texte de génération.Choisissez une autre voix. Si la voix provient de votre propre compte ElevenLabs connecté (Settings > Integrations), vérifiez ses paramètres d’accès dans ElevenLabs ; sinon, pour une voix gérée par Sync, contactez le support Sync.
422voice_sample_not_accessibleL’asset d’échantillon de clonage est introuvable ou inaccessible.Utilisez un id d’asset audio ou vidéo de votre organisation.
422voice_sample_type_unsupportedL’asset d’échantillon de clonage n’est ni audio ni vidéo.Clonez à partir d’un asset AUDIO ou VIDEO.
422voice_sample_upload_requiredL’url de l’échantillon de clonage n’est pas hébergée dans le stockage sync. labs.Envoyez d’abord via POST /v2/assets/upload, puis clonez à partir de l’assetId ou de l’url renvoyés.
422voice_sample_extraction_failedAucune piste audio n’a pu être extraite de l’échantillon vidéo.Vérifiez que la vidéo a une piste audio et est dans un format pris en charge.
400voice_sample_too_shortL’échantillon est trop court pour le clonage.Utilisez un échantillon plus long avec une parole claire (idéalement 30 secondes ou plus).
400voice_sample_invalidL’échantillon n’a pas pu être traité, ou le même échantillon a été ajouté plusieurs fois.Utilisez un fichier audio valide avec une parole claire, et retirez tout échantillon en double.
403voice_clone_limit_reachedTous les emplacements de clonage de voix de votre forfait sont utilisés.Supprimez une voix via DELETE /v2/voices/{id} ou passez à un forfait supérieur.
429voice_clone_busyUn autre clonage de voix partagé réserve la capacité du fournisseur.Respectez Retry-After et réessayez après le délai indiqué.
413voice_sample_source_too_largeLa vidéo source dépasse la limite de 1 GiB pour la préparation du clonage.Coupez la vidéo ou utilisez une source plus petite.
409voice_name_conflictVous avez déjà une voix portant ce nom.Choisissez un autre nom, ou supprimez d’abord la voix existante via DELETE /v2/voices/{id}.
400elevenlabs_api_key_invalidVotre clé API ElevenLabs connectée (bring-your-own) est invalide ou révoquée.Reconnectez une clé valide dans Settings > Integrations, ou retirez-la pour revenir aux voix partagées.
402elevenlabs_quota_exceededLe quota de votre propre compte ElevenLabs est épuisé.Vérifiez votre abonnement ElevenLabs, ou attendez la réinitialisation de son quota.
503 / 504elevenlabs_service_unavailableLe service de voix ElevenLabs est temporairement indisponible. Renvoyé en 504 pour les timeouts du fournisseur, et en 503 pour les autres pannes du fournisseur sur POST /v2/tts et les entrées text de génération sans clé. Les résultats incertains avec clé utilisent IDEMPOTENCY_OUTCOME_UNKNOWN.Relancez la requête en espaçant les tentatives. Si l’échec persiste, contactez le support avec l’id de requête.

Téléchargements

GET /v2/generations/{id}/download renvoie une URL pour télécharger la sortie d’une génération terminée. Les générations manquantes, supprimées ou d’une autre organisation renvoient generation_not_found (404), comme décrit plus haut. Une clé API manquante, invalide ou révoquée renvoie 401, et un id qui n’est pas un UUID renvoie 400. Les codes propres au téléchargement sont :

StatutCode d’erreurCauseRésolution
409generation_not_readyLa génération est encore en attente ou en cours de traitement, sa sortie n’est donc pas prête à être téléchargée.Interrogez GET /v2/generate/{id} jusqu’à ce qu’il indique COMPLETED, puis redemandez l’URL de téléchargement.
422generation_not_downloadableLa génération a échoué ou a été rejetée, elle n’a donc aucune sortie à télécharger.Inspectez le statut et l’erreur de la génération avec GET /v2/generate/{id} ; corrigez l’entrée et soumettez à nouveau si nécessaire.
404generation_output_unavailableLa génération n’a aucune référence de sortie éligible, ou le fichier de sortie stocké est manquant.Ce point de terminaison ne recrée pas les sorties. Contactez le support si une génération terminée n’a plus sa sortie.
503generation_download_unavailableL’URL de téléchargement n’a pas pu être préparée.Réessayez avec une temporisation exponentielle. Si l’échec persiste, contactez le support avec l’id de requête.

Capacité d’upload batch

Un upload batch multipart peut renvoyer 503 avec errorCode: upload_capacity_unavailable. Aucun batch n’a été créé. Relancez la même requête après le nombre de secondes indiqué dans Retry-After. Vous pouvez aussi envoyer les enregistrements dans un corps JSON rows.

Découpes audio

POST /v2/audio-trims et GET /v2/audio-trims/{id} préparent un asset audio plus court pour une vidéo partielle. Ces codes ne figurent pas dans le catalogue d’erreurs.

StatutCode d’erreurCauseRésolution
422audio_trim_source_not_hostedL’audio est hébergé hors du stockage sync. labs.Envoyez l’audio avec POST /v2/assets/upload, puis découpez-le par assetId.
422audio_trim_source_not_allowedLe sourceUrl se trouve dans le stockage sync. labs, mais pas dans celui de votre organisation.Découpez un audio appartenant à votre organisation, ou envoyez-le avec POST /v2/assets/upload et découpez-le par assetId.
429audio_trim_rate_limitedVotre organisation a déjà 4 découpes en cours, ou en a lancé 60 au cours de la dernière heure.Attendez la fin d’une découpe en cours, puis réessayez.

Une découpe qui ne parvient pas à décoder ou couper l’audio se termine avec status: failed et errorCode: audio_trim_failed sur GET /v2/audio-trims/{id}. Vérifiez que la source est un fichier audio lisible, puis lancez une nouvelle découpe avec une nouvelle Idempotency-Key.

Réutiliser une Idempotency-Key avec un corps différent renvoie 409. Une Idempotency-Key manquante, ou qui ne fait pas 1 à 128 caractères parmi [A-Za-z0-9._~-], renvoie 400. Une source audio ou une découpe qui n’existe pas ou à laquelle vous n’avez pas accès renvoie 404. Envoyez d’abord les sources externes et découpez-les par assetId.

Générations rejetées et en échec

REJECTED et FAILED sont des statuts finaux. Inspectez errorCode et error dans la réponse de génération ou le webhook. REJECTED signifie que la requête ou le compte doit être corrigé avant une nouvelle tentative. FAILED signifie que le traitement s’est arrêté à cause d’une erreur opérationnelle. Suivez la procédure de récupération du code renvoyé, et contactez le support si le problème persiste.

NO_OP est aussi un statut final : la génération s’est terminée, mais aucune image n’a été synchronisée, la sortie est donc la vidéo d’entrée inchangée. Elle porte l’un des codes de lip sync omis. Consultez Génération terminée sans synchronisation labiale.

Une requête refusée avant l’existence d’une génération renvoie son erreur dans la réponse HTTP. Arrêtez d’interroger une génération dès qu’elle atteint un statut final (COMPLETED, NO_OP, FAILED ou REJECTED). Pour les relances, suivez Idempotent requests.

Que signifient les codes d’erreur de l’API ?

Les codes ci-dessous sont regroupés par catégorie, les plus fréquents d’abord.

Erreurs de validation des entrées

generation_unsupported_model

Message : “The requested model is not supported for this operation.”

Description : Cette erreur est renvoyée quand vous essayez d’utiliser un modèle qui n’est pas compatible avec l’opération ou le point de terminaison API actuel.

Résolution :

  1. Consultez la documentation des modèles pour voir quels modèles sont pris en charge pour cet appel API précis.
  2. Modifiez votre requête pour utiliser un modèle pris en charge.
  3. Si vous pensez qu’il s’agit d’une erreur, contactez notre équipe support en détaillant votre cas d’usage.

generation_plan_duration_exceeded et generation_model_duration_exceeded

Message : “The input exceeds your plan’s output-duration limit.” ou “The input exceeds the selected model’s duration limit.”

Description : Il n’y a pas de limite fixe de durée audio pour le lip sync. La sortie la plus longue que vous pouvez générer dépend de votre forfait (consultez Facturation), et certains modèles ont leur propre plafond, comme 15 secondes pour react-1. Un rejet à la soumission renvoie 402 generation_plan_duration_exceeded, décrit dans Erreurs de validation lors de la soumission.

Résolution :

  1. Coupez ou découpez le média pour que la sortie respecte la limite.
  2. Pour une limite de modèle, choisissez un modèle avec une limite plus élevée (consultez List Models).
  3. Pour une limite de plan, passez à un forfait supérieur pour des générations plus longues.

Les scripts de synthèse vocale sont validés à la soumission : script accepte de 1 à 5 000 caractères. Consultez Text-to-Speech.

generation_input_validation_failed

Message : “Something in your input is invalid. Please check your media and settings, then try again.”

Description : Cette erreur survient quand les données d’entrée fournies ne respectent pas les critères de validation requis pour le traitement. Causes fréquentes : une URL d’entrée ou un assetId qui ne mène pas à un média récupérable, ou un média dans un format non pris en charge.

Résolution :

  1. Vérifiez que vos données d’entrée respectent toutes les exigences et spécifications de l’API.
  2. Vérifiez que tous les champs requis sont présents et correctement formatés.
  3. Vérifiez que les formats de fichier, les tailles et les autres paramètres sont dans les limites acceptées.
  4. Si le problème persiste, contactez notre équipe support avec des détails sur vos données d’entrée pour obtenir de l’aide.

generation_input_audio_invalid

Message : “We could not read the audio file metadata. Please try a different audio file.”

Description : Cette erreur survient quand les métadonnées du fichier audio sont manquantes ou illisibles. Le code équivalent pour la vidéo est generation_input_video_invalid, que vous pouvez corriger de la même façon en réencodant en MP4 H.264. Causes typiques : fichiers audio corrompus, en-têtes endommagés, ou fichiers issus d’outils qui produisent des métadonnées non standard.

Résolution :

  1. Réencodez votre fichier audio avec un outil standard comme FFmpeg pour garantir des métadonnées correctement formatées :
    ffmpeg -i input.wav -c:a pcm_s16le output.wav
  2. Vérifiez que votre fichier audio s’ouvre et se lit correctement dans un lecteur multimédia.
  3. Vérifiez que le fichier audio n’a pas été corrompu pendant le téléchargement ou le transfert.
  4. Si le problème persiste, essayez de convertir votre audio dans un autre format pris en charge (WAV, MP3, OGG, FLAC) et soumettez-le à nouveau.

generation_input_face_selection_invalid

Message : “We could not use the selected speaker face for this video. Please select the face again or try auto-detect.”

Description : Cette erreur survient quand le visage du locuteur sélectionné manuellement ne peut pas être utilisé pour la génération. Le visage sélectionné n’est peut-être pas détecté dans la vidéo, les coordonnées fournies peuvent se trouver hors du cadre de la vidéo, ou la sélection du locuteur actif peut être invalide.

Résolution :

  1. Relancez la détection de visage et sélectionnez à nouveau le locuteur, en vous assurant que le visage est bien visible dans l’image choisie.
  2. Vérifiez que les coordonnées ou bounding boxes fournies manuellement se trouvent dans les dimensions de la vidéo.
  3. Vous pouvez aussi désactiver la sélection manuelle du locuteur pour laisser le système détecter automatiquement le locuteur actif, puis soumettre à nouveau.

Erreurs de la Batch API

Les erreurs de validation batch sont des réponses 400 qui contiennent uniquement un message ; elles n’ont pas d’errorCode. Les refus liés à l’accès, au plan et à la capacité utilisent les codes ci-dessous. Les dry runs nécessitent la même approbation de l’organisation et le même plan que la création de batch.

L’accès batch n’est pas activé (batch_access_not_enabled)

Statut : 403

Description : Votre organisation n’a pas été approuvée pour créer des batches. L’accès est désactivé par défaut, y compris pour les nouveaux abonnements Scale. Les dry runs nécessitent la même approbation. Les batches existants continuent d’être traités et restent consultables quand l’accès à la création est retiré.

Résolution : Contactez support@sync.so pour demander l’accès pour votre organisation. Passer à un forfait supérieur n’active pas l’accès automatiquement.

Le batch nécessite le plan Scale (plan_feature_unavailable)

Statut : 402

Description : La Batch API nécessite l’approbation de l’organisation et un forfait Scale ou supérieur (Scale, Enterprise, forfaits partenaires et programmes). Les autres forfaits et les comptes gratuits ne peuvent pas créer de batches. Le corps de la réponse contient requiredPlan et une billingUrl : requiredPlan vaut scale, ou enterprise sur les plans à crédits, car aucun forfait à crédits en libre-service n’inclut le batch.

Résolution :

  1. Passez au plan Scale, ou contactez l’équipe commerciale au sujet d’Enterprise, et demandez l’approbation de votre organisation pour utiliser la Batch API.
  2. Pour exécuter quelques générations à la fois sans batch, envoyez des requêtes POST /v2/generate en parallèle dans la limite de votre concurrence. Consultez When to use batch, and when not to.

Limite de concurrence batch (concurrency_limit_reached)

Statut : 429, avec les en-têtes Retry-After et X-Sync-Concurrency-Limit

Message : “Batch concurrency limit reached. You have X active batches and your plan allows Y. Please wait for existing batches to complete or upgrade your plan for higher limits.”

Description : Vous exécutez déjà autant de batches que votre forfait l’autorise. Chaque batch actif occupe un emplacement d’une limite de batches égale à la limite de concurrence de votre forfait. Le corps de la réponse contient activeBatches, concurrencyLimit et retryAfterSeconds.

Résolution :

  1. Attendez retryAfterSeconds, ou la fin d’un batch actif.
  2. Vérifiez vos batches actifs avec GET /v2/batch.

Messages de validation batch

StatutMessageCorrection
400Input file is required / Input file cannot be emptyEnvoyez le JSONL dans le champ input, ou utilisez un corps JSON rows.
400File size exceeds the maximum limit of 5MBLe batch dépasse 5 Mo tel qu’envoyé ou après l’expansion de ses lignes d’édition de dialogue. Répartissez les enregistrements sur plusieurs batches.
400Number of records exceeds the maximum limit of NEnvoyez au plus N enregistrements. N vaut 500 par défaut, ou la limite propre à votre compte.
400Input file must contain at least N records. Found X record(s).Un batch nécessite au moins 20 enregistrements ; envoyez-en moins de 20 avec POST /v2/generate.
400Invalid JSON at line X: ...Faites de chaque ligne un objet JSON valide.
400Duplicate request_id found at line X: ...Utilisez un request_id unique pour chaque enregistrement.
400Record at line X: request_id is required / payload is requiredAjoutez le champ manquant.
400Record at line X: endpoint must be '/v2/generate'Définissez "endpoint": "/v2/generate".
400Record at line X: Invalid payload - ...Corrigez le payload pour qu’il soit un corps POST /v2/generate valide.

Les numéros de ligne comptent les enregistrements non vides ; avec un corps JSON rows, la ligne N correspond à rows[N-1].

Refus de lignes d’édition de dialogue

Exemple : {"statusCode": 422, "errorCode": "dialogue_edit_not_found", "lineNumber": 3, "message": "Record at line 3: The dialogue edit was not found in this organization."}

Description : Les lignes de batch qui contiennent dialogueEdit (accès anticipé) sont vérifiées à la soumission, y compris avec dry_run. Si une ligne ne peut pas être rendue, aucun batch n’est créé. La réponse contient le même errorCode que celui renvoyé par POST /v2/generate pour cet aperçu, comme dialogue_edit_not_found, dialogue_edit_not_completed, dialogue_edit_source_mismatch ou dialogue_edit_batch_mixed_sources, ainsi que le lineNumber de la première ligne en échec. Les numéros de ligne comptent les enregistrements non vides ; avec un corps JSON rows, la ligne N correspond à rows[N-1]. Les autres erreurs d’enregistrement batch, comme un JSON invalide, indiquent la ligne uniquement dans message.

Résolution :

  1. Trouvez la ligne à lineNumber et corrigez-la comme décrit dans Dialogue edit refusals.
  2. Validez à nouveau avec dry_run jusqu’à ce que la réponse soit {"status": "VALIDATED"}.

Lip sync omis

Ces codes accompagnent le statut NO_OP. La génération s’est terminée et son outputUrl est la vidéo d’entrée inchangée, avec la parole générée ou l’audio doublé le cas échéant. Le lip sync n’est pas facturé. Consultez Génération terminée sans synchronisation labiale.

generation_lipsync_skipped_no_face

Message : “No face was detected in the video, so nothing was lip-synced.”

Résolution : Utilisez une vidéo où le visage du locuteur est bien visible et suffisamment grand dans le cadre, puis soumettez à nouveau.

generation_lipsync_skipped_speaker_not_found

Message : “No face was found at the selected speaker position, so nothing was lip-synced.”

Résolution : Sélectionnez un point sur le visage du locuteur dans une image où il est visible, ou utilisez la détection automatique du locuteur, puis soumettez à nouveau.

generation_lipsync_skipped_no_active_speaker

Message : “Automatic speaker detection found no one speaking, so nothing was lip-synced.”

Résolution : Sélectionnez vous-même le locuteur avec un numéro d’image et des coordonnées, puis soumettez à nouveau. Consultez Sélection du locuteur.

generation_lipsync_skipped

Message : “No frames were lip-synced, so the video is unchanged.”

Résolution : Utilisez une vidéo où le visage du locuteur est bien visible, puis soumettez à nouveau.

Erreurs système et de traitement

generation_pipeline_failed

Message : “The generation failed while processing. Please try again or contact support if this keeps happening.”

Description : Cette erreur indique un échec dans l’une des étapes de traitement internes du pipeline de génération.

Résolution :

  1. Vérifiez que vos données d’entrée respectent toutes les spécifications requises.
  2. Essayez de soumettre à nouveau la requête, car certaines erreurs de pipeline peuvent être temporaires.
  3. Si le problème continue, contactez notre équipe support avec des détails sur votre requête et le message d’erreur précis pour une analyse plus poussée.

generation_unknown_error

Message : “Something went wrong while processing this generation. Please try again.”

Description : La génération a échoué pour une raison qui n’a pas de code plus précis.

Résolution :

  1. Relancez la génération.
  2. Si elle échoue de façon répétée, contactez le support avec l’ID de génération.

generation_infra_storage_error

Message : “An error occurred while accessing the storage on infra layer.”

Description : Cette erreur indique un problème d’accès ou de gestion des ressources de stockage pendant le processus de génération. Elle peut survenir à cause de problèmes temporaires du service de stockage ou de problèmes de connectivité.

Résolution :

  1. Relancez votre requête après un court délai, car les erreurs de stockage sont souvent temporaires.
  2. Assurez-vous que vos fichiers d’entrée sont accessibles et non corrompus.
  3. Si le problème persiste, contactez notre équipe support, car il peut s’agir d’un problème d’infrastructure plus large.

generation_infra_resource_exhausted

Message : “The infra resources are exhausted.”

Description : Cette erreur survient quand les ressources d’infrastructure nécessaires au traitement de votre requête sont temporairement indisponibles ou saturées.

Résolution :

  1. Attendez quelques minutes et relancez votre requête, car la disponibilité des ressources fluctue.
  2. Envisagez de soumettre votre requête en heures creuses, quand les ressources sont plus disponibles.
  3. Si vous rencontrez souvent cette erreur, contactez notre équipe support pour discuter de vos habitudes d’usage et des solutions possibles.

generation_infra_service_unavailable

Message : “The infra service is unavailable.”

Description : Cette erreur indique qu’un ou plusieurs services d’infrastructure nécessaires au traitement sont temporairement indisponibles. Cela peut être dû à une maintenance, à des problèmes de connectivité ou à des pannes de service.

Résolution :

  1. Consultez notre page de statut pour voir s’il y a des problèmes de service ou des fenêtres de maintenance en cours.
  2. Relancez votre requête après un court délai, car les problèmes de disponibilité de service sont généralement temporaires.
  3. Si le service reste indisponible pendant une période prolongée, contactez notre équipe support pour obtenir des nouvelles et de l’aide.

Conseils généraux de dépannage

  1. Vérifiez votre clé API : assurez-vous d’utiliser la bonne clé API et qu’elle n’a pas été révoquée.
  2. Vérifiez le format de la requête : contrôlez que votre requête API est correctement formatée et inclut tous les paramètres requis.
  3. Consultez les limites de débit : assurez-vous de ne pas avoir dépassé vos limites de débit API.
  4. Vérifiez l’état du service : consultez notre page de statut pour voir s’il y a des problèmes de service en cours.
  5. Consultez la documentation : notre documentation API a peut-être été mise à jour avec de nouvelles informations ou des changements.

Signaler une erreur peu claire ou un contournement

Si une erreur n’indiquait pas quoi corriger, si un résultat était incorrect ou si vous avez eu besoin d’un contournement, signalez-le avec Submit Feedback (POST /v2/feedback).

  • Envoyez un signalement par problème, avec un kind (confusing_error, bug, missing_capability, workaround, docs ou other) et un message de 4 000 caractères maximum qui inclut le texte exact de l’erreur.
  • Ajoutez l’errorCode et le generationId quand vous les avez.
  • L’équipe sync. examine les signalements tous les jours.
  • L’appel renvoie 202 avec un id de référence, ne modifie ni ne relance aucune tâche, et est limité à 30 signalements par minute.
  • Le serveur MCP expose le même signalement via l’outil feedback_send.
curl -X POST https://api.sync.so/v2/feedback \
-H "x-api-key: $SYNC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"kind": "confusing_error",
"severity": "major",
"message": "POST /v2/generate returned generation_input_video_inaccessible for a presigned URL that plays in a browser.",
"errorCode": "generation_input_video_inaccessible",
"generationId": "6533643b-acbb-4c4f-a5b3-5ba2e5ab6b5f"
}'

Trouver les ID de génération depuis Studio

Si vous avez besoin de trouver un ID de génération pour le dépannage, vous pouvez facilement le retrouver dans l’interface de Studio. Les modes Studio Pro et Studio Lite suivent le même processus de base :

Pour le mode Studio Pro : cliquez d’abord sur le bouton “History” dans l’interface de Studio, puis suivez les étapes ci-dessous.

Pour le mode Studio Lite : passez directement aux étapes ci-dessous.

  1. Repérez votre génération : trouvez la miniature de la génération dont vous avez besoin de l’ID
  2. Ouvrez le menu : survolez la miniature de la génération et cliquez sur le menu à trois points qui apparaît
  3. Copiez le Job ID : sélectionnez “copy job id” dans le menu déroulant
Capture d’écran montrant comment copier le job ID depuis le menu à trois points de Studio

Pour Agent Mode : dans Agent Mode, vous pouvez trouver les ID de génération de deux façons :

  1. Barre latérale Sessions : cliquez sur le menu déroulant (trois points) à côté d’une session dans la barre latérale et sélectionnez “Copy Job ID”
  2. Carte d’erreur : quand une génération échoue, cliquez directement sur le bouton “Copy Job ID” de la carte de notification d’erreur

Cet ID de génération peut ensuite être utilisé pour contacter le support ou pour effectuer des appels API afin de récupérer les détails d’une génération précise.

Si vous rencontrez toujours des problèmes après ces étapes, consultez la page Troubleshooting pour les problèmes courants et leurs solutions, ou contactez notre équipe support.

Ressources associées

  • Limites de débit: comprenez les limites de débit de l’API et comment gérer les requêtes limitées
  • Webhooks: recevez des notifications en temps réel quand des tâches de génération se terminent ou échouent
  • Démarrage rapide: lancez votre premier appel à l’API sync. labs

Base de connaissances du support

Questions fréquentes

Une erreur 400 signifie que votre requête contient une entrée invalide. Causes fréquentes : URL mal formée, format de média non pris en charge, champs requis manquants ou valeur hors de la plage autorisée. Un média plus long que ce que votre forfait autorise est rejeté avec 402 generation_plan_duration_exceeded, pas 400. Consultez le code d’erreur précis dans le corps de la réponse pour savoir quoi corriger.

Une génération au statut PENDING attend des ressources de traitement. En période de forte demande, les tâches peuvent patienter brièvement en file avant de démarrer. Si une génération reste longtemps en PENDING, interrogez son ID existant ou contactez le support. Ne créez pas de génération de remplacement simplement parce qu’elle est encore en attente.

Quand une génération se termine en FAILED ou REJECTED, relancez avec la même clé et les mêmes entrées : la relance démarre une nouvelle génération, admise et facturée comme une première requête. Pour un timeout ou un résultat de soumission inconnu, gardez la clé et les entrées d’origine ; ne lancez pas de remplacement. Consultez Requêtes idempotentes.