Facturation et mesure de l'utilisation

Chaque appel à une capacité IA — complétion LLM, transcription vocale, embedding, synthèse TTS, OCR, génération d'images, analyse vidéo — produit un événement d'utilisation mesuré. L'API billing.* permet aux administrateurs d'organisation d'interroger les coûts, les tokens, les exécutions et les estimations CO₂ selon toute combinaison d'espace de travail, d'équipe, d'utilisateur, de capacité, de fournisseur, de modèle ou de région.

Aperçu de l'API

Toutes les méthodes billing.* sont disponibles sur le client admin Better Auth (getAdminClient()) depuis @scrydon/multi-tenancy/auth/client.

Champs des événements d'utilisation

Chaque événement mesuré capture :

Résumé

Retourne les totaux agrégés pour l'organisation sur une plage de dates, avec une ventilation optionnelle par dimension.

const { data, error } = await getAdminClient().billing.summary({
  organizationId: "org_abc123",
  range: { from: "2026-06-01T00:00:00Z", to: "2026-07-01T00:00:00Z" },
  groupBy: "workspace",            // optionnel
  filters: { capability: "llm" }, // filtre de dimension optionnel
})

Requête

UsageDimension est l'une des valeurs suivantes : workspace, team, user, source, capability, vendor, model, region.

Réponse (UsageSummary)

{
  costUsd: number,       // coût total sur la plage
  co2Grams: number,      // estimation CO₂ totale (grammes CO₂e)
  tokensIn: number,
  tokensOut: number,
  runs: number,          // total des appels de capacité
  successes: number,
  groups: Array<{
    key: string,         // valeur de la dimension (ex. id d'espace de travail)
    costUsd: number,
    co2Grams: number,
    tokens: number,
    runs: number,
  }>,
}

Série temporelle

Retourne une série jour par jour pour visualiser la consommation dans le temps.

const { data, error } = await getAdminClient().billing.timeseries({
  organizationId: "org_abc123",
  range: { from: "2026-06-01T00:00:00Z", to: "2026-07-01T00:00:00Z" },
  granularity: "day",
  groupBy: "capability",  // optionnel
})

Requête

Réponse

{
  points: Array<{
    bucket: string,      // jour ISO (YYYY-MM-DD)
    costUsd: number,
    co2Grams: number,
    tokens: number,
    runs: number,
  }>,
}

Top-N

Retourne les N premières clés selon une métrique choisie sur une plage de dates — utile pour identifier les espaces de travail, modèles ou fournisseurs les plus coûteux.

const { data, error } = await getAdminClient().billing.topN({
  organizationId: "org_abc123",
  range: { from: "2026-06-01T00:00:00Z", to: "2026-07-01T00:00:00Z" },
  dimension: "model",
  metric: "cost_usd",
  limit: 10,
})

Requête

Réponse

{
  rows: Array<{
    key: string,    // valeur de la dimension
    value: number,  // total de la métrique
  }>,
}

Rétrofacturation

Retourne les totaux de coût, CO₂, tokens et exécutions par clé, ainsi que la part du total de l'organisation pour chaque clé. Utilisez ceci pour l'allocation interne des coûts.

const { data, error } = await getAdminClient().billing.chargeback({
  organizationId: "org_abc123",
  range: { from: "2026-06-01T00:00:00Z", to: "2026-07-01T00:00:00Z" },
  dimension: "workspace",
})

Réponse (ChargebackRow[])

Array<{
  key: string,        // valeur de la dimension (ex. id d'espace de travail)
  costUsd: number,
  co2Grams: number,
  tokens: number,
  runs: number,
  share: number,      // 0..1 — fraction du coût total de l'org
}>

Les valeurs de share sur toutes les lignes totalisent approximativement 1. Les événements sans valeur pour la dimension choisie sont regroupés sous "(unattributed)".

Facteurs carbone

Retourne la table complète des facteurs carbone utilisée pour calculer co2Grams sur chaque événement. Destiné aux auditeurs et aux rapports ESG.

const { data, error } = await getAdminClient().billing.carbonFactors({
  organizationId: "org_abc123",
})

Réponse

{
  version: string,                    // ex. "2026.06.0" — correspond à usage_event.carbon_version
  regionFallback: string,             // région utilisée quand la région du fournisseur est inconnue
  gridGco2PerKwh: Record<string, number>,    // gCO₂e par kWh par région
  energyWhPer1k: Record<string, number>,     // Wh pour 1k tokens/unités par classe de modèle
  pue: number,                        // multiplicateur d'efficacité de l'utilisation de l'énergie
  citation: string,                   // chaîne de provenance pour l'audit
}

Méthodologie carbone

Scrydon estime l'empreinte carbone des capacités IA à l'aide d'un modèle à trois facteurs :

CO₂ (g) = energy_per_1k_units_Wh × (total_tokens_or_units / 1000) × PUE × (grid_gco2_per_kwh / 1000)

• Énergie par 1k tokens (Wh) : Regroupée par classe de modèle (llm_large, llm_small, embedding, stt, etc.) en utilisant des estimations d'énergie par token publiées. Les classes non-token (STT, OCR, image, vidéo) utilisent des dénominateurs par seconde audio, par page ou par image.
• PUE (Power-Usage Effectiveness) : Un multiplicateur fixe de 1,12 — une valeur médiane dans la fourchette 1,1–1,2 publiée par les grands hyperscalers.
• Intensité carbone du réseau électrique (gCO₂e/kWh) : Valeurs spécifiques à la région issues de bases de données publiques d'intensité carbone du réseau électrique. Les requêtes sans région d'hébergement connue utilisent la moyenne mondiale en repli (436 gCO₂e/kWh).

La table des facteurs est versionnée (carbon_version). Chaque ligne usage_event enregistre la version en vigueur au moment de l'écriture, de sorte que les totaux historiques restent reproductibles après les mises à jour des facteurs. Récupérez la table courante et sa chaîne de provenance via billing.carbonFactors(...).

Rôle requis

Tous les appels billing.summary, billing.timeseries, billing.topN, billing.chargeback et billing.carbonFactors nécessitent une session administrateur d'organisation pour l'organizationId interrogé. Un membre non-administrateur reçoit une réponse 403 Forbidden.

billing.log est un endpoint M2M interne protégé par la capacité billing:admin. Il est appelé par le runtime de capacité — pas par le code produit ni par les consommateurs du SDK.

Voir aussi

• Administrateurs de plateforme et usurpation d'identité — comment confirmer votre rôle d'administrateur d'org.
• Intégrations — connexion des fournisseurs dont l'utilisation est mesurée ici.
• Conformité — comment la mesure d'utilisation s'applique à l'article 13 de l'EU AI Act et aux exigences d'attestation ESG.