Vytvorte účtovnú knihu AI API: Cenová ponuka, rezervácia, vyrovnanie a zosúladenie každého modelového hovoru

Customer-facing AI API billing nemôže byť mesačným exportom nespracovaného využitia poskytovateľa. Ak brána sprístupňuje nájomníkom, tímom alebo partnerom viacero modelov, fakturácia musí odpovedať na ťažšiu otázku, kým faktúra vznikne: mala by byť táto požiadavka povolená práve teraz a ako sa jej cena vysvetlí neskôr?

Praktický vzor je účtovná kniha so štyrmi fázami: ponuka, rezervácia, vyrovnanie a vyrovnanie. Pred požiadaním uveďte pravdepodobnú cenu. Vyhraďte si dostatočný rozpočet nájomcu na pokrytie povoleného najhoršieho prípadu. Urovnajte skutočné náklady po tom, čo je známe použitie. Zosúladiť účtovnú knihu brány so záznamami na strane poskytovateľa, aby faktúry zostali obhájiteľné.

Tento článok popisuje túto riadiacu slučku pre viacmodelovú bránu API. Je to užitočné, či brána účtuje interným tímom, predplateným zákazníkom, agentúrnym klientom alebo následným partnerom.

Problém s fakturáciou: používanie poskytovateľa nie je faktúra pre zákazníka

Fakt: hlavní poskytovatelia umelej inteligencie neuvádzajú jedno univerzálne počítadlo tokenov ani jednu univerzálnu cenu. OpenAI zverejňuje ceny za jednotlivé modely so samostatnými sadzbami vstupov, vstupov vo vyrovnávacej pamäti a výstupov. OpenAI rýchle ukladanie do vyrovnávacej pamäte hlási použitie tokenu uloženého vo vyrovnávacej pamäti v poli API využitie odpovede. Anthropic dokumentuje samostatné počítadlá pre normálne vstupné tokeny, vstupné tokeny na vytvorenie vyrovnávacej pamäte, vstupné tokeny na čítanie z vyrovnávacej pamäte a výstupné tokeny. Gemini Ceny rozlišujú vstup, výstup a ďalšie kategórie tokenov vrátane použitia špecifického pre modality, ako sú zvukové tokeny.

To znamená, že brána nemôže bezpečne účtovať vynásobením total_tokens jednou cenou. Vyžaduje si to adaptéry špecifické pre poskytovateľa za fakturačnou schémou neutrálnou voči poskytovateľovi.

Problém sa stáva viditeľnejším v týchto situáciách:

• Predplatené kredity: brána musí odmietnuť žiadosti skôr, ako nájomca minie pod nulu.
• Značky partnera: partner potrebuje vlastnú faktúru pre zákazníka, nie kópiu účtu poskytovateľa.
• Streamovanie: odpoveď začína skôr, ako je známe konečné využitie tokenu.
• Výzva ukladanie do vyrovnávacej pamäte: Vstup z vyrovnávacej pamäte môže byť lacnejší ako vstup bez vyrovnávacej pamäte, ale iba ak sa meria samostatne.
• Zdôvodnenie a použitie nástroja: niektoré modely odhaľujú ďalšie dimenzie používania, skryté triedy výstupu alebo mediálne jednotky.
• Zmeny cien poskytovateľa: faktúra z minulého mesiaca musí byť reprodukovateľná aj po zmenách cenníka.

Odporúčanie: zaobchádzajte s fakturáciou ako s finančnou knihou, ktorá sa len pripája, nie ako s dotazom na informačnom paneli nad denníkmi požiadaviek.

Základná architektúra

Spoľahlivá architektúra fakturácie má šesť komponentov:

1. Účet nájomcu: zákazník, pracovný priestor, klient predajcu alebo interné nákladové stredisko.
2. Služba cenníka: verzie cien pre poskytovateľa, model, triedu fakturácie, menu a pravidlo prirážky.
3. Estimator: vypočíta cenovú ponuku pred výstupom z parametrov požiadavky a pravidiel modelu.
4. Kniha rezervácií: obsahuje rozpočet pred začatím hovoru s poskytovateľom.
5. Usage normalizer: konvertuje polia používania špecifické pre poskytovateľa na interné fakturačné jednotky.
6. Úlohy týkajúce sa vyrovnania a vyrovnania: finalizujte poplatky a porovnajte ich so záznamami na strane poskytovateľa.

Tok ovládania vyzerá takto:

client request
  -> authenticate tenant and key
  -> select model and rate-card version
  -> estimate input and max output cost
  -> reserve tenant balance
  -> call provider
  -> normalize returned usage
  -> settle actual cost
  -> release unused reservation
  -> emit invoice-ready ledger event

Dôležitou voľbou dizajnu je, že požiadavka nie je len dodržaná. Je finančne kontrolovaný pred a po vykonaní.

Krok 1: cenová ponuka pred hovorom poskytovateľa

Cenová ponuka pred výstupom by mala byť dostatočne pesimistická na presadzovanie rozpočtov, ale dostatočne vysvetliteľná, aby sa ukázala zákazníkom alebo partnerom.

Vstupy zvyčajne zahŕňajú:

• ID nájomníka a plán fakturácie;
• API ID kľúča alebo ID projektu;
• ID poskytovateľa a modelu po použití pravidiel smerovania;
• estimated neuložené vstupné tokeny;
• známa vhodnosť pre vstup z vyrovnávacej pamäte, ak je k dispozícii;
• max_tokens, max_output_tokens alebo ekvivalentné obmedzenie výstupu;
• parametre nástroja, obrázka, zvuku alebo inej modality;
• pravidlo označovania, zľavy alebo ceny pre partnera;
• zásady meny a zaokrúhľovania.

Jednoduchý vzorec citácie na generovanie textu môže byť:

estimated_cost =
  estimated_uncached_input_tokens * input_rate
+ estimated_cached_input_tokens   * cached_input_rate
+ max_output_tokens               * output_rate
+ request_fee
+ partner_markup

Odporúčanie: ak nie je známa konečná dĺžka výstupu, rezervujte si podľa nakonfigurovaného maximálneho výkonu. Ak aplikácia ponechá výstupný limit neohraničený, brána by mala použiť predvolené nastavenie nájomníka alebo modelu. Presadzovanie rozpočtu nemôže byť deterministické, ak neexistuje maximálna zodpovednosť.

Môžete odmietnuť niektoré žiadosti, ktoré by v praxi boli lacné. To je ten kompromis. Pre predplatené systémy je bezpečnejším východiskom pesimistická rezervácia s nevyužitými prostriedkami uvoľnenými po zúčtovaní. Pre podnikových zákazníkov s fakturáciou môžu tímy povoliť mierne prekročenia a cenovú ponuku použiť hlavne na upozornenia.

Krok 2: Rezervovať rozpočet nájomcu

Rezervácia chráni účet nájomcu pred míňaním viac, než je povolený zostatok. Mala by byť atómová: buď bude rezervácia úspešná a hovor poskytovateľa sa môže začať, alebo sa žiadosť zamietne skôr, ako sa vynaložia akékoľvek náklady poskytovateľa.

Záznam rezervácie môže obsahovať:

{
  "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": "reserved",
  "expires_at": "2026-08-11T12:05:00Z"
}

Použite krátke uplynutie platnosti rezervácie pre zlyhania siete a odpojenia klienta. Úloha čistenia by mala uvoľniť rezervácie s vypršanou platnosťou, ktoré nikdy nedosiahli vyrovnanie. Neuvoľňujte však rezerváciu len preto, že sa klient odpojil; hovor poskytovateľa sa môže aj tak dokončiť a môže byť spoplatnený. Samostatne sledujte stav žiadosti poskytovateľa.

Odporúčanie: urobte rezerváciu idempotentnou pomocou ID žiadosti alebo kľúča idempotencie. Opätovné pokusy od klientov, brán alebo pracovníkov by nemali vytvárať viaceré pozastavenia rozpočtu pre rovnakú logickú požiadavku.

Krok 3: normalizujte používanie poskytovateľa

Odpovede poskytovateľa by sa mali previesť na malú internú schému. Udržujte ho stabilný, aj keď poskytovatelia pridávajú nové polia použitia.

Praktická schéma normalizovaného použitia:

{
  "input_uncached_tokens": 1200,
  "input_cached_tokens": 800,
  "cache_write_tokens": 0,
  "output_tokens": 650,
  "reasoning_or_hidden_output_tokens": 0,
  "tool_or_media_units": [],
  "request_fee_units": 1,
  "provider_request_id": "prov_abc",
  "usage_source": "provider_response",
  "is_estimated": false
}

Táto schéma nie je zámerne identická s odpoveďou žiadneho poskytovateľa. Zachytáva fakturačné rozmery, ktoré faktúry potrebujú, pričom zachováva únikové otvory pre jednotky špecifické pre poskytovateľa.

Tokeny vo vyrovnávacej pamäti potrebujú svoj vlastný riadok

Fakt: Cena rýchleho ukladania do vyrovnávacej pamäte sa môže líšiť od ceny vstupu bez vyrovnávacej pamäte. Ak sa tokeny uložené vo vyrovnávacej pamäti zlúčia do celkových vstupných tokenov, zákazníkovi sa môže účtovať nadmerná cena alebo môže brána podhodnotiť náklady poskytovateľa. Vstup uložený vo vyrovnávacej pamäti by sa mal objaviť ako vlastná fakturačná trieda v účtovnej knihe aj na faktúre.

Zápisy do vyrovnávacej pamäte a čítania z vyrovnávacej pamäte nie sú vždy rovnaké

Niektorí poskytovatelia rozlišujú medzi vytváraním záznamov z vyrovnávacej pamäte a čítaním z vyrovnávacej pamäte. Normalizátor by nemal predpokladať, že vstup z vyrovnávacej pamäte vždy znamená jednu fakturačnú sadzbu. Ak má poskytovateľ tokeny na zápis do vyrovnávacej pamäte a tokeny na čítanie z vyrovnávacej pamäte, namapujte ich samostatne alebo ich zachovajte ako podjednotky špecifické pre poskytovateľa.

Uvažovanie a skrytý výstup si vyžadujú politiku

Niektoré modely odhaľujú používanie súvisiace s uvažovaním alebo skryté výstupné počítadlá. Ak poskytovateľ účtuje tieto jednotky, brána sa musí rozhodnúť, či ich zobrazí priamo, zaradí ich do výstupnej kategórie alebo ich uvedie ako samostatný riadok faktúry.

Odporúčanie: Faktúry vystavené zákazníkom by mali používať jednoduchý jazyk. Napríklad: „výstupné tokeny odôvodnenia“ je jasnejšie ako nespracovaný názov poľa poskytovateľa. Udržujte nespracované polia dostupné pre audit, ale nenúťte každého zákazníka, aby porozumel interným informáciám poskytovateľa.

4. krok: zúčtovanie skutočných nákladov

Vyrovnanie prevádza normalizované používanie na konečné položky hlavnej knihy. Mala by obsahovať iba prílohu a odkazovať na verziu cenníka použitú v žiadosti.

Vyrovnaná udalosť môže vyzerať takto:

{
  "ledger_event_id": "led_01J...",
  "event_type": "settlement",
  "tenant_id": "tenant_123",
  "request_id": "req_789",
  "reservation_id": "res_01J...",
  "provider": "example_provider",
  "model": "model-a",
  "rate_card_version": "2026-08-01",
  "lines": [
    {
      "billing_class": "input_uncached_tokens",
      "quantity": 1200,
      "unit": "token",
      "unit_price": "0.00000250",
      "amount": "0.003000"
    },
    {
      "billing_class": "input_cached_tokens",
      "quantity": 800,
      "unit": "token",
      "unit_price": "0.00000125",
      "amount": "0.001000"
    },
    {
      "billing_class": "output_tokens",
      "quantity": 650,
      "unit": "token",
      "unit_price": "0.00001000",
      "amount": "0.006500"
    }
  ],
  "total_amount": "0.010500",
  "currency": "USD",
  "status": "settled"
}

Ak bola požiadavka rezervovaná pre 0.032100 a vyrovnaná na 0.010500, účtovná kniha uvoľní 0.021600 späť na disponibilný zostatok.

Odporúčanie: nikdy neprepočítavajte staré riadky faktúry z aktuálnej cenovej tabuľky. Uložte si nemenné verzie cenníka a pripojte ID verzie ku každej cenovej ponuke, rezervácii a udalosti vyrovnania. V opačnom prípade sa môže stať, že po aktualizácii modelových cien poskytovateľom nebude možné faktúru reprodukovať.

Požiadavky na streamovanie: najskôr rezervovať, neskôr urovnať

Streamovanie komplikuje fakturáciu, pretože používateľ začne prijímať výstup skôr, ako brána pozná konečné využitie. Odpoveďou je nepreskakovať predletové kontroly. Brána by si mala rezervovať pred otvorením streamu.

Použite tento pracovný postup:

1. Odhadnite vstupné tokeny a maximálne výstupné náklady.
2. Rezervovať rozpočet nájomcu.
3. Otvoriť stream poskytovateľa.
4. Poslať časti ďalej klientovi.
5. Zaznamenajte konečné využitie, keď ho poskytovateľ odošle alebo keď je k dispozícii následný záznam o používaní.
6. Urovnajte skutočné náklady a uvoľnite nevyužitú rezerváciu.

Ak konečné použitie nie je k dispozícii, označte vyrovnanie ako odhadované, a nie predstierajte, že je presné:

"usage_source": "gateway_estimate",
"is_estimated": true,
"reconciliation_status": "pending"

Odporúčanie: denné zosúlaďovanie by malo uprednostňovať odhadované udalosti streamovania, neúspešné žiadosti, časové limity a opakované pokusy. Toto sú oblasti, ktoré s najväčšou pravdepodobnosťou vytvoria rozdiely medzi záznamami brány a faktúrami poskytovateľa.

Verzie a pravidlá označovania cenníka

Cenník by mal byť objekt s verziou, nie meniteľná tabuľka.

Minimálne polia:

• poskytovateľ;
• ID modelu;
• trieda fakturácie;
• jednotka, ako je token, požiadavka, obrázok, zvuková sekunda alebo jednotka nástroja;
• jednotková cena;
• currency;
• efektívna časová pečiatka začiatku a konca;
• zásady zaokrúhľovania;
• pravidlo označovania plánu nájomcu alebo partnera;
• referencie zdroja a metadáta schválenia.

Pravidlá označovania by mali byť explicitné. Napríklad:

• Cost plus: cena poskytovateľa plus 20 %.
• Pevný maloobchod: nájomca platí pevnú symbolickú cenu bez ohľadu na cenu poskytovateľa.
• Tiered: najprv 10 miliónov tokenov jedným kurzom, potom nižším kurzom.
• Zahrnuté kredity: používanie zníži mesačný limit pred začatím účtovania prekročenia.

Trade-off: Verzia podľa cenníka pridáva operatívnu prácu, ale zabraňuje tomu, aby sa spory o faktúry stali archeológiou. Zástupca zákazníckej podpory by mal byť schopný vysvetliť, prečo bola žiadosť z 3. augusta účtovaná konkrétnou sadzbou, bez toho, aby skontroloval dnešné ceny poskytovateľa.

Oddeľte účtovnú knihu od analytiky

Analytika a fakturácia majú rôzne tolerancie. Analýzu možno agregovať, oneskoriť, vzorkovať alebo opraviť. Fakturácia musí byť úplná, idempotentná, kontrolovateľná a vysvetliteľná.

Používajte analýzu na otázky ako:

• Ktoré tímy používajú najviac tokenov?
• Ktoré modely rastú najrýchlejšie?
• Kde môže rýchle ukladanie do vyrovnávacej pamäte znížiť náklady?
• Ktoré klávesy vytvárajú nezvyčajne drahé požiadavky?

Používajte účtovnú knihu na otázky ako:

• Bola táto žiadosť autorizovaná za zostatok nájomníka?
• Ktorá verzia cenníka spôsobila tento poplatok?
• Bola uvoľnená nevyužitá rezervácia?
• Zhoduje sa zákaznícka faktúra s uhradeným použitím?
• Zhoduje sa používanie brány s používaním na strane poskytovateľa?

Fakt: Sémantické konvencie OpenTelemetry GenAI zahŕňajú atribúty používania tokenov, ako sú vstupné a výstupné tokeny. To je užitočné pre pozorovateľnosť a spájanie stôp s nákladovými udalosťami. Ale telemetrické atribúty nenahrádzajú cenníky, rezervácie, zúčtovanie, zaokrúhľovanie a stav faktúry.

Pracovný postup denného vyrovnania

Reconciliation porovnáva zúčtovanú účtovnú knihu brány s používaním na strane poskytovateľa. Cieľom nie je dokonalá zhoda na každom strednom poli. Cieľom je odhaliť odchýlky materiálu dostatočne skoro, aby bolo možné opraviť faktúry, cenníky alebo adaptéry.

Praktická každodenná práca:

1. Skupinové udalosti hlavnej knihy podľa poskytovateľa, modelu, nájomníka alebo kľúča API, fakturačnej triedy a dňa UTC.
2. Načítajte využitie na strane poskytovateľa zoskupené podľa dostupných dimenzií, ako je API ID kľúča, model a deň.
3. Ak je to možné, normalizujte exporty poskytovateľa prostredníctvom rovnakého kódu adaptéra, ktorý sa používa pre odpovede na požiadavky.
4. Porovnajte množstvá a náklady podľa fakturačnej triedy.
5. Naznačte odchýlku nad prahovými hodnotami, ako je rozdiel v množstve 0,5 % alebo akýkoľvek veľký absolútny rozdiel v nákladoch.
6. Klasifikujte príčiny odchýlky: odhady streamovania, opakované pokusy, neúspešné žiadosti, vyrovnávacia pamäť, zmeny aliasov modelu, oneskorené záznamy poskytovateľa alebo chýbajúce ID žiadostí.
7. Vytvárajte udalosti úprav namiesto úpravy starých udalostí vyrovnania.

Odporúčanie: ak je to prevádzkovo možné, použite kľúče poskytovateľa API na nájomníka, pretože to zjednodušuje odsúhlasenie. Ak to vytvára príliš veľkú réžiu správy kľúčov, namapujte interné ID nájomníkov na metadáta poskytovateľa, ak sú podporované, a ponechajte si spoľahlivý most ID žiadostí.

Zákazníci v riadkoch faktúr môžu pochopiť

Faktúra vystavená zákazníkovi by nemala odrážať poskytovateľa JSON. Malo by to vysvetliť účet v stabilných obchodných podmienkach.

Užitočné stĺpce faktúr:

• rozsah dátumov;
• nájomník, projekt alebo API označenie kľúča;
• profil modelu alebo modelu;
• počet žiadostí;
• neuložené vstupné tokeny;
• uložené vstupné tokeny;
• výstupné tokeny;
• v prípade potreby jednotky médií alebo nástrojov;
• zľavy, kredity alebo prirážky;
• celková suma a mena.

V prípade partnerov zahrňte veľkoobchodné aj maloobchodné náklady, iba ak si to vyžaduje obchodný model. Mnohé faktúry od predajcov by mali uvádzať iba maloobchodné použitie, zatiaľ čo na paneloch partnerov sa marža môže zobrazovať oddelene.

Trade-off: Jednotná schéma faktúr zlepšuje čitateľnosť, no fakturačné údaje špecifické pre poskytovateľa stále potrebujú únikové otvory. V predvolenom nastavení majte jednoduché riadky faktúr a poskytnite export pre pokročilých zákazníkov, ktorí potrebujú podrobné polia auditu.

Kontrolný zoznam implementácie

Pred spustením

• Definujte normalizované triedy fakturácie pre všetkých podporovaných poskytovateľov.
• Vytvorte nemenné verzie cenníka s dátumami účinnosti.
• Vyžadovať obmedzenia výstupu alebo použiť predvolené nastavenia brány.
• Implementujte atómové rezervácie pomocou kľúčov idempotencie.
• Nastavte pravidlá zaokrúhľovania pre každú menu.
• Rozhodnite sa, ako fakturovať tokeny uložené vo vyrovnávacej pamäti, tokeny zdôvodňovania, mediálne jednotky a poplatky za žiadosti.
• Opakované pokusy o test, časové limity, odpojenia klienta a chyby poskytovateľa.
• Namiesto úpravy vyrovnaných udalostí zostavte mechanizmus udalostí úprav.

Počas spracovania žiadostí

• Autentifikujte nájomníka a kľúč.
• Po smerovaní a záložných pravidlách vyriešte konečný model.
• Vyberte správnu verziu cenníka.
• Uveďte cenu v najhoršom prípade.
• Rezervujte zostatok alebo odmietnite žiadosť.
• Zaznamenajte ID žiadosti poskytovateľa, ak bude k dispozícii.
• Normalizácia používania z odpovede.
• Vyrovnať, uvoľniť nevyužitú rezerváciu a vygenerovať udalosti pripravené na faktúru.

Po spracovaní žiadosti

• Spúšťajte denné vyrovnanie podľa poskytovateľa, kľúča, modelu, fakturačnej triedy a dňa.
• Skontrolujte odhadované vysporiadania streamingu.
• Použitie modelu vlajky s chýbajúcimi položkami cenníka.
• Monitorujte odchýlky spôsobené účtovaním tokenov uložených vo vyrovnávacej pamäti.
• Generovanie ukážok zákazníckych faktúr pred konečnou fakturáciou.

Predpovede na plánovanie

Predpoved: AI API fakturácia bude viac viacrozmerná, nie menšia. Triedy tokenov, triedy vyrovnávacej pamäte, mediálne jednotky, spúšťanie nástrojov a počítadlá súvisiace s uvažovaním sa budú pravdepodobne neustále rozširovať, keď sa menia možnosti modelu.

Predpoveď: zákazníci budú očakávať vysvetlenia používania na úrovni požiadavky, kľúča, projektu a faktúry. Mesačný súčet bez vysledovateľných riadkových položiek nebude pre tímy, ktoré predávajú prístup API alebo presadzujú predplatené rozpočty, postačujúci.

Prediction: Brány, ktoré už oddeľujú cenovú ponuku, rezerváciu, vyrovnanie a vyrovnanie, sa rýchlejšie prispôsobia novým cenovým modelom, pretože môžu pridávať triedy fakturácie bez prepisovania celého fakturačného systému.

Uplatniteľný záver

Ak prostredníctvom jednej brány odhalíte viacero poskytovateľov AI, vytvorte si účtovnú knihu skôr, ako spory o fakturáciu vynútia problém. Začnite so štyrmi zárukami:

1. Každá fakturovateľná žiadosť dostane predbežnú cenovú ponuku.
2. Každý predplatený alebo obmedzený nájomník má pred začiatkom hovoru s poskytovateľom rezervovaný rozpočet.
3. Každá odpoveď poskytovateľa je normalizovaná do stabilných tried fakturácie.
4. Každá faktúra sa dá porovnať s použitím na strane poskytovateľa a presnou verziou cenníka, ktorá sa v tom čase používala.

Táto kontrolná slučka robí zjednotenú AI API fakturáciu zrozumiteľnou pre zákazníkov, vynútiteľná pre predplatené kredity, flexibilná pre partnerské prirážky a auditovateľná pri zmene cien poskytovateľa alebo formátov používania.

Súvisiace čítanie

• spojenie s použitím LLM records
• budovanie portálov pre predajcov s meraním využitia nájomníkov
• používanie rýchleho ukladania do vyrovnávacej pamäte pri zachovaní zrozumiteľnosti fakturácie