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

Fakturácia rozhrania AI API pre zákazníka nemôže predstavovať mesačný export nespracovanej spotreby 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 budú jej náklady vysvetlené neskôr?

Praktickým vzorom 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. Porovnajte úč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 bránu API s viacerými modelmi. Je to užitočné, či už 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 pre jednotlivé modely so samostatnými vstupnými, medzipamäťovými a výstupnými tokenovými sadzbami. Ukladanie výzvy do vyrovnávacej pamäte OpenAI hlási použitie tokenu uloženého vo vyrovnávacej pamäti v poli využitia odpovede API. Antropické dokumenty oddeľujú 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. Ceny Gemini 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. Potrebuje 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 faktúry 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.
• Dôvod a použitie nástroja: niektoré modely odhaľujú ďalšie dimenzie použitia, skryté výstupné triedy 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: s fakturáciou zaobchádzajte 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. Odhad: vypočíta cenovú ponuku pred výstupom z parametrov požiadavky a politiky modelu.
4. Kniha rezervácií: obsahuje rozpočet pred začatím hovoru poskytovateľa.
5. Normalizátor používania: konvertuje polia používania špecifické pre poskytovateľa na interné fakturačné jednotky.
6. Úlohy vyrovnania a odsúhlasenia: finalizujte poplatky a porovnajte ich so záznamami na strane poskytovateľa.

Tok ovládania vyzerá takto:

žiadosť klienta
  -> autentifikujte nájomcu a kľúč
  -> vyberte model a verziu cenníka
  -> odhad vstupných a maximálnych výstupných nákladov
  -> rezervný zostatok nájomcu
  -> poskytovateľa hovorov
  -> normalizovať vrátené používanie
  -> uhradiť skutočné náklady
  -> uvoľnite nevyužitú rezerváciu
  -> vygenerovať udalosť knihy pripravenej na faktúru

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;
• ID kľúča API alebo ID projektu;
• ID poskytovateľa a modelu po použití pravidiel smerovania;
• odhadované 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ý limit výstupu;
• parametre nástroja, obrázka, zvuku alebo inej modality;
• pravidlo na značkovanie partnera, zľavu alebo cenu predajcu;
• pravidlá meny a zaokrúhľovania.

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

estimated_cost =
  odhadované_uložené_vstupné_tokeny * vstupná_miera
+ odhadovaný_cached_input_tokens * cache_input_rate
+ max_output_tokens * output_rate+ request_fee
+ partner_markup

Odporúčanie: ak konečná výstupná dĺžka nie je známa, rezervujte si podľa konfigurované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 tým 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 použiť cenovú ponuku 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ť atomická: 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": "rezervované",
  "expires_at": "2026-08-11T12:05:00Z"
}

V prípade zlyhania siete a odpojení klienta použite krátke uplynutie platnosti rezervácie. Ú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 ako idempotentnú 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": [],
  "jednotky_poplatku_požiadavky": 1,
  "provider_request_id": "prov_abc",
  "usage_source": "odpoveď_poskytovateľa",
  "is_estimated": nepravda
}

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

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

Fakt: rýchle ukladanie do vyrovnávacej pamäte môže mať inú cenu ako vstup neuložený vo vyrovnávacej pamäti. 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 prevedie 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": "vyrovnanie",
  "tenant_id": "tenant_123",
  "request_id": "req_789",
  "reservation_id": "res_01J...",
  "provider": "example_provider",
  "model": "model-a",
  "rate_card_version": "2026-08-01",
  "riadky": [
    {
      "billing_class": "input_uncached_tokens",
      "množstvo": 1200,
      "jednotka": "token",
      "jednotková_cena": "0,00000250",
      "suma": "0,003000"
    },
    {
      "billing_class": "input_cached_tokens",
      "množstvo": 800,
      "jednotka": "token",
      "jednotková_cena": "0,00000125",
      "suma": "0,001000"
    },
    {
      "billing_class": "output_tokens",
      "množstvo": 650,
      "jednotka": "token","jednotková_cena": "0,00001000",
      "suma": "0,006500"
    }
  ],
  "celková_suma": "0,010500",
  "currency": "USD",
  "status": "vyrovnané"
}

Ak bola požiadavka rezervovaná na 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 rezervujte, vyrovnajte neskôr

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. Rezervovaný rozpočet nájomcu.
3. Otvorte stream poskytovateľa.
4. Poslať bloky ď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é využitie nie je k dispozícii, označte vyrovnanie ako odhadované, a nie predstierajte, že je presné:

"usage_source": "gateway_estimate",
"is_estimated": pravda,
"reconciliation_status": "čaká"

Odporúčanie: denné vyrovnanie 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.

Pravidlá tvorby verzií a značiek cenníka

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

Minimálne množstvo polí:

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

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

• Cena plus: cena poskytovateľa plus 20 %.
• Pevný maloobchod: nájomca platí pevnú cenu tokenu bez ohľadu na cenu poskytovateľa.
• Viacúrovňové: najprv 10 miliónov tokenov jednou sadzbou, potom nižšou.
• Zahrnuté kredity: používaním sa zníži mesačný limit pred začatím účtovania prekročenia.

Výmena: 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á špecifickou sadzbou bez toho, aby skontroloval dnešné ceny poskytovateľa.

Oddeľte účtovnú knihu od analytiky

Analytika a fakturácia majú rozdielne 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?

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 dohodnutý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.

Denný pracovný postup zosúlaďovania

Zosúladenie 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. Zoskupte udalosti hlavnej knihy podľa poskytovateľa, modelu, nájomníka alebo kľúča API, triedy fakturácie a dňa UTC.
2. Načítajte využitie na strane poskytovateľa zoskupené podľa dostupných dimenzií, ako je ID kľúča API, 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 triedy fakturácie.
5. Naznačte odchýlku nad prahovými hodnotami, ako je 0,5 % rozdiel v množstve 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é požiadavky, zaúčtovanie vyrovnávacej pamäte, zmeny aliasov modelu, oneskorené záznamy poskytovateľa alebo chýbajúce ID požiadaviek.
7. Namiesto úpravy starých udalostí vyrovnania vytvorte udalosti úprav.

Odporúčanie: používajte kľúče API poskytovateľa na nájomníka tam, kde je to prevádzkovo možné, pretože to zjednodušuje zosúlaďovanie. 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 pochopia riadky faktúr

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

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

• rozsah dátumov;
• nájomník, projekt alebo označenie kľúča API;
• 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 v prípade, že si to vyžaduje obchodný model. Mnohé faktúry od predajcov by mali uvádzať iba maloobchodné použitie, zatiaľ čo na informačných paneloch partnerov sa marža môže zobrazovať oddelene.

Výmena: Jednotná schéma faktúr zlepšuje čitateľnosť, no fakturačné údaje špecifické pre poskytovateľa stále potrebujú únikové informácie. V predvolenom nastavení ponechajte riadky faktúr jednoduché 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 uvažovania, jednotky médií a poplatky za žiadosti.
• Opakované pokusy o test, časové limity, odpojenia klienta a chyby poskytovateľa.
• Namiesto úpravy vyrovnaných udalostí vytvorte mechanizmus udalostí úprav.

Počas spracovania žiadosti

• Autentifikujte nájomníka a kľúč.
• Vyriešte konečný model po smerovaní a záložných pravidlách.
• 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 je k dispozícii.
• Normalizácia používania z odpovede.
• Vyrovnajte, uvoľnite nevyužitú rezerváciu a vystavte 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 vlajkového modelu s chýbajúcimi položkami cenníka.
• Monitorujte odchýlky spôsobené účtovaním tokenov uložených vo vyrovnávacej pamäti.
• Pred konečnou fakturáciou vygenerujte ukážky zákazníckych faktúr.

Predpovede na plánovanie

Predpoveď: Fakturácia AI API 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 k rozhraniu API alebo presadzujú predplatené rozpočty, postačujúci.

Predpoveď: 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ý nájomník s predplateným alebo obmedzeným počtom nájomníkov má rezervovaný rozpočet pred začiatkom hovoru poskytovateľa.
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á bola v danom čase použitá.

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

Súvisiace informácie

• spojenie trasovania LLM so záznamami o využití a nákladoch
• vybudovanie predajných portálov s meraním využitia nájomníkov
• používanie rýchleho ukladania do vyrovnávacej pamäte pri zachovaní zrozumiteľnosti fakturácie