resources/finops.ts
Source : sdks/typescript/packages/sdk/src/resources/finops.ts. Retour à l'index de la référence du SDK TypeScript.
Cette page est générée par tools/docs/gen_sdk_reference.py depuis les sources du SDK et les dossiers de textes OpenAPI. Ne la modifiez pas à la main : changez la source et régénérez.
Interface TokenUnits
Unités de jetons d'un Usage Event ; les jetons en cache font partie de l'entrée et les jetons de raisonnement de la sortie.
Champs :
| Nom | Type | Requis | Description |
|---|---|---|---|
input_tokens | number | oui | Total des jetons d'entrée indiqué par le fournisseur. |
output_tokens | number | oui | Total des jetons de sortie indiqué par le fournisseur. |
cached_input_tokens | number | non | Jetons d'entrée servis depuis le cache, inclus dans input_tokens. |
reasoning_tokens | number | non | Jetons de raisonnement explicites, au moins 0 ; remplacent la réserve de reasoning_effort. |
Alias de type ReconciliationSource
Format d'un import de facture : openai, anthropic, aws_cur, azure, gcp ou generic_csv.
Définition : "openai" \| "anthropic" \| "aws_cur" \| "azure" \| "gcp" \| "generic_csv".
Interface FinOpsSettings
Réglages FinOps du tenant : devise, budget mensuel, seuil d'écart et durée de vie des réservations.
Champs :
| Nom | Type | Requis | Description |
|---|---|---|---|
currency | string | oui | Code de devise ISO 4217, par exemple EUR. |
monthly_budget | string | null | oui | Budget mensuel du tenant, au moins 0 : la dépense mesurée du mois lui est comparée et des alertes de budget se déclenchent aux seuils (50, 80 et 100 pour cent par défaut). Il ne refuse pas d'appel par lui-même ; utilisez pour cela des quotas stricts. |
variance_threshold_pct | string | oui | Écart entre coût mesuré et coût facturé, en pour cent, au-delà duquel une alerte d'écart est levée (10 par défaut). |
reservation_ttl_seconds | number | oui | Durée de vie par défaut d'une réservation de quota en secondes, supérieure à 0 (900 par défaut). |
Alias de type SummaryGroupBy
Regroupement de FinOpsResource.summary : tenant, project, agent, model, provider, usage_type ou day.
Définition : "tenant" \| "project" \| "agent" \| "model" \| "provider" \| "usage_type" \| "day".
Classe FinOpsResource
FinOps. Gestion des coûts de l'usage de l'IA : grilles tarifaires, événements d'usage, estimations, quotas et réservations, répartition du coût des GPU, rapprochement de la facturation et alertes.
Resource
Attributs :
| Nom | Type | Requis | Description |
|---|---|---|---|
alerts | Alerts | oui | Alertes FinOps (GET /v1/finops/alerts). |
allocationPolicies | AllocationPolicies | oui | Politiques de répartition des coûts : list et create sur /v1/finops/allocation-policies. |
fxRates | FxRates | oui | Taux de change : list et put sur /v1/finops/fx-rates. |
gpu | Gpu | oui | Usage GPU : ingestSamples et allocation sur /v1/finops/gpu. |
priceCards | PriceCards | oui | Grilles tarifaires : list, create, get et retire sur /v1/finops/price-cards. |
reconciliation | Reconciliation | oui | Rapprochement avec les factures des fournisseurs : imports, exécution et rapport (/v1/finops/reconciliation). |
settings | Settings | oui | Réglages FinOps du tenant : get et update sur /v1/finops/settings. |
usage | Usage | oui | Usage Events : ingest, ingestBatch, list et iterate sur /v1/finops/usage. |
FinOpsResource.checkBudget
checkBudget(query: { agent?: string; project?: string; run?: string } = {}, opts?: CallOptions)
Lire la consommation des quotas. Chaque quota du tenant avec sa fenêtre courante et le coût et les jetons consommés et réservés dans celle-ci. Les quotas par exécution demandent run pour trouver leur fenêtre. Demande un rôle de lecteur et un principal de tenant.
Route : /v1/quotas/usage (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
query | { agent?: string; project?: string; run?: string } | {} | non | Paramètres de la chaîne de requête de la route. |
opts | CallOptions | non | Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes). |
Erreurs levées : les erreurs typées du transport (Erreurs).
FinOpsResource.createMediaPrice
createMediaPrice(body: Doc, opts?: CallOptions)
Ajouter une révision de prix de média. Ajoute une révision de prix datée pour une unité de média et répond 201. Une révision ne réécrit jamais une révision plus ancienne. Les mêmes unité, fournisseur, ressource et date de début répondent 409 media_price_exists ; un champ invalide 422 media_price_invalid. Audité. Demande finops ou tenant_admin, et un principal de tenant.
Route : /v1/finops/media-prices (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
body | Doc | oui | unit (audio_second, image, video_second, gpu_second, storage_gb_month), provider, unit_price (nombre, au moins 0), currency (ISO 4217), source (origine du prix, obligatoire), et facultativement resource (* par défaut, tout le fournisseur) et effective_from (ISO 8601, maintenant par défaut). | |
opts | CallOptions | non | Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes). |
Erreurs levées : les erreurs typées du transport (Erreurs).
FinOpsResource.estimate
estimate(body: Doc, opts?: CallOptions)
Estimer le coût d'un appel. Valorise un appel prévu avec la grille tarifaire en vigueur (motif de modèle et région les plus précis d'abord), le convertit dans la devise du tenant et le compare aux quotas correspondants, sans rien réserver. Les jetons de raisonnement sont ajoutés selon le mode de facturation de la grille. Sans grille : 404 price_card_not_found ; sans taux de change : 422 fx_rate_missing. Demande un rôle d'usage ou de lecteur et un principal de tenant.
Route : /v1/finops/estimate (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
body | Doc | oui | L'appel prévu à valoriser. | |
opts | CallOptions | non | Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes). |
Erreurs levées : les erreurs typées du transport (Erreurs).
FinOpsResource.estimateMediaCost
estimateMediaCost(body: Doc, opts?: CallOptions)
Estimer des coûts de médias. Valorise jusqu'à 100 éléments de médias avec la révision en vigueur à leur date (ressource exacte d'abord, puis la révision * du fournisseur). Un élément sans prix revient avec amount: null, status: unavailable et reason: price_unknown ; total n'est donné que si tous les éléments sont valorisés dans une seule devise (complete: true). Des éléments invalides répondent 422 media_price_invalid avec le champ. Demande un rôle de lecteur ou agent, et un principal de tenant.
Route : /v1/finops/media-costs/estimate (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
body | Doc | oui | items : de 1 à 100 objets avec unit (audio_second, image, video_second, gpu_second, storage_gb_month), provider, quantity (nombre positif), et facultativement resource (* par défaut) et at (ISO 8601, maintenant par défaut). | |
opts | CallOptions | non | Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes). |
Erreurs levées : les erreurs typées du transport (Erreurs).
FinOpsResource.mediaPrices
mediaPrices(query: { unit?: string } = {}, opts?: CallOptions)
Lister les prix des médias. Révisions datées des prix des médias du tenant par unité, fournisseur, ressource et date, avec la liste des unités prises en charge. Une unité inconnue répond 422 media_price_invalid. Demande un rôle de lecteur et un principal de tenant.
Route : /v1/finops/media-prices (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
query | { unit?: string } | {} | non | Paramètres de la chaîne de requête de la route. |
opts | CallOptions | non | Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes). |
Erreurs levées : les erreurs typées du transport (Erreurs).
FinOpsResource.recordUsage
recordUsage(event: UsageEvent | Doc, opts?: CallOptions)
Ingérer un événement d'usage. Valide un Usage Event v1, le valorise (coût mesuré dans la devise du tenant) et l'enregistre ; répond 201, ou 200 avec duplicate: true si le même event_id était déjà enregistré. Un événement invalide répond 422 usage_event_invalid avec les erreurs ; un événement d'un autre tenant 403 usage_tenant_mismatch. Un événement d'audit par appel, jamais le contenu. Demande finops, tenant_admin, agent ou developer, et un principal de tenant.
Route : /v1/finops/usage (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
event | UsageEvent | Doc | oui | Usage Event à enregistrer ; envoyer deux fois le même event_id ne l'enregistre qu'une fois. | |
opts | CallOptions | non | Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes). |
Erreurs levées : les erreurs typées du transport (Erreurs).
FinOpsResource.reserve
reserve(body: ReserveBody, opts?: CallOptions)
Réserver un coût et des jetons. Réserve un montant sur chaque quota actif correspondant à la portée (les quotas du tenant correspondent toujours ; un principal utilisateur ajoute sa propre portée utilisateur) et répond 201 avec la réservation, ses éléments par quota et fenêtre, les quotas souples dépassés et son échéance. Un quota strict qui serait dépassé répond 429 quota_exceeded avec Retry-After: 60, et rien n'est réservé. Les réservations expirées sont d'abord libérées. Audité. Demande finops, tenant_admin, agent ou developer, et un principal de tenant.
Route : /v1/quotas/reserve (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
body | ReserveBody | oui | Montant, portée et durée de vie de la réservation. | |
opts | CallOptions | non | Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes). |
Erreurs levées : les erreurs typées du transport (Erreurs).
FinOpsResource.summary
summary(query: { group_by?: SummaryGroupBy; from?: string; to?: string } & Query = {}, opts?: CallOptions)
Synthétiser la dépense. Événements d'usage du tenant regroupés selon une dimension, par devise : nombre d'événements, jetons, secondes GPU, montants estimés, mesurés et facturés (le facturé vaut null si rien n'a été rapproché). Un regroupement inconnu répond 400 finops_group_by_invalid. Demande un rôle de lecteur et un principal de tenant.
Route : /v1/finops/summary (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
query | { group_by?: SummaryGroupBy; from?: string; to?: string } & Query | {} | non | Paramètres de la chaîne de requête de la route. |
opts | CallOptions | non | Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes). |
Erreurs levées : les erreurs typées du transport (Erreurs).
Interface QuotaReservation
Réponse de POST /v1/quotas/reserve, commit et release ; id est l'identifiant de la réservation.
Doc
Champs :
| Nom | Type | Requis | Description |
|---|---|---|---|
id | string | oui | Identifiant de la réservation, utilisé pour la valider ou la libérer. |
tenant_id | string | oui | Locataire de l'agent. default par défaut. |
status | "reserved" | "committed" | "released" | "expired" | string | oui | reserved, committed, released ou expired. |
amount | { cost: { amount: string; currency: string }; tokens: number } | oui | Coût réservé (montant et devise) et jetons. |
expires_at | string | oui | Date et heure (ISO 8601, UTC) après lesquelles l'élément n'est plus valide. |
quotas | Doc[] | oui | Quotas sur lesquels la réservation est imputée. |
soft_exceeded | Doc[] | oui | Quotas souples que la réservation dépasse. |
Interface ReserveBody
Corps de POST /v1/quotas/reserve : coût, jetons, périmètre et durée de vie de la réservation.
Champs :
| Nom | Type | Requis | Description |
|---|---|---|---|
cost | string | number | non | Coût à réserver. |
tokens | number | non | Jetons à réserver. |
scope | Doc | non | Ce qui est sauvegardé (clusters, services, jeux de données), sous forme d'objet. |
ttl_seconds | number | non | Durée de vie en secondes. Une fois écoulée, l'élément expire et n'est plus accepté. |
Interface CommitBody
Corps de QuotasResource.commit : le coût et les jetons mesurés de la réservation.
Champs :
| Nom | Type | Requis | Description |
|---|---|---|---|
cost | string | number | non | Coût mesuré à valider. |
tokens | number | non | Jetons mesurés à valider. |
Interface WithReservationOptions
Options de QuotasResource.withReservation.
Champs :
| Nom | Type | Requis | Description |
|---|---|---|---|
commitBody | (result: T) => CommitBody | non | Construit le corps de validation (coût et jetons mesurés) à partir du résultat de la fonction. |
opts | CallOptions | non | Options par appel acceptées par toutes les méthodes du SDK. |
Interface QuotaCreate
Corps de POST /v1/quotas.
Doc
Champs :
| Nom | Type | Requis | Description |
|---|---|---|---|
name | string | oui | Nom du quota. |
scope_type | "tenant" | "project" | "user" | "agent" | "model" | "provider" | non | Ce que le quota limite : tenant (par défaut), project, agent, user, model ou provider. |
scope_value | string | non | Identifiant du projet, de l'agent, de l'utilisateur, du modèle ou du fournisseur ; obligatoire sauf si scope_type vaut tenant, où il doit être null. |
period | "request" | "run" | "hour" | "day" | "month" | non | Période du quota : request, run, hour, day ou month. |
limit_cost | string | number | non | Limite de coût sur la période. |
limit_tokens | number | non | Limite de jetons sur la période. |
currency | string | non | Code de devise ISO 4217, par exemple EUR. |
enforcement | "hard" | "soft" | non | hard refuse au-delà de la limite, soft se contente de le signaler. |
enabled | boolean | non | Indique si le quota est appliqué. |
Classe QuotasResource
FinOps. Gestion des coûts de l'usage de l'IA : grilles tarifaires, événements d'usage, estimations, quotas et réservations, répartition du coût des GPU, rapprochement de la facturation et alertes.
Resource
Attributs :
| Nom | Type | Requis | Description |
|---|---|---|---|
fn | (reservation: QuotaReservation) | oui | Fonction de withReservation, exécutée avec la réservation. |
options | WithReservationOptions<T> | oui | Options de withReservation : constructeur du corps de validation et options par appel. |
reserveBody | ReserveBody, | oui | Corps de la réservation effectuée par withReservation. |
QuotasResource.commit
commit(id: string, body: CommitBody = {}, opts?: CallOptions)
Valider une réservation. Remplace le montant réservé par le montant mesuré sur chaque fenêtre de quota de la réservation et vérifie les seuils d'alerte. Une réservation close répond 409 reservation_closed ; une réservation inconnue 404 reservation_not_found. Audité. Demande finops, tenant_admin, agent ou developer, et un principal de tenant.
Route : /v1/quotas/{reservation_id}/commit (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
id | string | oui | Identifiant (UUID) de la réservation renvoyé par POST /v1/quotas/reserve. | |
body | CommitBody | {} | non | Coût et jetons mesurés de l'appel. |
opts | CallOptions | non | Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes). |
Erreurs levées : les erreurs typées du transport (Erreurs).
QuotasResource.create
create(body: QuotaCreate, opts?: CallOptions)
Créer un quota. Crée un quota du tenant et répond 201. Une limite de coût ou de jetons est obligatoire, et scope_value est obligatoire sauf si scope_type vaut tenant (422 validation_error). Sans devise, celle du tenant s'applique. Audité. Demande finops ou tenant_admin, et un principal de tenant.
Route : /v1/quotas (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
body | QuotaCreate | oui | Le nouveau quota. | |
opts | CallOptions | non | Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes). |
Erreurs levées : les erreurs typées du transport (Erreurs).
QuotasResource.delete
delete(id: string, opts?: CallOptions)
Supprimer un quota. Supprime un quota du tenant et répond 204. Identifiant inconnu : 404 quota_not_found. Audité (finops.quota.delete). Demande finops ou tenant_admin.
Route : /v1/quotas/{quota_id} (DELETE).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
id | string | oui | Identifiant (UUID) du quota. | |
opts | CallOptions | non | Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes). |
Erreurs levées : les erreurs typées du transport (Erreurs).
QuotasResource.list
list(params?: ListParams, opts?: CallOptions)
Lister les quotas. Quotas du tenant par nom, y compris ceux reproduits depuis les projets LLM (llm-project:...). Une seule page. Demande un rôle de lecteur et un principal de tenant.
Route : /v1/quotas (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
params | ListParams | non | Champs supplémentaires fusionnés dans la requête. | |
opts | CallOptions | non | Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes). |
Erreurs levées : les erreurs typées du transport (Erreurs).
QuotasResource.release
release(id: string, opts?: CallOptions)
Libérer une réservation. Rend le montant réservé à chaque fenêtre de quota de la réservation sans rien consommer (l'appel a échoué ou n'a pas eu lieu). Une réservation close répond 409 reservation_closed ; une réservation inconnue 404 reservation_not_found. Audité. Demande finops, tenant_admin, agent ou developer, et un principal de tenant.
Route : /v1/quotas/{reservation_id}/release (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
id | string | oui | Identifiant (UUID) de la réservation. | |
opts | CallOptions | non | Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes). |
Erreurs levées : les erreurs typées du transport (Erreurs).
QuotasResource.replace
replace(id: string, body: Doc, opts?: CallOptions)
Remplacer un quota. Remplace tous les champs d'un quota (mêmes règles qu'à la création ; sans devise, la devise actuelle est conservée). Identifiant inconnu : 404 quota_not_found. Audité. Demande finops ou tenant_admin, et un principal de tenant.
Route : /v1/quotas/{quota_id} (PUT).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
id | string | oui | Identifiant (UUID) du quota. | |
body | Doc | oui | Le quota complet. | |
opts | CallOptions | non | Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes). |
Erreurs levées : les erreurs typées du transport (Erreurs).
QuotasResource.reserve
reserve(body: ReserveBody, opts?: CallOptions)
Réserver un coût et des jetons. Réserve un montant sur chaque quota actif correspondant à la portée (les quotas du tenant correspondent toujours ; un principal utilisateur ajoute sa propre portée utilisateur) et répond 201 avec la réservation, ses éléments par quota et fenêtre, les quotas souples dépassés et son échéance. Un quota strict qui serait dépassé répond 429 quota_exceeded avec Retry-After: 60, et rien n'est réservé. Les réservations expirées sont d'abord libérées. Audité. Demande finops, tenant_admin, agent ou developer, et un principal de tenant.
Route : /v1/quotas/reserve (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
body | ReserveBody | oui | Montant, portée et durée de vie de la réservation. | |
opts | CallOptions | non | Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes). |
Erreurs levées : les erreurs typées du transport (Erreurs).
QuotasResource.usage
usage(query?: Query, opts?: CallOptions)
Lire la consommation des quotas. Chaque quota du tenant avec sa fenêtre courante et le coût et les jetons consommés et réservés dans celle-ci. Les quotas par exécution demandent run pour trouver leur fenêtre. Demande un rôle de lecteur et un principal de tenant.
Route : /v1/quotas/usage (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
query | Query | non | Paramètres de la chaîne de requête de la route. | |
opts | CallOptions | non | Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes). |
Erreurs levées : les erreurs typées du transport (Erreurs).
QuotasResource.withReservation
async withReservation(reserveBody: ReserveBody, fn: (reservation: QuotaReservation) = Promise<T>, options: WithReservationOptions<T> = {},): Promise<T>
Réserve du quota, exécute fn, puis valide en cas de succès ou libère en cas d'échec ; l'erreur de la fonction est relancée après la libération.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
reserveBody | ReserveBody | oui | Coût, jetons, périmètre et durée de vie à réserver. | |
fn | (reservation: QuotaReservation) | Promise<T>, options: WithReservationOptions<T> = {}, | non | Travail à exécuter sous la réservation. |
Retour : Promise<T>. Résultat de fn.
Fonctions
tokenUnits
tokenUnits(input: number, output: number, detail: { cached?: number; reasoning?: number } = {}): TokenUnits
Unités de jetons selon la règle FinOps : input_tokens inclut déjà les jetons en cache et output_tokens inclut déjà les jetons de raisonnement (totaux du fournisseur, jamais ajoutés en plus).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
input | number | oui | Total des jetons d'entrée. | |
output | number | oui | Total des jetons de sortie. | |
detail | { cached?: number; reasoning?: number } | {} | non | Jetons en cache et de raisonnement, chacun au plus égal à son total. |
Retour : TokenUnits. Les unités, avec les champs de cache et de raisonnement seulement s'ils ne sont pas nuls ; lève RangeError quand une part dépasse son total.
Erreurs levées : RangeError.