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 un client explicite créé avec createClient(...) depuis @scrydon/multi-tenancy. Les exemples ci-dessous nomment ce client scrydon ; transmettez les en-têtes de session de l'appelant pour les requêtes d'administration d'organisation, ou les en-têtes de workload pour billing.log.

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 scrydon.billing.summary({
  organizationId: "org_abc123",
  range: { from: "2026-06-01T00:00:00Z", to: "2026-07-01T00:00:00Z" },
  groupBy: "workspace",            // optional
  filters: { capability: "llm" }, // optional dimension filter
})

Requête

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

Réponse (UsageSummary)

{
  costUsd: number,       // total cost over the range
  co2Grams: number,      // total CO₂ estimate (grams CO₂e)
  tokensIn: number,
  tokensOut: number,
  runs: number,          // total capability calls
  successes: number,
  groups: Array<{
    key: string,         // dimension value (e.g. workspace id)
    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 scrydon.billing.timeseries({
  organizationId: "org_abc123",
  range: { from: "2026-06-01T00:00:00Z", to: "2026-07-01T00:00:00Z" },
  granularity: "day",
  groupBy: "capability",  // optional
})

Requête

Réponse

{
  points: Array<{
    bucket: string,      // ISO day (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 scrydon.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,    // dimension value
    value: number,  // metric total
  }>,
}

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 scrydon.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,        // dimension value (e.g. workspace id)
  costUsd: number,
  co2Grams: number,
  tokens: number,
  runs: number,
  share: number,      // 0..1 — fraction of org-total cost
}>

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 scrydon.billing.carbonFactors({
  organizationId: "org_abc123",
})

Réponse

{
  version: string,                    // e.g. "2026.06.0" — matches usage_event.carbon_version
  regionFallback: string,             // region used when vendor region is unknown
  gridGco2PerKwh: Record<string, number>,    // gCO₂e per kWh by region
  energyWhPer1k: Record<string, number>,     // Wh per 1k tokens/units by model class
  pue: number,                        // power-usage effectiveness multiplier
  citation: string,                   // provenance string for 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.