API Pro : limites, codes d'erreur et bonnes pratiques

Plafonds

Chaque clé en porte trois : renders simultanés (2 par défaut), soumissions par minute (60 par défaut) et, si tu en définis un, un plafond de crédits journalier.

Dès qu'un plafond est atteint, la réponse est 429 avec un en-tête Retry-After en secondes. Un appel refusé ne coûte rien. Le jour pris en compte pour les plafonds est le jour UTC.

Les longues vidéos ajoutent deux plafonds supplémentaires : 30 plans par séquence et 5 séquences en cours par licence (voir Vidéos).

Les personnages en ont un : 50 par licence Pro, ceux de l'appli compris, et un personnage inutilisé pendant un an est effacé (voir Personnages). Les lieux, objets et animaux ont le leur, compté à part : 50 par licence Pro (10 avec une licence personnelle, dans l'appli), effacés après la même année sans usage (voir Lieux, objets, animaux, styles et tenues).

Le Face swap a les siens : un passage de 20 s au plus par rendu, et notre serveur prépare deux vidéos à la fois. Au-delà, la réponse est 429 server_busy : réessaie après Retry-After (voir Face swap). Par le MCP, un Face swap avec transition prend une vidéo entière de 60 s au plus, et le serveur en traite deux à la fois : au-delà, l'outil demande de réessayer dans quelques minutes.

Notre propre carte est partagée avec les utilisateurs de l'application. Quand elle est occupée, tes renders sont envoyés vers des GPU loués, au même prix et via la même API, avec quelques dizaines de secondes supplémentaires au démarrage.

Codes d'erreur

Code	error	Ce que ça signifie, et quoi faire
400	prompt_required	Ajoute un prompt.
400	forbidden_content	Le filtre de contenu a refusé le prompt.
400	invalid_seed	seed doit être un entier de 0 à 4294967295.
400	image_required, inpaint_images_required	Le mode nécessite image_b64, et mask_b64 pour inpaint.
401	key_required, invalid_key	En-tête absent, ou clé inconnue.
402	insufficient_credits	Solde insuffisant pour ce rendu (cost est indiqué). La réponse contient buy_url, la page d'achat de crédits de ta licence. Un rendu ou un entraînement en cours réserve son prix jusqu'à sa fin : engaged dit combien de crédits sont ainsi tenus de côté.
402	confirmation_required, payment_declined	Un achat sur ta carte enregistrée (POST /credits/purchase) : ta banque demande ta confirmation, ou a refusé le paiement. Utilise buy_url, le lien d'achat ordinaire.
409	agent_not_allowed, no_saved_card, monthly_cap_reached	Un achat sur ta carte enregistrée : ton agent n'est pas autorisé à acheter (recharge automatique de ta page compte), aucune carte n'est enregistrée, ou l'achat dépasserait ton plafond mensuel. Utilise buy_url.
409	topup_in_progress, purchase_in_progress	Un autre paiement sur ta carte enregistrée est en cours : attends qu'il se termine.
400	unknown_pack	Un achat avec un pack inconnu, ou un montant libre hors bornes ou hors tranche.
503	payment_unavailable	Le paiement n'a pas pu être confirmé : on ne sait pas si le débit a eu lieu. Ne relance pas tout de suite ; un débit passé est crédité.
403	key_disabled, key_revoked, key_expired	Clé désactivée, révoquée ou expirée : crée-en une nouvelle dans l'application.
403	license_revoked, license_not_pro	Licence révoquée, ou compte qui n'est pas Pro.
403	missing_scope	La clé ne possède pas la permission demandée, indiquée dans scope.
403	unknown_lora	Un personnage qui n'appartient pas au compte.
404	media_unavailable	Le fichier a disparu : soumets à nouveau.
404	unknown_lora	Sur DELETE /loras/{name}, aucun fichier de ce nom sur le compte. Note le code : le même nom renvoie 403 quand un rendu demande un personnage qui ne t'appartient pas.
411	size_required	Un upload de LoRA sans Content-Length. Le corps est brut, la taille doit donc être annoncée.
413	file_too_large	Un LoRA dépassant 800 Mo, ou 90 Mo en un seul upload. Envoie-le en plusieurs parties. Un 413 brut sans corps JSON est autre chose : la requête n'a jamais atteint l'API, consulte la section upload.
413	part_too_large	Une partie est plus grande que le max_part_size annoncé par la session.
404	unknown_upload_session	L'uploadId n'existe pas, ou la session a été abandonnée (six heures) ou annulée par une partie rejetée.
503	upload_refused, part_refused	Stockage injoignable au moment du dépôt : réessaie.
507	storage_full	Plus de place sur le stockage côté serveur (LoRA, ou séquences en cours). L'équipe est prévenue : réessaie plus tard.
415	invalid_safetensors	Le fichier uploadé n'est pas un safetensors.
415	incompatible_lora	Le LoRA est destiné à une autre architecture, indiquée dans architecture. Les images n'acceptent que Krea 2, les vidéos LTX 2.5 ou 2.3. Rien n'est stocké et aucun quota n'est consommé.
413	lora_quota	Le stockage LoRA du compte est plein (20 fichiers ou 10 Go). La réponse indique ce qu'il reste ; supprime un fichier pour libérer de la place.
413	image_too_large	Image source ou masque dépassant 12 Mo décodé.
429	too_many_concurrent_renders, rate_limited, daily_cap	Un plafond est atteint, consulte Retry-After.
429	daily_credit_cap	Le plafond de crédits journalier de la clé est atteint (cap, spent, cost).
502	submission_failed, status_failed	Un incident côté rendu : réessaie dans quelques secondes.
503	license_check_failed	Le compte ne peut pas être vérifié pour l'instant : réessaie dans une minute.
400	invalid_extend_frames	Une prolongation dont extend_frames ne vaut pas 9, 17, 25, 33, 41 ou 49, ou un extend_video qui ne contient pas exactement ce nombre d'images.
400	extension_with_transition	Une prolongation ne peut être une transition qu'en consistency enhanced : retire end_image, ou demande la cohérence renforcée.
400	extension_too_short	La length d'une prolongation ne compte que les nouvelles images, et doit être d'au moins 9.
404	clip_unavailable	Le clip à prolonger n'est plus disponible : prolonge-le plus tôt, ou envoie sa fin dans extend_video. En 502, sa lecture a échoué : réessaie.
404	unknown_clip	Le clip à prolonger appartient à une autre licence.
404	unknown_sequence	La séquence n'existe pas, appartient à une autre licence, ou a expiré.
400	job_id_required, empty_sequence	POST /sequences/{id}/clips sans job_id, ou export d'une séquence qui n'a aucun plan.
409	not_exported_yet	GET /sequences/{id}/file avant l'export : appelle d'abord POST /sequences/{id}/export.
404	unknown_export	Export du dossier de projet : rendu inconnu, d'une autre licence ou soumis il y a plus de 24 h ; ZIP effacé (45 min après le premier téléchargement, 2 h au plus).
409	export_in_progress	Un export de dossier de projet à la fois par licence.
413	export_too_large	Dossier de projet de plus de 2 Go : exporte les plans un par un.
400	unknown_reference	Export du dossier de projet : une entrée de exclude_references ne désigne aucune référence de l'export (ni id, ni nom, ni @mention).
400	invalid_export_options	Export du dossier de projet : une option qui n'est pas un booléen, un exclude_references qui n'est pas une liste de textes, ou include_film sans include_media.
500	export_failed	L'export a échoué (raison dans detail) : rien n'est débité, relance.
422	resolution_mismatch, unreadable_clip	Rendu rangé à la main (POST /sequences/{id}/clips) d'une autre résolution que la séquence, ou illisible.
409	missing_shot	Un plan n'est pas encore terminé, ou n'est plus disponible (job_id le désigne) : attends qu'il se termine, puis exporte à nouveau.
409	sequence_exported	La séquence est déjà assemblée.
409	audio_mismatch	Un plan avec son dans une séquence silencieuse, ou l'inverse.
413	extend_video_too_large	La fin de clip que tu as envoyée dépasse 8 Mo.
413	too_many_shots	30 plans au maximum par séquence.
422	unreadable_tail	La fin de clip, envoyée ou relue, n'est pas une vidéo lisible.
422	assembly_failed	Les plans ont des résolutions différentes, ou le son n'est présent que sur certains d'entre eux.
503	ultra_unavailable	Le mode Ultra est momentanément fermé : réessaie plus tard, ou rends sans quality.
503	ultra_4k_unavailable	Une taille 4K demandée en Ultra : la 4K n'est plus proposée, la vidéo va jusqu'au 1080p (1920 x 1088).
400	ultra_incompatible	Une transition (end_image) demandée en Ultra.
400	extension_4k	La suite d'un ancien clip 4K : la 4K n'est plus proposée, un clip 4K ne se prolonge plus (ultra_4k_unavailable avec quality: "max"). Prolonge un clip de 1080p au plus.
400	resolution_above_quality	Une taille au-delà du 1080p (1920 x 1088) sans quality: "max" : le 1080p est le plafond dans tous les modes.
400	invalid_keyframes, invalid_keyframe_time, keyframes_mode	Images clés hors limites : plus de 4, image ou force invalide ; instant hors du clip ou deux images clés à moins de 0,5 s ; mode autre que Qualité (Ultra, Multi-Ref), ou prolongation sans consistency enhanced.
400	invalid_consistency, consistency_mode	consistency autre que standard ou enhanced ; cohérence renforcée demandée en Ultra ou en Multi-Ref.
400	consistency_explicit	Prompt que la cohérence renforcée ne rend pas encore, au-delà de 20 s (15 s avec une end_image), en prolongation ou dans une séquence (un plan seul plus court est rendu en cohérence standard) : raccourcir, ou passer en standard.
403	consistency_licensed_only	Cohérence renforcée réservée aux licences.
503	consistency_unavailable	Cohérence renforcée momentanément fermée : réessaie plus tard, ou rends en standard.
409	consistency_mismatch	Plan d'une autre consistency que la séquence.
422	encoding_mismatch	Rendu rangé à la main (POST /sequences/{id}/clips) d'une autre consistency que les plans déjà rangés.
400	invalid_fps, fps_requires_fixed_duration, extend_fps_mismatch	Une cadence (fps) absente du mode (detail liste celles qu'il a) ; cohérence renforcée au-delà de 30 i/s en durée automatique (mets duration_auto à false et donne length) ; une prolongation à une autre cadence que le clip précédent.
409	sequence_fps_mismatch	Plan d'une autre cadence (fps) que la séquence.
503	keyframes_unavailable	Images clés fermées pour le moment : relance sans keyframes.
429	too_many_sequences	5 séquences en cours au maximum par licence : exporte-en une, ou attends qu'une expire.
400	invalid_name, invalid_kind, invalid_photo_role, outfit_too_long, invalid_role	Champ de personnage hors limites (voir Personnages).
400	image_too_small	Photo de moins de 1024 px sur le grand côté.
415	unsupported_image_format, unreadable_image	Photo ou image de décor qui n'est pas un JPEG, PNG ou WebP lisible.
404	unknown_character	Le character_id n'est pas sur ta licence, ou a été effacé (un an sans usage, ou supprimé dans l'appli).
409	character_limit	Plafond de personnages atteint (max) : efface-en un.
409	character_busy	Ses vues sont en fabrication : attends que status ne soit plus pending. Sur POST /characters : la même création est en cours d'enregistrement, renvoie-la quelques secondes plus tard.
409	photo_view, empty_character, single_image_sheet	La vue de la photo d'origine ne se refait pas ; ou le personnage n'a aucune vue lisible (si c'est le stockage qui refuse la lecture : 503 storage_unavailable, à réessayer) ; ou une sheet importée en une seule image (une planche, gardée telle quelle) : ni vue refaite, ni habillée pour une nouvelle sheet (fournissez la vue 4 ou 1).
409	app_character	Une instruction ou une vue déposée sur un personnage ou une sheet faits dans l'appli : réservé aux personnages et aux sheets créés par l'API.
400	instruction_too_long	Une instruction de plus de 200 caractères.
400	outfit_or_views_required	Une sheet ajoutée sans outfit ni views : donne une tenue à générer, ou des vues.
400	views_required	Une sheet ajoutée avec generate: false : donne au moins une vue.
409	source_sheet_empty	Une sheet ajoutée sans vue en pied ni buste, à un personnage qui n'a ni l'un ni l'autre à reprendre : envoie l'un des deux dans views.
404	unknown_sheet	Seule une sheet ajoutée par l'API (sheet_origin api) s'efface avec DELETE /characters/{id}/sheets/{sheet_id}.
404	unknown_subject	Le subject_id n'est pas sur ta licence, ou a été effacé après un an sans usage.
409	subject_limit	Le plafond de sujets (max) est atteint : lieux, objets, animaux, styles et tenues comptent ensemble ; efface-en un.
409	empty_subject	Un sujet sans aucune image lisible.
400	invalid_type, description_too_long, invalid_images	Un champ de sujet hors limites (voir Lieux, objets, animaux, styles et tenues).
400	invalid_image	Une image de sujet qui n'est pas un JPEG, PNG ou WebP lisible d'au moins 512 px sur le grand côté (index dit laquelle).
400	description_required, invalid_views, invalid_view, invalid_count, too_many_images, prompt_too_long, invalid_instructions	Générer un sujet : ni description, ni prompt, ni image de départ ; une clé de vue absente du genre (detail donne la liste) ; count hors de 1 à 6, ou plus de 6 images, départ compris ; un prompt de plus de 2 000 caractères ; instructions vides, trop longues ou pour plusieurs vues.
409	subject_busy, subject_not_generated, view_exists, views_exist, start_image_missing, start_image_imported	Une série tourne déjà sur ce sujet ; un sujet créé par images (ajoutes-en par /images) ; une vue déjà faite (refais-la) ; un départ à refaire alors que des vues en partent ; un départ en échec à refaire d'abord ; un départ importé, qui ne se refait pas.
404 / 503	unknown_view, generation_unavailable	Une vue jamais demandée (ajoute-la) ; la génération de sujets n'est pas disponible sur le serveur pour le moment : réessaie plus tard.
400	multiref_characters_required, multiref_incompatible, multiref_mode, multiref_format, invalid_length	Multi-Ref hors limites : 1 à 4 personnages (12 en Ultra), pas de prolongation ni de transition, les formats et durées de Multi-Ref Vidéo.
400	duplicate_name, invalid_strength, unknown_mention	Deux personnages du même nom ; strength hors de 0 à 2 ; un @Nom du prompt sans personnage (mentions les liste).
400	voice_requires_audio, voice_slot	Une voix de personnage (voice_b64) sans son ("audio": true) ; ou sur un autre personnage que characters[0] et characters[1] (le moteur supporte 2 voix). index dit lequel.
400	invalid_voice_choice	voice autre que character ou original dans un Face swap, ou characters[].voice autre que character ou generated dans le Multi-Ref Vidéo.
413	audio_too_large	Une voix de personnage de plus de 4 Mo, ou de plus de 2 Mo dans un Face swap. Seules les 5 premières secondes servent (20 dans un Face swap) : envoie un extrait court.
415	unsupported_audio_format	Une voix de personnage qui n'est pas un fichier audio lisible (WAV, MP3, OGG, FLAC).
400	multiref_too_many_references, invalid_subject_type	Plus de 4 personnages, objets et animaux en tout, hors Ultra ; un sujet dans le mauvais champ (un lieu dans subjects, un objet en location, un style hors de styles, une tenue hors de outfits).
400	invalid_count, invalid_view, invalid_lora_pass, invalid_subject_image, invalid_size	Créer une image : count 1 ou 2, view 1 à 5 et présente dans la sheet, lora_pass 0,3 à 0,9, image d'un sujet parmi ses images, largeur et hauteur de 256 à 2048.
400	character_not_ready	Créer une image : la vue choisie d'un personnage n'a pas encore d'image.
503	multiref_image_disabled	Créer une image n'est pas encore ouvert sur ce serveur.
400	multiref_ultra_only, multiref_too_many_images, unknown_wearer	Styles, tenues ou mouvement hors du Multi-Ref en Ultra ; plus de 30 images en Ultra ; un worn_by qui ne nomme aucun personnage.
400	invalid_motion, invalid_motion_mode, unreadable_motion, motion_missing	Un motion sans motion_id ni video_b64 ; un mode autre que camera ou choreography ; une vidéo illisible, ou hors de 4 à 30 s (input_video_out_of_limits) ; un motion_id jamais déposé (pas de PUT).
404 / 409	unknown_motion, motion_already_used	Un motion_id inconnu, déjà utilisé ou de plus de 2 heures : dépose la vidéo à nouveau.
413 / 503	motion_too_large, motion_not_open, motion_mode_unavailable	Une vidéo de mouvement de plus de 20 Mo (20 Mo une fois ramenée en 480p) ; le mouvement n'est pas encore ouvert (ultra.motion_per_second vaut null) ; un mode pas encore ouvert.
409	extension_link_expired	Un extend_job_id inconnu de ta licence, ou un plan Ultra de plus de 24 heures : dépose son original (POST /extensions) et passe extend_upload_id.
400	extension_real_face	La vidéo à prolonger en Ultra n'a pas été rendue par le mode Ultra (le rendu d'un autre mode, par exemple) et montre un visage réaliste : rien n'est débité. Prolonge-la en mode Qualité, ou refais le plan en Ultra.
400	extension_ultra_only, extension_ultra_options, invalid_extension_direction, extension_backward_sequence, extension_tail_quality_only	Prolongation Ultra hors limites : extend_upload_id ou backward sans quality: "max" (ou depuis un clip qui n'est pas Ultra) ; une image de départ, des références, un mouvement ou la cohérence renforcée avec ; un sens autre que forward ou backward ; backward dans une séquence ; extend_video en Ultra.
400	extension_too_large, unreadable_extension, extension_upload_missing	Une vidéo déposée au-delà du 1080p ; un MP4 illisible, ou hors de 4 à 30 s (input_video_out_of_limits) ; un fichier jamais déposé (pas de PUT).
400	input_video_out_of_limits	Une vidéo envoyée au mode Ultra (mouvement, vidéo à prolonger) hors de ses limites, vérifiées avant le rendu, rien n'est débité : limit dit laquelle (duration : 4 à 30 s ; total_duration : 30 s avec les sons de référence ; count : 10 ; size : 200 Mo ; format : MP4 ou MOV ; fps : 24 à 60 ; pixels : largeur × hauteur de 409 600 à 8 295 044 ; aspect_ratio : 0,4 à 2,5), avec value, min et max.
404 / 409	unknown_extension_upload, extension_upload_used	Un extend_upload_id inconnu, de plus de 2 heures ou déjà utilisé : dépose le fichier à nouveau.
413 / 503	extension_too_heavy, extension_not_open, extension_backward_unavailable	Un fichier de plus de 60 Mo ; la prolongation Ultra n'est pas encore ouverte (ultra.extend_per_second vaut null) ; vers l'arrière pas encore ouvert.
413	references_too_large	Les vues préparées dépassent le budget du rendu : moins de personnages, ou un format plus petit.
400	video_required, character_required	Un Face swap sans video_b64, ou sans character_id.
413	video_too_large	Une vidéo de Face swap de plus de 20 Mo : coupe-la ou compresse-la avant, ou passe par l'outil MCP tendre_face_swap, qui prend jusqu'à 95 Mo.
415	unreadable_video	La vidéo du Face swap n'est pas un MP4, MOV, WebM ou MKV lisible.
400	invalid_start, invalid_duration, passage_too_short	Un passage de Face swap hors limites : start négatif ou au-delà de la fin de la vidéo ; duration hors de 0,5 à 20 s ; un passage de moins d'une demi-seconde.
400	invalid_zone, invalid_likeness, invalid_scene, invalid_description, invalid_character_name, invalid_part	Un champ de Face swap hors limites : zone autre que tight, normal ou wide ; part autre que full ou head ; likeness hors de 0,5 à 2 ; scene de plus de 400 caractères ; description de plus de 360 ; name de plus de 60.
413	face_swap_too_large	Le passage reste trop lourd une fois préparé : donne une duration plus courte.
429	server_busy	Notre serveur prépare déjà deux vidéos de Face swap : réessaie après Retry-After (20 s). Le lien de dépôt du MCP rend le même code en 503 quand trop de fichiers attendent : réessaie dans quelques minutes.
503	face_swap_unavailable, face_swap_price_missing	Le Face swap est momentanément fermé, ou sans prix : réessaie plus tard.
503	creation_unavailable, multiref_unavailable, storage_unavailable	Service momentanément indisponible : réessaie plus tard.
500	internal_error	Un incident inattendu côté serveur : réessaie, et signale-le s'il revient.

Ultra facturé à la seconde (Ultra) :

Code	error	Ce que ça signifie, et quoi faire
400	resolution_outside_ultra	Au-delà du 1080p : 480p, 720p ou 1080p.
400	engine_refused	Le moteur refuse le texte ou une image : la raison est dans detail et le code dans code. Rien n'est débité : reformule.
502	engine_unavailable	Le moteur ne répond pas : réessaie dans quelques minutes. Rien n'est débité.
409	render_in_progress	Annulation d'un rendu déjà en calcul : il ne s'arrête plus, il est livré et facturé.
400	invalid_references, references_too_large, multiref_ultra_options, multiref_ultra_explicit	Multi-Ref en Ultra : une image de référence est illisible ou trop lourde (20 Mo au plus en tout), ou une option n'est pas prise en charge.
403	multiref_ultra_unavailable	Le Multi-Ref en Ultra à la seconde n'est pas encore ouvert à ce compte.

Les noms d'erreur sont les chaînes exactes que renvoie l'API. Fais correspondre dessus plutôt que sur le message, qui peut être reformulé.

Une réponse n'est pas une erreur : un rendu Multi-Ref ou un Face swap avec un personnage qui n'a qu'une vue passe, avec un avertissement limited_likeness dans warnings ({ "code": "limited_likeness", "character_id": "...", "detail": "..." }). La ressemblance est limitée : crée les sept vues du personnage pour une ressemblance fidèle.

Un rendu Multi-Ref en Ultra avec 9 à 12 personnages passe aussi, avec un avertissement many_characters : certains peuvent manquer ou se mélanger (8 sont conseillés).

Bonnes pratiques

• Interroge toutes les 3 secondes, pas plus vite. La file est partagée, et la bombarder n'aide personne.
• Télécharge dès que le statut est completed. Le fichier n'est pas archivé.
• Écris les prompts en anglais, et pour les vidéos décris le mouvement plutôt que l'image fixe.
• Une clé par usage, et un plafond de crédits journalier sur chaque clé qui vit sur un serveur. Une clé compromise avec un plafond te coûte une journée, pas tout ton solde.
• Traite un 429 comme normal, et non comme un échec : attends le Retry-After et continue.
• Une connexion coupée avant la réponse ne coûte rien. Si une soumission d'image ou de vidéo reste sans réponse (délai d'un proxy dépassé, erreur 524, programme arrêté), le rendu n'est pas lancé, ou il est annulé aussitôt, et rien n'est facturé : relance simplement la demande. Pour un lot d'images (count), les rendus déjà créés sont annulés eux aussi. Une création de personnage, elle, continue : la renvoyer à l'identique rend le même personnage, sans rien facturer deux fois (voir Personnages).

Les prompts sont journalisés de notre côté, comme pour l'application, à des fins de sécurité.