Creați un registru de facturare API AI: cotați, rezervați, decontați și reconciliați fiecare apel de model

Facturarea API AI orientată către client nu poate fi un export lunar al utilizării brute a furnizorului. Dacă un gateway expune mai multe modele chiriașilor, echipelor sau partenerilor, facturarea trebuie să răspundă la o întrebare mai dificilă înainte de a exista factura: ar trebui să fie permisă această solicitare chiar acum și cum va fi explicat costul ei mai târziu?

Modelul practic este un registru de facturare cu patru etape: cotație, rezervare, decontare și reconciliere. Cotați costul probabil înainte de solicitare. Rezervați suficient buget pentru chiriaș pentru a acoperi cel mai rău caz permis. Decontați costul real după ce se cunoaște utilizarea. Reconciliați registrul gateway cu înregistrările furnizorului, astfel încât facturile să rămână susceptibile.

Acest articol descrie acea buclă de control pentru un gateway API cu mai multe modele. Este util dacă gateway-ul facturează echipele interne, clienții preplătiți, clienții agenției sau partenerii din aval.

Problema de facturare: utilizarea furnizorului nu este o factură a clientului

Realitate: furnizorii importanți de inteligență artificială nu expun un singur număr de simboluri universale sau un preț universal. OpenAI publică prețuri pe model cu rate separate de intrare, intrare în cache și rate de ieșire. Memorarea în cache a promptului OpenAI raportează utilizarea token-ului memorat în cache în câmpul de utilizare a răspunsului API. Documente antropice contoare separate pentru jetoane de intrare normale, jetoane de intrare pentru crearea cache-ului, jetoane de intrare de citire cache și jetoane de ieșire. Prețurile Gemini distinge intrarea, ieșirea și alte categorii de simboluri, inclusiv utilizarea specifică modalității, cum ar fi simbolurile audio.

Aceasta înseamnă că un gateway nu poate factura în siguranță prin înmulțirea total_tokens cu un preț. Are nevoie de adaptoare specifice furnizorului în spatele unei scheme de facturare neutră pentru furnizor.

Problema devine mai vizibilă în următoarele situații:

• Credite preplătite: gateway-ul trebuie să respingă cererile înainte ca chiriașul să cheltuiască sub zero.
• Markupuri pentru partener: partenerul are nevoie de propria factură pentru client, nu de o copie a facturii furnizorului.
• Transmitere în flux: răspunsul începe înainte de a fi cunoscută utilizarea finală a simbolului.
• Memorizare promptă în cache: intrarea în cache poate fi mai ieftină decât cea neînregistrată în cache, dar numai dacă este măsurată separat.
• Raționament și utilizarea instrumentului: unele modele expun dimensiuni suplimentare de utilizare, clase de ieșire ascunse sau unități media.
• Modificări ale prețului furnizorului: o factură de luna trecută trebuie să fie în continuare reproductibilă după modificarea unui tarif.

Recomandare: tratați facturarea ca pe un registru financiar numai pentru anexare, nu ca pe o interogare din tabloul de bord asupra jurnalelor de solicitări.

Arhitectura de bază

O arhitectură de facturare fiabilă are șase componente:

1. Cont de chiriaș: client, spațiu de lucru, client reseller sau centru de cost intern.
2. Serviciul de tarif: prețuri versiunea pentru furnizor, model, clasa de facturare, monedă și regula de markup.
3. Estimator: calculează o ofertă preflight din parametrii solicitării și politica modelului.
4. Registrul de rezervări: reține bugetul înainte de începerea apelului la furnizor.
5. Normalizarea utilizării: convertește câmpurile de utilizare specifice furnizorului în unități de facturare interne.
6. Lucrări de decontare și reconciliere: finalizați taxele și comparați-le cu înregistrările furnizorului.

Fluxul de control arată astfel:

solicitarea clientului
  -> autentificați chiriașul și cheia
  -> selectați modelul și versiunea tarifului
  -> estimați costul de intrare și de ieșire maxim
  -> rezervă soldul chiriașului
  -> furnizor de apeluri
  -> normalizează utilizarea returnată
  -> decontează costul real
  -> eliberați rezervarea nefolosită
  -> emite un eveniment registru gata pentru factură

Alegerea importantă a designului este că cererea nu este doar respectată. Este controlat financiar înainte și după execuție.

Pasul 1: citați înainte de apelul furnizorului

O ofertă înainte de zbor ar trebui să fie suficient de pesimistă pentru a impune bugetele, dar suficient de explicabilă pentru a fi afișată clienților sau partenerilor.

Intrarile includ de obicei:

• ID-ul locatarului și planul de facturare;
• ID cheie API sau ID proiect;
• ID-ul furnizorului și al modelului după aplicarea regulilor de rutare;
• jetoane de intrare estimate necache;
• eligibilitatea cunoscută pentru introducerea în cache, dacă este disponibilă;
• max_tokens, max_output_tokens sau limita de ieșire echivalentă;
• instrument, imagine, audio sau alți parametri de modalitate;
• regula de markup pentru partener, reducere sau preț pentru distribuitor;
• politica valutară și de rotunjire.

O formulă simplă de citate pentru generarea de text ar putea fi:

cost_estimat =
  estimated_uncached_input_tokens * rata_intrarilor
+ estimated_cached_input_tokens * cached_input_rate
+ max_output_tokens * output_rate+ request_fee
+ markup_partener

Recomandare: când lungimea finală a ieșirii este necunoscută, rezervați-vă față de ieșirea maximă configurată. Dacă aplicația lasă limita de ieșire nelimitată, gateway-ul ar trebui să aplice un chiriaș sau un model implicit. Executarea bugetului nu poate fi deterministă dacă nu există o răspundere maximă.

Acest lucru poate respinge unele solicitări care ar fi fost ieftine în practică. Acesta este compromisul. Pentru sistemele preplătite, implicit mai sigur este rezervarea pesimistă cu fonduri neutilizate eliberate după decontare. Pentru clienții companiei facturați, echipele pot permite depășiri ușoare și pot folosi cotația în principal pentru alerte.

Pasul 2: rezervați bugetul locatarului

Rezervarea protejează contul chiriașului de a cheltui mai mult decât soldul permis. Ar trebui să fie atomic: fie rezervarea reușește și apelul furnizorului poate începe, fie cererea este respinsă înainte ca orice cost al furnizorului să fie suportat.

O înregistrare a rezervării poate include:

{
  "reservation_id": "res_01J...",
  "tenant_id": "tenant_123",
  "api_key_id": "key_456",
  "request_id": "req_789",
  "provider": "example_provider",
  "model": "model-a",
  "rate_card_version": "2026-08-01",
  "quoted_amount": "0,032100",
  "currency": "USD",
  "status": "rezervat",
  "expires_at": "2026-08-11T12:05:00Z"
}

Utilizați perioade scurte de expirare a rezervărilor pentru erori de rețea și deconectări ale clienților. O lucrare de curățare ar trebui să elibereze rezervele expirate care nu au ajuns niciodată la soluționare. Cu toate acestea, nu eliberați o rezervare pur și simplu pentru că clientul s-a deconectat; apelul furnizorului s-ar putea în continuare să se finalizeze și să suporte costuri. Urmăriți separat starea solicitării furnizorului.

Recomandare: faceți rezervarea idempotent prin ID de solicitare sau cheia idempotity. Reîncercările de la clienți, gateway-uri sau lucrători nu ar trebui să creeze mai multe rețineri de buget pentru aceeași solicitare logică.

Pasul 3: normalizați utilizarea furnizorului

Răspunsurile furnizorului ar trebui convertite într-o schemă internă mică. Păstrați-l stabil chiar și atunci când furnizorii adaugă noi câmpuri de utilizare.

O schemă practică de utilizare normalizată:

{
  „input_uncached_tokens”: 1200,
  „input_cached_tokens”: 800,
  "cache_write_tokens": 0,
  „output_tokens”: 650,
  „rezoning_or_hidden_output_tokens”: 0,
  „tool_or_media_units”: [],
  „request_fee_units”: 1,
  "provider_request_id": "prov_abc",
  "usage_source": "provider_response",
  „este_estimat”: fals
}

Această schemă nu este în mod intenționat identică cu răspunsul niciunui furnizor. Captează dimensiunile de facturare de care au nevoie facturile, păstrând în același timp trapele de evacuare pentru unitățile specifice furnizorului.

Jetoanele din cache au nevoie de propria linie

Realitate: stocarea în cache a promptului poate avea un preț diferit față de intrarea necache. Dacă jetoanele din cache sunt îmbinate în totalul jetoane de intrare, clientul poate fi supraîncărcat sau gateway-ul poate subestima costul furnizorului. Intrările din cache ar trebui să apară ca propria clasă de facturare atât în registru, cât și în factură.

Scrierile în cache și citirile în cache nu sunt întotdeauna aceleași

Unii furnizori fac diferența între crearea de intrări în cache și citirea din cache. Normalizatorul nu ar trebui să presupună că intrarea în cache înseamnă întotdeauna o singură rată de facturare. Dacă un furnizor are jetoane de scriere cache și jetoane de citire cache, mapați-le separat sau păstrați-le ca subunități specifice furnizorului.

Raționamentul și rezultatul ascuns au nevoie de o politică

Unele modele expun utilizări legate de raționament sau contoare de ieșiri ascunse. Dacă furnizorul facturează pentru acele unități, gateway-ul trebuie să decidă dacă le afișează direct, le introduce într-o categorie de ieșire sau le afișează ca linie separată de factură.

Recomandare: facturile destinate clienților ar trebui să utilizeze un limbaj simplu. De exemplu: „semnificative de ieșire de raționament” este mai clar decât numele unui câmp de furnizor brut. Păstrați câmpurile brute disponibile pentru audit, dar nu forțați fiecare client să înțeleagă elementele interne ale furnizorului.

Pasul 4: stabiliți costul real

Decontarea convertește utilizarea normalizată în intrări finale în registru. Ar trebui să fie numai pentru atașare și să facă referire la versiunea cardului de tarife utilizată pentru solicitare.

Un eveniment stabilit ar putea arăta astfel:

{
  "ledger_event_id": "led_01J...",
  "event_type": "decontare",
  "tenant_id": "tenant_123",
  "request_id": "req_789",
  "reservation_id": "res_01J...",
  "provider": "example_provider",
  "model": "model-a",
  "rate_card_version": "2026-08-01",
  "linii": [
    {
      "billing_class": "input_uncached_tokens",
      "cantitate": 1200,
      „unitate”: „indicativ”,
      "unit_price": "0,00000250",
      "suma": "0,003000"
    },
    {
      "billing_class": "input_cached_tokens",
      "cantitate": 800,
      „unitate”: „indicativ”,
      "unit_price": "0,00000125",
      "suma": "0,001000"
    },
    {
      "billing_class": "jetoane de ieșire",
      "cantitate": 650,
      „unitate”: „indicativ”,"unit_price": "0,00001000",
      "suma": "0,006500"
    }
  ],
  "total_amount": "0,010500",
  "currency": "USD",
  "status": "stabilit"
}

Dacă solicitarea a fost rezervată pentru 0,032100 și decontată la 0,010500, registrul eliberează 0,021600 înapoi la soldul disponibil.

Recomandare: nu recalculați niciodată liniile de factură vechi din tabelul actual de prețuri. Stocați versiuni imuabile de tarif și atașați ID-ul versiunii la fiecare cotație, rezervare și eveniment de decontare. În caz contrar, o factură poate deveni imposibil de reprodus după ce un furnizor actualizează prețurile modelului.

Solicitări de streaming: rezervați mai întâi, soluționați mai târziu

Transmiterea în flux complică facturarea deoarece utilizatorul începe să primească rezultate înainte ca gateway-ul să cunoască utilizarea finală. Răspunsul este să nu săriți peste verificările preflight. Poarta de acces ar trebui să rezerve înainte de a deschide fluxul.

Utilizați acest flux de lucru:

1. Estimați jetoanele de intrare și costul maxim de ieșire.
2. Rezervați bugetul locatarului.
3. Deschide fluxul furnizorului.
4. Redirecționați bucăți către client.
5. Captați utilizarea finală atunci când furnizorul o trimite sau când este disponibilă o înregistrare ulterioară de utilizare.
6. Decontați costul real și eliberați rezervarea neutilizată.

Dacă utilizarea finală nu este disponibilă, marcați soluția ca estimată, în loc să pretindeți că este exactă:

"usage_source": "gateway_estimate",
„este_estimat”: adevărat,
„reconciliation_status”: „în așteptare”

Recomandare: reconcilierea zilnică ar trebui să acorde prioritate evenimentelor de streaming estimate, solicitărilor nereușite, expirărilor și reîncercărilor. Acestea sunt zonele cel mai probabil să creeze variații între înregistrările gateway-ului și facturile furnizorilor.

Reguli de versiuni și de marcare a tarifelor

O fișă de tarife ar trebui să fie un obiect cu versiuni, nu o foaie de calcul mutabilă.

Câmpuri minime:

• furnizor;
• ID model;
• clasa de facturare;
• unitatea, cum ar fi indicativul, cererea, imaginea, secunda audio sau unitatea instrumentului;
• prețul unitar;
• monedă;
• marcaje de timp efective de început și de sfârșit;
• politica de rotunjire;
• planul de chiriaș sau regulă de markup pentru partener;
• referința sursă și metadatele de aprobare.

Regulile de marcare ar trebui să fie explicite. De exemplu:

• Cost plus: costul furnizorului plus 20%.
• Comerț fix: chiriașul plătește un preț fix pentru token, indiferent de prețul furnizorului.
• Tiered: primele 10 milioane de jetoane la o singură rată, apoi o rată mai mică.
• Credite incluse: utilizarea consumă o alocație lunară înainte de începerea facturării pentru exces.

Compartiment: versiunea cardului de tarif adaugă muncă operațională, dar împiedică litigiile referitoare la facturi să devină arheologie. Un agent de asistență pentru clienți ar trebui să poată explica de ce o solicitare din 3 august a fost facturată la o anumită rată fără a verifica prețurile de astăzi ale furnizorului.

Separați registrul de facturare de analize

Analitica și facturarea au toleranțe diferite. Analytics poate fi agregat, amânat, eșantionat sau corectat. Facturarea trebuie să fie completă, idempotentă, auditabilă și explicabilă.

Utilizați statisticile pentru întrebări precum:

• Care echipe folosesc cele mai multe jetoane?
• Care modele cresc cel mai rapid?
• Unde poate reduce costurile memorarea promptă în cache?
• Care chei produc solicitări neobișnuit de costisitoare?

Utilizați registrul de facturare pentru întrebări precum:

• Această cerere a fost autorizată în raport cu soldul chiriașului?
• Ce versiune de tarif a produs această taxă?
• A fost eliberată rezervarea nefolosită?
• Factura clientului corespunde utilizării stabilite?
• Utilizarea gateway-ului se potrivește cu cea a furnizorului?

Realitate: convențiile semantice OpenTelemetry GenAI includ atribute de utilizare a simbolurilor, cum ar fi indicatoarele de intrare și de ieșire. Acest lucru este util pentru observabilitate și unirea urmelor la evenimentele de cost. Dar atributele de telemetrie nu înlocuiesc tarifele, rezervările, decontarea, rotunjirea și starea facturii.

Fluxul de lucru zilnic de reconciliere

Reconcilierea compară registrul decontat al gateway-ului cu utilizarea de către furnizor. Scopul nu este acordul perfect pe fiecare domeniu intermediar. Scopul este de a detecta variația materialului suficient de devreme pentru a corecta facturile, tarifele sau adaptoarele.

O muncă zilnică practică:

1. Grupați evenimentele registrului gateway în funcție de furnizor, model, chiriaș sau cheie API, clasa de facturare și ziua UTC.
2. Preluați utilizarea de către furnizor, grupată în funcție de parametri disponibili, cum ar fi ID-ul cheii API, modelul și ziua.
3. Normalizați exporturile furnizorului prin același cod de adaptor folosit pentru răspunsurile la solicitare, acolo unde este posibil.
4. Comparați cantitățile și costurile în funcție de clasa de facturare.
5. Semnalați variația peste praguri, cum ar fi diferența de cantitate de 0,5% sau orice diferență mare de cost absolută.
6. Clasificați cauzele variației: estimări în flux, reîncercări, solicitări nereușite, contabilitate în cache, modificări de alias de model, înregistrări întârziate ale furnizorilor sau ID-uri de solicitare lipsă.
7. Creați evenimente de ajustare în loc să editați evenimentele de decontare vechi.

Recomandare: folosiți cheile API ale furnizorului pentru fiecare locatar acolo unde este fezabil din punct de vedere operațional, deoarece simplifică reconcilierea. Dacă acest lucru creează prea multă sarcină generală de gestionare a cheilor, mapați ID-urile interne ale chiriașilor la metadatele furnizorului acolo unde sunt acceptate și păstrați o punte de identificare a cererii de încredere.

Liniile de factură pe care clienții le pot înțelege

O factură orientată spre client nu trebuie să oglindească furnizorul JSON. Ar trebui să explice factura în termeni comerciali stabili.

Coloane de factură utile:

• interval de date;
• chiriaș, proiect sau cheie API;
• model sau profil de model;
• număr de solicitări;
• jetoane de intrare necache;
• jetoane de intrare stocate în cache;
• jetoane de ieșire;
• unități media sau instrumente, dacă este cazul;
• reduceri, credite sau majorări;
• suma totală și moneda.

Pentru parteneri, includeți atât costul cu ridicata, cât și tariful cu amănuntul numai dacă modelul de afaceri o impune. Multe facturi ale distribuitorilor ar trebui să arate numai utilizarea de vânzare cu amănuntul, în timp ce tablourile de bord ale partenerilor pot afișa marja separat.

Compartiment: o schemă unificată a facturii îmbunătățește lizibilitatea, dar detaliile de facturare specifice furnizorului necesită totuși trape de evacuare. Păstrați liniile de factură simple în mod implicit și oferiți un export pentru clienții avansați care au nevoie de câmpuri detaliate de audit.

Lista de verificare a implementării

Înainte de lansare

• Definiți clase de facturare normalizate pentru toți furnizorii acceptați.
• Creați versiuni imuabile de tarife cu date de intrare în vigoare.
• Solicită limite de ieșire sau aplică valorile implicite ale gateway-ului.
• Implementați rezervările atomice cu chei de idempotnță.
• Setați reguli de rotunjire pentru fiecare monedă.
• Decideți cum să facturați jetoanele stocate în cache, jetoanele de raționament, unitățile media și solicitați taxe.
• Reîncercări de testare, expirări, deconectări ale clienților și erori ale furnizorului.
• Construiți un mecanism de ajustare a evenimentelor în loc să editați evenimentele stabilite.

În timpul procesării cererii

• Autentificați chiriașul și cheia.
• Rezolvați modelul final după rutare și politica de rezervă.
• Selectați versiunea corectă a tarifului.
• Citați costul în cel mai rău caz.
• Rezervați soldul sau respingeți solicitarea.
• Înregistrați ID-ul solicitării furnizorului atunci când este disponibil.
• Normalizați utilizarea din răspuns.
• Rezolvați, eliberați rezervarea neutilizată și emiteți evenimente pregătite pentru factură.

După gestionarea cererii

• Efectuați reconcilierea zilnică în funcție de furnizor, cheie, model, clasă de facturare și zi.
• Examinați așezările estimate în flux.
• Semnalați utilizarea modelului cu înregistrări lipsă din lista de tarife.
• Monitorizați variația cauzată de contabilizarea token-ului în cache.
• Generați previzualizări ale facturilor clienților înainte de facturarea finală.

Predicții de planificat

Predicție: facturarea AI API va deveni mai multidimensională, nu mai puțin. Clasele de jetoane, clasele cache, unitățile media, execuția instrumentului și contoarele legate de raționament sunt probabil să se extindă în continuare pe măsură ce se schimbă capabilitățile modelului.

Predicție: clienții se vor aștepta la explicații de utilizare la nivel de cerere, cheie, proiect și factură. Un total lunar fără elemente rând urmăribile va fi insuficient pentru echipele care revând acces la API sau impun bugete preplătite.

Predicție: gateway-urile care separă deja cotația, rezervarea, decontarea și reconcilierea se vor adapta mai rapid la noile modele de preț, deoarece pot adăuga clase de facturare fără a rescrie întregul sistem de factură.

Concluzie acționabilă

Dacă expuneți mai mulți furnizori de inteligență artificială printr-un singur gateway, creați registrul de facturare înainte ca litigiile de facturare să forțeze problema. Începeți cu patru garanții:

1. Fiecare cerere facturabilă primește o cotație preflight.
2. Fiecare chiriaș cu plată anticipată sau cu plafon are un buget rezervat înainte de începerea apelului la furnizor.
3. Fiecare răspuns al furnizorului este normalizat în clase de facturare stabile.
4. Fiecare factură poate fi reconciliată cu utilizarea de către furnizor și cu versiunea exactă a tarifului utilizată la momentul respectiv.

Această buclă de control face ca facturarea unificată AI API să fie înțeleasă pentru clienți, aplicabilă pentru creditele preplătite, flexibilă pentru markupurile pentru parteneri și auditabilă atunci când prețurile furnizorilor sau formatele de utilizare se modifică.

Lectură similară

• unirea urmelor LLM cu înregistrările privind utilizarea și costurile
• crearea de portaluri de reseller cu contorizare a utilizării chiriașilor
• utilizarea promptului cache în timp ce facturarea se înțeleg