Facturation

Des dollars, sans conversion en crédits

Les prix sont exprimés en dollars américains : « 0,008 $ par image », « 0,042 $ par seconde de résultat ». Les fonds prépayés, les dotations promotionnelles et les lignes de crédit sont également libellés en dollars, mais un plafond de crédit ne constitue pas un solde en espèces.

Ce choix évite une conversion supplémentaire. Avec un système de crédits, il faut passer de « rechargez X, obtenez Y de bonus » à « combien vaut un crédit ? », ce qui complique le calcul du coût réel par unité. Le prix affiché est celui que vous payez.

Le paiement en quelques étapes

1. Ajoutez d’abord des fonds. Un nouveau compte démarre avec un solde de 0 $ et aucune offre gratuite n’est prévue. Une tâche envoyée avant la recharge est refusée avec 40201 et ne coûte rien.
2. Lorsqu’une tâche est acceptée, son montant estimé est réservé. Cette réservation vous appartient toujours, mais elle ne peut pas financer simultanément une autre tâche.
3. Si la tâche réussit, vous payez l’usage réel, sans jamais dépasser le montant réservé. La différence éventuelle revient dans votre solde.
4. Une tâche échouée ou expirée libère normalement toute la réservation. Certains refus de contenu sont facturés au montant du devis accepté, uniquement lorsque la page du modèle mentionne explicitement cette exception. Consultez settled et cost pour connaître les frais définitifs.
5. Les plafonds de dépenses définis pour chaque clé API empêchent un script qui s’emballe de vider votre solde.

La suite de cette page détaille chaque étape.

Ajouter des fonds

Ajoutez des fonds dans Facturation, dans la console : par carte, en cryptomonnaie ou par virement manuel lorsque cette option est proposée. Vous pouvez aussi activer la recharge automatique pour éviter qu’un traitement long s’arrête lorsque le solde devient faible. Les fonds que vous avez payés n’expirent pas ; les fonds promotionnels expirent à la date indiquée dans Facturation.

Pour le parcours détaillé — moyens de paiement, délai de crédit du compte et fonctionnement de la recharge automatique — consultez Configuration du compte. Les recharges ne donnent généralement pas lieu à un remboursement en espèces ; la politique de remboursement précise les exceptions, notamment un paiement facturé deux fois.

Les trois phases

Chaque tâche suit les trois mêmes étapes de facturation. Elles ne nécessitent aucune intervention de votre part ; les connaître permet de lire votre historique de solde sans ambiguïté.

Consulter votre solde

Le moyen le plus rapide est la page Facturation de la console : elle affiche votre solde disponible, les fonds actuellement réservés et chaque mouvement de solde. Dans votre code, appelez :

GET /api/v1/chat/credit

curl https://api.spicyapi.ai/api/v1/chat/credit \
  -H "Authorization: Bearer $SPICY_API_KEY"

const res = await fetch('https://api.spicyapi.ai/api/v1/chat/credit', {
  headers: { Authorization: `Bearer ${process.env.SPICY_API_KEY}` },
});
const body = await res.json();
if (body.code !== 200) throw new Error(`${body.code} ${body.msg}`);

const balance = body.data;
console.log(balance.funding ?? balance);

import os, requests

res = requests.get(
    "https://api.spicyapi.ai/api/v1/chat/credit",
    headers={"Authorization": f"Bearer {os.environ['SPICY_API_KEY']}"},
)
body = res.json()
if body["code"] != 200:
    raise RuntimeError(f'{body["code"]} {body["msg"]}')

balance = body["data"]
print(balance.get("funding", balance))

{
  "code": 200,
  "msg": "success",
  "data": {
    "available": "128.42",
    "held": "0.36",
    "total": "128.78"
  }
}

Lorsque les fonds admissibles pour le modèle et la date sélectionnés ne couvrent pas l’estimation, createTask renvoie 40201. L’expiration du crédit, des plafonds épuisés ou un déficit dû au recouvrement d’un paiement peuvent également empêcher l’acceptation. Ne remplacez pas les contrôles du serveur par un test côté client sur le signe de available.

Vous n’avez pas besoin de vérifier le solde avant chaque génération : l’acceptation de la tâche contrôle déjà les fonds disponibles et les plafonds de dépenses.

// Keep the exact decimal string for display
const usd = task.cost;

from decimal import Decimal
usd = Decimal(task["cost"])   # not float()

Plafonds de dépenses

Un plafond de dépenses limite le montant utilisable. Jusqu’à six plafonds peuvent s’appliquer à une tâche ; le premier atteint provoque un refus avec 40202, avant toute création ou réservation :

Les plafonds quotidiens repartent à zéro à 00:00 UTC ; les plafonds mensuels suivent le mois civil UTC et repartent à zéro le 1er. Un plafond total ne se réinitialise jamais. Si le plafond de la plateforme est atteint, réessayez après 00:00 UTC ou contactez l’assistance si cela se reproduit régulièrement.

Une réservation non réglée compte dans tous les plafonds, totaux, mensuels et quotidiens, jusqu’au règlement de la tâche, quel que soit le jour ou le mois concerné : les fonds ne sont pas encore dépensés, mais ne peuvent pas l’être deux fois. Les limites d’équipe sont détaillées dans Console et équipes.

Ces plafonds servent à vous protéger. Une boucle qui s’emballe et consomme une somme importante en quelques heures est un incident courant dans ce secteur, presque toujours sur un compte sans plafond.

Le registre des mouvements

La page Facturation de la console répertorie chaque mouvement de solde avec des libellés simples, comme Recharge, Réservé, Facturé ou Restitué. Lorsque vous téléchargez cette liste avec Exporter en CSV, la colonne kind contient l’un de ces codes stables :

Le bonus est enregistré séparément des fonds payés, car un remboursement de paiement, renvoyé sur votre carte, porte uniquement sur ce que vous avez payé ; un bonus n’a aucune valeur en espèces. Cela n’a aucun rapport avec les écritures refund ci-dessus, qui restituent au solde la réservation d’une tâche échouée.

Ces mouvements de solde sont conservés pendant 10 ans, séparément du contenu des tâches. Ils restent ainsi disponibles pour le rapprochement comptable et les litiges bien après la suppression des prompts et des résultats. Consultez Conservation des données.

Factures et relevés d’utilisation

Vous pouvez émettre vous-même deux documents depuis Facturation → Factures dans la console, tous deux téléchargeables en PDF :

Renseignez vos coordonnées une fois, en haut de Facturation → Factures. Le nom de votre entreprise ou votre nom, la première ligne d’adresse, la ville et le pays sont obligatoires ; un numéro fiscal, comme la TVA ou la GST, est facultatif. Ces informations sont imprimées telles que vous les saisissez : vous les fournissez et nous n’en vérifions aucune, y compris le numéro fiscal. Seuls les caractères latins, grecs et cyrilliques peuvent être imprimés ; indiquez donc le nom d’une entreprise japonaise ou coréenne dans sa forme romanisée enregistrée. Un document déjà émis conserve les coordonnées utilisées à sa création ; les modifications ultérieures ne concernent que les nouveaux documents.

• Chaque recharge payée et chaque mois terminé peuvent être documentés une seule fois. Si un document existe déjà, téléchargez-le au lieu d’en émettre un autre.
• Pour corriger des coordonnées erronées, choisissez Réémettre : l’ancien document est annulé et un nouveau numéro couvre le même élément. Utilisez Annuler sans remplacer uniquement lorsqu’un document concerne la mauvaise recharge ou le mauvais mois.
• Les relevés de compte, plus bas sur la même page, sont distincts : ce sont des instantanés mensuels figés de tous les mouvements du solde, destinés à votre comptabilité. Ce ne sont ni des reçus ni des documents fiscaux.

Le montant de taxe indiqué est zéro : nous sommes un fournisseur américain et ne collectons ni ne reversons pour votre compte de TVA, GST ou taxe sur les ventes. Chaque document comporte une mention d’autoliquidation ; toute taxe due dans votre pays reste donc à votre charge comptable. Une facture émise n’est jamais modifiée : elle est annulée puis réémise, avec le motif et le remplacement enregistrés.

Unités de facturation

Chaque modèle utilise exactement une unité de facturation.

Vous n’avez pas à deviner le nom du champ : quantityField, sur le point de terminaison du catalogue, l’indique pour chaque modèle. Une chaîne vide signifie une unité par appel.

Un modèle peut appliquer des prix différents selon ses paliers. La résolution, la durée, les options audio et les médias de référence peuvent modifier le devis, selon son schéma. pricing[].variant identifie un palier de la grille tarifaire ; le corps de la requête ne contient aucun champ variant. Ne supposez pas que ce libellé peut toujours être envoyé comme resolution, ni que tous les modèles se calculent en multipliant le prix de départ par la durée. Envoyez les entrées complètes à jobs/quote pour obtenir l’estimation exacte et le plafond de facturation.

Durée facturée par blocs entiers

La plupart des modèles per_second facturent la durée exacte qu’ils produisent. Quelques-uns utilisent des blocs fixes : la durée mesurée est arrondie au bloc entier supérieur avant le calcul du prix. Avec des blocs de 8 secondes, un clip de 6 secondes coûte autant qu’un clip de 8 secondes, et un clip de 9 secondes coûte deux blocs. Tous les modèles facturés à la seconde ne fonctionnent pas ainsi : cette règle concerne uniquement les points de terminaison qui la déclarent, et chacun l’indique sur sa page de modèle.

Ils partagent une autre particularité, qui explique l’arrondi visible dans le devis : leur durée provient d’une vidéo que vous fournissez, et non d’une valeur duration_seconds que vous choisissez. La durée du résultat reste donc inconnue jusqu’à la lecture du clip. Leur quantityField est vide ; le montant annoncé avant l’envoi correspond alors au maximum possible, soit le clip le plus long accepté par le point de terminaison :

{
  "estimatedCost": "0.96",
  "maxCharge": "0.96",
  "quantity": "32",
  "unit": "per_second"
}

Ces montants sont des exemples ; ici, quantity est un plafond en secondes, pas une mesure. Le montant du devis est celui réservé ; les frais définitifs sont calculés sur la durée arrondie et ne dépassent jamais cette réservation. La différence est libérée au règlement de la tâche, comme dans les trois phases décrites plus haut.

Deux conséquences sont à prévoir :

• Calculez le budget sur le devis, pas sur votre clip. Jusqu’au règlement, le montant réservé est le plafond, qui compte dans vos limites de dépenses comme toute autre réservation.
• Même un clip court coûte un bloc entier. Passer de 9 à 8 secondes peut diviser par deux le prix d’un point de terminaison utilisant des blocs de 8 secondes ; passer de 8 à 5 secondes ne change rien.

Les unités et les prix exacts figurent sur la page des tarifs et sur la page de chaque modèle.

Remises client et promotions

Une offre peut concerner tout le monde ou un compte précis, l’ensemble des modèles ou certains modèles seulement. Une offre permanente reste active jusqu’à sa désactivation ; une offre limitée dans le temps s’applique uniquement entre ses dates de début et de fin effectives. Les prix propres à un compte s’appliquent lorsque ce compte se connecte ou demande un devis avec sa clé API ; ils ne sont jamais publiés comme les prix d’un autre client.

Les offres ne se cumulent pas. Le prix admissible le plus bas s’applique automatiquement. Pour des frais standards de 10 $, une offre publique de 10 % et une remise de compte de 20 % donnent un prix de 8 $, sans cumul à 7,20 $. Lorsqu’une offre expire ou est désactivée, les nouveaux devis utilisent la meilleure offre encore admissible, ou le tarif standard s’il n’en reste aucune.

Les offres de la page d’accueil, du catalogue et des pages de modèles vous aident à comparer les options. Obtenez l’estimation réelle avec jobs/quote, en utilisant votre identité, le modèle et les entrées complètes. Un compte à rebours ne réserve pas un prix : actualisez le devis si l’offre, les entrées ou le tarif changent. Une tâche acceptée conserve son prix figé même si l’offre expire pendant son exécution ; les frais définitifs ne peuvent pas dépasser le montant réservé à l’acceptation.

Les offres s’appliquent automatiquement aux frais d’utilisation de l’API, pas au montant de votre recharge, et ne donnent aucun cashback sur les recharges. Les exemples de budgets quotidiens ou mensuels extrapolent le prix actuel ; une offre limitée peut se terminer avant la fin de la période budgétaire, pensez donc aussi à vérifier sa date de fin.

Fonds promotionnels et lignes de crédit

GET /api/v1/chat/credit conserve available, held et total, et peut inclure une ventilation funding. Les anciennes réponses peuvent omettre funding ; l’absence d’une donnée ne signifie pas zéro. Utilisez client.getBalance() dans le SDK ou spicyapi balance --json dans la CLI.

• funding.prepaidAvailableUsd contient les fonds prépayés disponibles ou les anciens fonds sans restriction ; grantAvailableUsd totalise les dotations actuellement actives. Chaque entrée de grants indique les montants accordés, disponibles, réservés et dépensés, ainsi que le statut, le début, l’expiration et modelSlugs. Une liste de modèles vide couvre tous les modèles ; sinon, la dotation finance uniquement ceux de la liste. Jusqu’à 100 dotations sont affichées, en priorité celles qui conservent un solde disponible ou réservé, puis de la plus récente à la plus ancienne. grantsHasMore signale des enregistrements supplémentaires. Ne remplacez pas le total du compte par le sous-total des dotations visibles.
• funding.credit décrit une ligne de crédit approuvée permettant de payer plus tard. limitUsd est son plafond, availableUsd le crédit admissible inutilisé, usedUsd le principal comptabilisé et encore dû, heldUsd le montant réservé pour des tâches acceptées et expiresAt sa date d’expiration. Ce plafond de crédit n’est ni une recharge, ni une dotation, ni un solde en espèces. L’expiration, la désactivation ou le dépassement du plafond limite les nouvelles requêtes ; les dettes existantes restent dues.
• Les fonds promotionnels ne peuvent pas être retirés. Les remises définissent le prix de la requête ; les dotations et le crédit déterminent comment le financer. Une dotation ne réduit pas le tarif affiché du modèle. Son périmètre de modèles et sa validité s’appliquent, et les fonds inutilisés peuvent expirer ou être révoqués. Les tâches échouées et les réservations inutilisées libèrent les fonds vers leur source d’origine, sans réactiver une dotation expirée ou révoquée.
• Un funding.cashShortfallUsd positif signale un déficit lié au recouvrement d’un paiement externe. Les dotations et le crédit ne peuvent pas le couvrir ; les nouveaux appels restent bloqués jusqu’à sa régularisation. À l’inverse, un available négatif peut refléter l’utilisation d’un crédit approuvé. Ne déduisez pas un refus de son signe et ne l’ajoutez pas directement au plafond de crédit. Le serveur contrôle les sources de financement, l’admissibilité du modèle, la validité et les plafonds de dépenses.

Les montants restent des chaînes décimales exactes en USD et les dates utilisent RFC3339. Indiquez le fuseau horaire lorsque vous affichez des dates. La page Facturation de la console présente les fonds et les dotations ; les modifications ne prennent effet qu’après approbation manuelle d’un administrateur. Pour toute question sur les dotations ou les lignes de crédit, ouvrez une conversation dans Assistance dans la console, ou écrivez à support@spicyapi.ai. L’API publique ne propose aucune opération permettant d’augmenter vous-même votre plafond ou d’émettre des dotations.

Utilisation de la clé API actuelle

Pour consulter les dépenses quotidiennes et par modèle de l’ensemble du compte ou d’une équipe, utilisez Facturation → Utilisation dans la console. Le point de terminaison ci-dessous couvre uniquement la clé qui l’appelle :

curl 'https://api.spicyapi.ai/api/v1/usage?from=2026-09-01&to=2026-09-06' \
  -H "Authorization: Bearer $SPICY_API_KEY"

Les dates sont en UTC avec l’intervalle [from,to) ; cet exemple couvre donc du 1er au 5 septembre. Sans dates, les sept derniers jours sont utilisés, aujourd’hui inclus ; la plage maximale est de 92 jours. Les résultats concernent uniquement la clé API actuelle. Aucun paramètre ne permet de consulter une autre clé ou un rapport global du compte ; utilisez chat/credit pour le solde du portefeuille.

data.totalCalls compte toutes les tâches ; data.totalSpend inclut uniquement les frais réglés. days et models regroupent ces mêmes tâches par date de création et par modèle, avec des chaînes décimales exactes en USD. Les réservations en attente sont exclues et un règlement tardif peut modifier les dates précédentes. L’historique masqué reste inclus ; les dates sans appel sont omises. N’additionnez pas ces deux regroupements.

Utilisez client.getUsage({ from, to }) dans le SDK ou spicyapi usage --from 2026-09-01 --to 2026-09-06 dans la CLI. Ce point de terminaison possède sa propre limite de débit, plus stricte : consultez Limites de débit.