Déboguer une requête Seedance en échec
- 1
Lisez le code, pas le message
Basez votre logique sur code (erreurs de requête) ou job.errorCode (erreurs de tâche) ; les messages peuvent changer, les codes non.
- 2
Vérifiez d'abord les limites
La plupart des 400 viennent d'une durée, d'une résolution ou d'un format d'image que le modèle ne propose pas. GET /v1/models liste les limites de chaque modèle.
- 3
Respectez les 429
Attendez le nombre de secondes indiqué dans Retry-After avant de renvoyer.
- 4
Renvoyez sans risque
Après un dépassement de délai, renvoyez avec la même Idempotency-Key. Après un prompt refusé, modifiez-le et utilisez une nouvelle clé.
Erreurs de requête (l'appel HTTP échoue)
| Code | Statut | Signification | Solution |
|---|---|---|---|
| invalid_api_key | 401 | La clé est absente, erronée ou révoquée. | Envoyez Authorization: Bearer <key>. Créez une nouvelle clé si elle a été révoquée. |
| insufficient_balance | 402 | Pas assez de tokens pour le coût estimé. | Rechargez dans l'onglet Billing. Le champ data.top_up_url y mène. |
| account_not_active | 403 | Le compte développeur est suspendu. | Contactez le support. |
| scope_missing | 403 | La clé n'a pas le scope requis par cet endpoint. | Utilisez une clé qui a ce scope. |
| job_not_found | 404 | Aucune tâche avec cet id pour le compte de cette clé. | Vérifiez l'id ; les tâches sont privées au compte. |
| character_not_found | 404 | L'id ou le slug du personnage n'existe pas. | Listez les personnages avec GET /v1/characters. |
| upload_not_found | 404 | L'upload_id n'existe pas dans cet espace de travail. | Recréez l'upload. |
| reference_upload_not_developer | 400 | The upload_id is a file uploaded on the website, not through the API. | Upload this file with /v1/uploads first. |
| reference_upload_not_found | 404 | Un upload_id de référence n'existe pas dans cet espace de travail. | Envoyez à nouveau le fichier et utilisez le nouvel upload_id. |
| video_edit_source_not_found | 404 | Le source_video_upload_id n'existe pas. | Envoyez le clip avec upload_type VIDEO. |
| upload_in_use | 409 | Une tâche en file d'attente ou en cours utilise encore cet upload. | Supprimez-le une fois la tâche terminée. |
| character_pending | 409 | Le personnage est encore en cours de vérification. Rien n'a été réservé. | Attendez retry_after secondes, puis réessayez. |
| upload_too_large | 413 | Le fichier dépasse la taille maximale pour son type. | Images 50 Mo, vidéo 200 Mo, audio 15 Mo. |
| character_registration_failed | 422 | L'image du personnage n'a pas passé la vérification. | Enregistrez à nouveau le personnage avec une autre image. |
| rate_limited | 429 | Trop de requêtes dans la fenêtre de temps. | Attendez le nombre de secondes indiqué dans l'en-tête Retry-After. |
| prompt_required | 400 | Aucun prompt (ou texte pour la synthèse vocale) n'a été envoyé. | Ajoutez un prompt. |
| prompt_too_long | 400 | Le prompt dépasse la limite du modèle. | Raccourcissez-le ; GET /v1/models indique maxPromptChars. |
| model_not_found | 400 | Alias de modèle inconnu. | Utilisez un id de GET /v1/models. |
| duration_not_supported | 400 | Le modèle ne propose pas cette durée. | Envoyez l'une des durées du modèle. |
| aspect_ratio_not_supported | 400 | Le modèle ne propose pas ce format d'image. | Envoyez l'un des formats d'image du modèle. |
| resolution_not_supported | 400 | Le modèle ne propose pas cette résolution. | Envoyez l'une des résolutions du modèle. |
| reference_combination_not_supported | 400 | Ces références ne peuvent pas être combinées, par exemple des images de début et de fin avec des images de référence. | Envoyez un seul type par requête. |
| upload_invalid | 400 | Il manque un champ à la requête d'upload ou un type est incorrect. | Envoyez file_name, mime_type, file_size et upload_type. |
| video_edit_model_not_supported | 400 | Les retouches vidéo nécessitent un modèle de la famille Seedance 2.0 (2.0, Fast ou Mini). | Utilisez kreator-video-pro, kreator-video-fast ou kreator-video-mini. |
| video_edit_source_required | 400 | Une retouche vidéo nécessite un clip source. | Envoyez source_video_upload_id ou video. |
| voice_required | 400 | La synthèse vocale nécessite une voix. | Utilisez un id de GET /v1/voices. |
| paid_account_required | 403 | Lip Sync needs a paid account. Nothing was charged. | Top up with a card under Billing. |
| paid_check_unavailable | 503 | The account's payment status could not be read just now. Nothing was charged. | Send the same request again in a moment. |
| audio_reference_too_long | 400 | The audio references add up to more than the model accepts in total (15 s on Seedance 2.0, 30 s on 2.5). Nothing was charged. | Trim or remove audio so all audio references combined fit. |
| image_upload_not_found | 404 | The image_upload_id isn't in this workspace. | Upload the photo with upload_type IMAGE and use the new upload_id. |
| audio_upload_not_found | 404 | The audio_upload_id isn't in this workspace (or audio_job_id isn't a completed /v1/audio job). | Upload the track with upload_type AUDIO, or use a completed audio job id. |
| audio_too_short | 400 | The voice track is under 4 seconds. Nothing was charged. | Send 4 seconds to 5 minutes of audio. |
| audio_too_long | 400 | The voice track is over 5 minutes. Nothing was charged. | Trim it to 5 minutes or less. |
| audio_unreadable | 400 | The audio couldn't be read. Nothing was charged. | Use an MP3 or WAV under 15 MB. |
| image_rejected | 422 | The photo didn't pass the safety check. Nothing was charged. | Use a different photo. |
| internal_error | 500 | Une erreur s'est produite de notre côté. | Renvoyez la requête avec la même Idempotency-Key. |
| dispatch_disabled | 503 | La génération est en pause pour cet environnement. | Réessayez plus tard. |
Erreurs de tâche (la tâche échoue, tokens libérés)
| Code | Signification | Solution |
|---|---|---|
| reference_rejected | Une référence a été refusée (souvent la photo d'une personne réelle). | Enregistrez le visage comme personnage, ou utilisez une autre image. |
| reference_asset_pending | Une nouvelle référence est encore en cours de vérification. | Attendez errorData.retry_after secondes, puis renvoyez avec le même upload_id et une nouvelle Idempotency-Key. |
| reference_asset_failed | La référence n'a pas passé la vérification. | Utilisez un autre fichier. |
| generation_rejected | La requête a été refusée (prompt, référence ou options). | Modifiez le prompt, la référence ou les options, puis réessayez. |
| generation_timeout | La tâche ne s'est pas terminée à temps. Les tokens réservés sont libérés. | Renvoyez avec une nouvelle Idempotency-Key. |
| generation_unavailable | Le modèle est temporairement indisponible. | Réessayez plus tard ou choisissez un autre modèle. |
| generation_failed | La génération a échoué. | Réessayez ; modifiez le prompt ou les références si l'erreur se répète. |
Pourquoi ma référence a-t-elle été refusée ?
Les références et les prompts qui demandent de ressembler à une personne réelle, une célébrité ou une personnalité publique sont refusés. Cela inclut les photos de personnes réelles utilisées comme références et les prompts qui nomment une personne à imiter. Décrivez plutôt l'apparence, la tenue et le style, ou enregistrez un personnage qui vous appartient avec POST /v1/characters et passez son id.
Pourquoi la vidéo a-t-elle un autre format d'image ?
Avec une image d'entrée ou une première image, adaptive suit le format de l'image. Envoyez un aspect_ratio explicite quand la sortie doit respecter un format, et vérifiez que le modèle le propose.
Pourquoi camera_fixed échoue-t-il avec une image en entrée ?
N'envoyez pas camera_fixed avec une image ou une image clé en entrée, et décrivez plutôt la caméra dans le prompt (par exemple locked-off camera).
Questions fréquentes
Suis-je facturé quand une tâche Seedance échoue ?
Non. Les tokens réservés d'une tâche échouée sont libérés.
Que signifie insufficient_balance ?
Votre solde de tokens est inférieur au devis de la tâche. Rechargez dans la console ; rien n'a été réservé.
Que faire en cas de 429 ?
Attendez le nombre de secondes indiqué dans l'en-tête Retry-After, puis renvoyez.
Pourquoi mon prompt a-t-il été refusé ?
Il demandait de ressembler à une personne réelle ou enfreignait la politique d'utilisation acceptable. Modifiez le prompt et créez une nouvelle tâche.
