Guide
Limitation de débit et quotas
Limites de concurrence, limitation de débit, quotas et capacité du compte, ainsi que la méthode de nouvelle tentative avec recul
Limitation de débit et quotas
Les limites de la plateforme se répartissent en plusieurs catégories, avec des manifestations différentes. Il faut identifier la catégorie concernée pour agir rapidement.
| Type de limite | Manifestation une fois déclenchée | Traitement |
|---|---|---|
| Fréquence des requêtes (limitation de débit) | HTTP 429 « requêtes trop fréquentes » | Réessayer après un recul, sans réessayer en parallèle |
| Concurrence des tâches asynchrones | HTTP 429, task_concurrency_exceeded | Attendre la fin des tâches existantes avant de soumettre |
| Quota de la clé | Message de solde/quota insuffisant, la tâche n'est pas créée | Recharger, ajuster le quota de la clé ou réduire la requête |
| Solde du compte | Message indiquant que le solde ne couvre pas la consommation estimée | Recharger via le portefeuille |
| Capacité des ressources | Validation du format et de la taille lors de la soumission | Corriger le fichier ou utiliser image_url |
Limitation de la fréquence des requêtes
La plateforme limite la fréquence des requêtes. Une interrogation trop rapide, une concurrence trop élevée ou de nombreuses nouvelles tentatives en peu de temps peuvent la déclencher :
{ "error": { "code": "...", "message": "请求过于频繁" } }Le statut HTTP est 429.
Bonne pratique :
- Après avoir reçu un
429, reculer : attendez un certain temps avant la requête suivante, sans la renvoyer immédiatement ; - Ne contournez pas la limitation de débit avec des requêtes parallèles : cela ne ferait qu'allonger le temps de recul ;
- Lors de l'interrogation de tâches asynchrones, utilisez un intervalle fixe et raisonnable (par exemple toutes les quelques secondes), sans interroger en continu.
Ne réessayez pas aveuglément pour les codes de statut autres que 429 :
| Code de statut | Traitement |
|---|---|
429 | Réessayer après un recul conforme au message |
5xx temporaire | Conserver le RequestId, réessayer une fois après un recul |
400 | Problème de paramètres : corrigez la requête avant de l'envoyer |
401 | Clé invalide ou désactivée : vérifiez la clé |
403 | Aucun droit d'accès à cette ressource ou à ce modèle |
404 | Ressource inexistante : vérifiez l'ID |
Concurrence des tâches asynchrones
Les tâches asynchrones telles que la vidéo sont soumises à une limite de concurrence, déclinée par compte et pour l'ensemble de la plateforme. Une fois la limite atteinte, la plateforme renvoie HTTP 429,
avec le code d'erreur task_concurrency_exceeded, et le message indique « actuellement N / limite M ».
Dans ce cas :
- Conservez les ID des tâches existantes, sans les abandonner ;
- Attendez que les tâches en cours atteignent un état terminal (ou interrogez directement leur état actuel) ;
- Attendez, puis laissez l'utilisateur soumettre volontairement à nouveau, sans réessayer en rafale ;
- Ne soumettez pas plusieurs fois la même tâche pour « forcer » la concurrence : cela créerait des tâches et des frais en double.
Avant une soumission par lots, il est recommandé de gérer une file d'attente dans le backend métier : limitez le nombre de tâches en cours plutôt que de tout soumettre d'un coup.
Quota de la clé et solde du compte
Le quota et le solde sont des limites à deux niveaux :
| Niveau | Explication |
|---|---|
| Quota de la clé | Plafond d'usage et durée de validité définis pour la clé dans « Clés API » de la console |
| Solde du compte | Solde disponible, quota de forfait ou points de l'ensemble du compte LocoPal |
Avant la soumission d'une tâche asynchrone, la plateforme vérifie si le solde couvre la consommation estimée de cette requête. En cas d'insuffisance, elle renvoie un message lisible et ne crée pas la tâche ; cette situation ne génère donc pas de frais.
Traitement :
- Quota de la clé insuffisant → ajustez le quota ou la durée de validité de la clé dans « Clés API » ;
- Solde du compte insuffisant → rechargez via « Portefeuille » ou utilisez un forfait ;
- Consommation estimée trop élevée → réduisez la résolution, la durée ou utilisez un modèle plus petit.
Il est recommandé d'effectuer une vérification préalable du solde dans le backend métier et de fournir un message clair à l'utilisateur final, plutôt que de lui renvoyer directement l'erreur de la plateforme.
Limites des ressources
L'interface de ressources valide les données téléversées :
| Limite | Manifestation | Traitement |
|---|---|---|
| Format de l'adresse | image_url 必须是可公开下载的 http(s) 地址… | Utilisez une adresse http(s) directement téléchargeable depuis l'internet public |
| Un seul type par soumission | image_url 与 data_url 只能提交一个 | Ne conservez qu'un seul champ |
| Taille des données | 图片数据无效或超过 20MB | Compressez l'image ou utilisez image_url |
| Type de groupe | 素材分组不存在或不是虚拟素材分组 | Les images ne peuvent être soumises qu'à un groupe virtual |
| Longueur du nom | Le nom du groupe ne peut pas être vide et ne doit pas dépasser 64 caractères ; la description ne doit pas dépasser 300 caractères | Corrigez le nom ou la description |
Une ressource dont la vérification n'est pas terminée n'est pas en erreur : l'interrogation renvoie 200 avec un status à Processing ; continuez à interroger avec le même ID de ressource,
sans soumettre à nouveau.
Recommandations d'interrogation
L'interrogation des tâches asynchrones ne génère pas de frais, mais des interrogations trop rapprochées déclenchent la limitation de débit.
| Phase de la tâche | Intervalle recommandé |
|---|---|
| Juste après la soumission (en file d'attente) | Toutes les quelques secondes |
| En génération | Toutes les quelques secondes à une quinzaine de secondes |
| État terminal atteint | Arrêter l'interrogation |
L'interrogation doit avoir une durée totale maximale. Une fois cette limite atteinte, arrêtez l'interrogation et renvoyez l'ID de tâche à l'utilisateur, afin qu'il puisse reprendre l'interrogation plus tard avec cet ID — ne recréez pas la tâche.
Idempotence et soumissions en double
La plateforme ne fusionne pas automatiquement des requêtes identiques. Même si le prompt, les paramètres et les ressources de référence sont exactement identiques, chaque soumission volontaire crée une nouvelle tâche et un nouveau résultat, chacun facturé.
Par conséquent :
- Utilisez une clé d'idempotence côté métier (numéro de commande, ID métier) pour éviter les soumissions en double dues à des clics répétés ;
- Enregistrez immédiatement l'ID de tâche en base de données après la soumission ; en cas de coupure réseau, reprenez par une interrogation plutôt qu'en recréant la tâche ;
- Ce n'est qu'en cliquant sur « Réessayer directement » sur un même résultat en échec que l'exécution reprend au même emplacement — cela génère également une nouvelle tâche et de nouveaux frais.