Sestavení účetní knihy AI API: Cenová nabídka, rezervace, vypořádání a sladění každého modelového hovoru

Fakturace rozhraní AI API zaměřená na zákazníka nemůže být měsíčním exportem nezpracovaného využití poskytovatele. Pokud brána zpřístupní nájemcům, týmům nebo partnerům více modelů, fakturace musí před vznikem faktury zodpovědět složitější otázku: měla by být tato žádost povolena právě teď a jak bude její cena vysvětlena později?

Praktickým vzorem je účetní kniha se čtyřmi fázemi: nabídka, rezervace, vypořádání a odsouhlasení. Před žádostí uveďte pravděpodobné náklady. Vyhraďte si dostatek rozpočtu nájemce na pokrytí povoleného nejhoršího případu. Vyrovnejte skutečné náklady poté, co je známo použití. Srovnejte účetní knihu brány se záznamy na straně poskytovatele, aby faktury zůstaly obhajitelné.

Tento článek popisuje řídicí smyčku pro bránu API pro více modelů. Je užitečné, ať už brána účtuje interním týmům, předplaceným zákazníkům, agenturním klientům nebo následným partnerům.

Problém s fakturací: použití poskytovatele není faktura pro zákazníka

Fakt: velcí poskytovatelé umělé inteligence nevystavují jedno univerzální počítadlo tokenů ani jednu univerzální cenu. OpenAI zveřejňuje ceny za model se samostatnými sazbami vstupů, vstupů uložených v mezipaměti a výstupu. Ukládání výzvy do mezipaměti OpenAI hlásí použití tokenu uloženého v mezipaměti v poli využití odezvy rozhraní API. Antropické dokumenty oddělují počítadla pro normální vstupní tokeny, vstupní tokeny pro vytvoření mezipaměti, vstupní tokeny pro čtení z mezipaměti a výstupní tokeny. Ceny Gemini rozlišují vstup, výstup a další kategorie tokenů, včetně použití specifického pro modalitu, jako jsou zvukové tokeny.

To znamená, že brána nemůže bezpečně účtovat vynásobením total_tokens jednou cenou. Potřebuje adaptéry specifické pro poskytovatele za fakturačním schématem neutrálním vůči poskytovateli.

Problém je viditelnější v těchto situacích:

• Předplacené kredity: brána musí odmítnout požadavky, než nájemce utratí pod nulou.
• Značky partnera: partner potřebuje vlastní fakturu pro zákazníky, nikoli kopii účtu poskytovatele.
• Streamování: odpověď začíná dříve, než je známo konečné využití tokenu.
• Ukládání výzvy do mezipaměti: Vstup z mezipaměti může být levnější než vstup bez mezipaměti, ale pouze pokud je měřen samostatně.
• Důvod a použití nástroje: některé modely odhalují další dimenze použití, skryté třídy výstupu nebo jednotky médií.
• Změny ceny poskytovatele: Faktura z minulého měsíce musí být reprodukovatelná i po změně ceníku.

Doporučení: zacházejte s fakturací jako s finanční knihou, která se pouze připojuje, nikoli jako s dotazem na řídicí panel nad protokoly požadavků.

Základní architektura

Spolehlivá fakturační architektura má šest komponent:

1. Účet nájemce: zákazník, pracovní prostor, klient distributora nebo interní nákladové středisko.
2. Ceník: verze cen pro poskytovatele, model, fakturační třídu, měnu a pravidlo přirážek.
3. Odhad: vypočítá cenovou nabídku před výstupem z parametrů požadavku a zásad modelu.
4. Kniha rezervací: obsahuje rozpočet před zahájením hovoru poskytovatele.
5. Normalizátor využití: převádí pole využití specifická pro poskytovatele na interní fakturační jednotky.
6. Úlohy vypořádání a odsouhlasení: dokončete poplatky a porovnejte je se záznamy na straně poskytovatele.

Řízení vypadá takto:

požadavek klienta
  -> ověřte nájemce a klíč
  -> vyberte model a verzi ceníku
  -> odhad vstupní a maximální výstupní náklady
  -> rezervní zůstatek nájemce
  -> poskytovatel volání
  -> normalizovat vrácené využití
  -> uhradit skutečné náklady
  -> uvolnit nevyužitou rezervaci
  -> vygenerovat událost účetní knihy připravené na fakturu

Důležitou volbou návrhu je, aby požadavek nebyl pouze dodržován. Je finančně kontrolován před a po provedení.

Krok 1: nabídka před zavoláním poskytovatele

Cena před výstupem by měla být dostatečně pesimistická, aby prosadila rozpočty, ale dostatečně vysvětlitelná, aby se ukázala zákazníkům nebo partnerům.

Vstupy obvykle zahrnují:

• ID nájemce a plán fakturace;
• ID klíče API nebo ID projektu;
• ID poskytovatele a modelu po použití pravidel směrování;
• odhadovaný počet neuložených vstupních tokenů;
• známá způsobilost pro vstup z mezipaměti, je-li k dispozici;
• max_tokens, max_output_tokens nebo ekvivalentní omezení výstupu;
• parametry nástroje, obrázku, zvuku nebo jiné modality;
• pravidlo pro značkové partnery, slevy nebo ceny pro prodejce;
• zásady pro měnu a zaokrouhlování.

Jednoduchý vzorec citace pro generování textu může být:

estimated_cost =
  odhadovaný_uncached_input_tokens * input_rate
+ odhadovaný_cached_input_tokens * cache_input_rate
+ max_output_tokens * output_rate+ request_fee
+ partner_markup

Doporučení: když konečná délka výstupu není známa, rezervujte si konfigurovaný maximální výstup. Pokud aplikace ponechá omezení výstupu neomezené, brána by měla použít výchozí nastavení tenanta nebo modelu. Vymáhání rozpočtu nemůže být deterministické, pokud neexistuje maximální odpovědnost.

Může to odmítnout některé požadavky, které by v praxi byly levné. To je ten kompromis. U předplacených systémů je bezpečnější výchozí nastavení pesimistická rezervace s nevyužitými prostředky uvolněnými po vypořádání. U fakturovaných podnikových zákazníků mohou týmy povolit mírné překročení a použít nabídku hlavně pro upozornění.

Krok 2: Zarezervujte si rozpočet nájemce

Rezervace chrání účet nájemce před útratou vyšší, než je povolený zůstatek. Mělo by to být atomické: buď bude rezervace úspěšná a volání poskytovatele může začít, nebo je požadavek zamítnut před tím, než poskytovateli vzniknou jakékoli náklady.

Záznam rezervace může obsahovat:

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

Pro selhání sítě a odpojení klienta použijte krátké doby platnosti rezervace. Úloha čištění by měla uvolnit rezervace s vypršenou platností, které nikdy nedosáhly vypořádání. Neuvolňujte však rezervaci jen proto, že se klient odpojil; hovor poskytovatele může být stále dokončen a může být zpoplatněn. Stav požadavku poskytovatele můžete sledovat samostatně.

Doporučení: udělejte rezervaci idempotentní pomocí ID požadavku nebo klíče idempotence. Opakované pokusy od klientů, bran nebo pracovníků by neměly vytvářet více pozastavení rozpočtu pro stejný logický požadavek.

Krok 3: Normalizujte využití poskytovatele

Odpovědi poskytovatele by měly být převedeny na malé interní schéma. Udržujte jej stabilní, i když poskytovatelé přidávají nová pole použití.

Praktické normalizované schéma použití:

{
  "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": "odpověď poskytovatele",
  "is_estimated": nepravda
}

Toto schéma není záměrně totožné s odpovědí žádného poskytovatele. Zachycuje fakturační dimenze, které faktury potřebují, a zároveň zachovává únikové šrafy pro jednotky specifické pro poskytovatele.

Tokeny uložené v mezipaměti potřebují svůj vlastní řádek

Fakt: Ukládání výzvy do mezipaměti může mít jinou cenu než vstup bez mezipaměti. Pokud jsou tokeny uložené v mezipaměti sloučeny do celkových vstupních tokenů, může být zákazníkovi přeúčtován poplatek nebo může brána podhodnotit náklady poskytovatele. Vstup uložený v mezipaměti by se měl objevit jako vlastní fakturační třída v hlavní knize i na faktuře.

Zápisy a čtení mezipaměti nejsou vždy stejné

Někteří poskytovatelé rozlišují mezi vytvářením položek mezipaměti a čtením z mezipaměti. Normalizátor by neměl předpokládat, že vstup z mezipaměti vždy znamená jednu fakturační sazbu. Pokud má poskytovatel tokeny pro zápis do mezipaměti a tokeny pro čtení z mezipaměti, namapujte je samostatně nebo je uchovejte jako podjednotky specifické pro poskytovatele.

Uvažování a skrytý výstup vyžadují politiku

Některé modely odhalují použití související s uvažováním nebo skryté výstupní čítače. Pokud poskytovatel tyto jednotky účtuje, brána se musí rozhodnout, zda je zobrazí přímo, zařadí je do výstupní kategorie nebo je vypíše jako samostatný řádek faktury.

Doporučení: Faktury vystavené zákazníkům by měly používat jednoduchý jazyk. Například: „výstupní tokeny uvažování“ je jasnější než nezpracovaný název pole poskytovatele. Udržujte nezpracovaná pole dostupná pro audit, ale nenuťte každého zákazníka, aby porozuměl interním informacím poskytovatele.

Krok 4: vyrovnejte skutečné náklady

Vyrovnání převádí normalizované využití na konečné položky hlavní knihy. Měl by obsahovat pouze přílohu a odkazovat na verzi ceníku použitou pro požadavek.

Vyrovnaná událost může vypadat takto:

{
  "ledger_event_id": "led_01J...",
  "event_type": "vypořádání",
  "tenant_id": "tenant_123",
  "request_id": "req_789",
  "reservation_id": "res_01J...",
  "provider": "example_provider",
  "model": "model-a",
  "rate_card_version": "2026-08-01",
  "řádky": [
    {
      "billing_class": "input_uncached_tokens",
      "množství": 1200,
      "jednotka": "token",
      "jednotková_cena": "0,00000250",
      "částka": "0,003000"
    },
    {
      "billing_class": "input_cached_tokens",
      "množství": 800,
      "jednotka": "token",
      "jednotková_cena": "0,00000125",
      "částka": "0,001000"
    },
    {
      "billing_class": "output_tokens",
      "množství": 650,
      "jednotka": "token","jednotková_cena": "0,00001000",
      "částka": "0,006500"
    }
  ],
  "total_amount": "0,010500",
  "currency": "USD",
  "status": "vyřízeno"
}

Pokud byl požadavek rezervován pro 0,032100 a vypořádán na 0,010500, účetní kniha uvolní 0,021600 zpět na disponibilní zůstatek.

Doporučení: nikdy nepřepočítávejte staré řádky faktury z aktuální cenové tabulky. Uložte neměnné verze ceníku a připojte ID verze ke každé nabídce, rezervaci a události vypořádání. V opačném případě se může stát, že poté, co poskytovatel aktualizuje modelové ceny, nebude možné fakturu reprodukovat.

Požadavky na streamování: nejprve rezervovat, vypořádat později

Streamování komplikuje účtování, protože uživatel začne přijímat výstup dříve, než brána pozná konečné využití. Odpovědí je nevynechat předletové kontroly. Brána by měla provést rezervaci před otevřením streamu.

Použijte tento pracovní postup:

1. Odhadněte vstupní tokeny a maximální výstupní náklady.
2. Rezervujte rozpočet nájemce.
3. Otevřete stream poskytovatele.
4. Přeposílat bloky klientovi.
5. Zaznamenejte konečné využití, když je poskytovatel odešle nebo když je k dispozici následný záznam využití.
6. Uhraďte skutečné náklady a uvolněte nevyužitou rezervaci.

Pokud konečné využití není k dispozici, označte vyrovnání jako odhadované, nikoli předstírejte, že je přesné:

"usage_source": "gateway_estimate",
"is_estimated": pravda,
"reconciliation_status": "nevyřízeno"

Doporučení: denní odsouhlasení by mělo upřednostňovat odhadované události streamování, neúspěšné požadavky, časové limity a opakování. Toto jsou oblasti, které s největší pravděpodobností vytvoří rozdíly mezi záznamy brány a fakturami poskytovatelů.

Verze ceníku a pravidla označování

Ceník by měl být objekt s verzí, nikoli měnitelná tabulka.

Minimální počet polí:

• poskytovatel;
• ID modelu;
• třída fakturace;
• jednotka, jako je token, požadavek, obrázek, zvuková sekunda nebo nástrojová jednotka;
• jednotková cena;
• měna;
• účinná časová razítka začátku a konce;
• zásady zaokrouhlování;
• pravidlo pro označení plánu nájemce nebo partnera;
• referenční zdroj a metadata schválení.

Pravidla označování by měla být jasná. Například:

• Cena plus: náklady poskytovatele plus 20 %.
• Pevný maloobchod: nájemce platí pevnou cenu tokenu bez ohledu na cenu poskytovatele.
• Vrchní: nejprve 10 milionů tokenů jednou sazbou, poté nižší sazbou.
• Zahrnuté kredity: používáním se sníží měsíční povolená částka, než začne účtování přebytku.

Výměna: Verze ceníku přidává provozní práci, ale brání tomu, aby se spory o faktury staly archeologií. Zástupce zákaznické podpory by měl být schopen vysvětlit, proč byla žádost ze dne 3. srpna účtována za konkrétní sazbu, aniž by kontroloval dnešní ceny poskytovatele.

Oddělte účetní knihu od analýzy

Analytika a fakturace mají různé tolerance. Analýzy mohou být agregovány, zpožděny, vzorkovány nebo opraveny. Fakturace musí být úplná, idempotentní, kontrolovatelná a vysvětlitelná.

Používejte analýzu pro otázky jako:

• Které týmy používají nejvíce tokenů?
• Které modely rostou nejrychleji?
• Kde může rychlé ukládání do mezipaměti snížit náklady?
• Které klíče vytvářejí neobvykle drahé požadavky?

Pro otázky jako:

• Byla tato žádost autorizována proti zůstatku nájemce?
• Která verze ceníku způsobila tento poplatek?
• Byla uvolněna nevyužitá rezervace?
• Odpovídá zákaznická faktura zúčtovanému použití?
• Odpovídá využití brány využití na straně poskytovatele?

Fakt: Sémantické konvence OpenTelemetry GenAI zahrnují atributy použití tokenů, jako jsou vstupní a výstupní tokeny. To je užitečné pro pozorovatelnost a spojování tras s nákladovými událostmi. Atributy telemetrie však nenahrazují ceníky, rezervace, zúčtování, zaokrouhlování a stav faktury.

Denní pracovní postup odsouhlasení

Odsouhlasení porovnává ustálenou účetní knihu brány s využitím na straně poskytovatele. Cílem není dokonalá shoda na každém středním poli. Cílem je odhalit odchylky materiálu dostatečně včas, aby bylo možné opravit faktury, ceníky nebo adaptéry.

Praktická každodenní práce:

1. Seskupit události hlavní knihy brány podle poskytovatele, modelu, tenanta nebo klíče API, fakturační třídy a dne UTC.
2. Načtěte využití na straně poskytovatele seskupené podle dostupných dimenzí, jako je ID klíče API, model a den.
3. Pokud je to možné, normalizujte exporty poskytovatele prostřednictvím stejného kódu adaptéru, který se používá pro odpovědi na požadavky.
4. Porovnejte množství a náklady podle fakturační třídy.
5. Označte odchylku nad prahovými hodnotami, jako je 0,5% rozdíl v množství nebo jakýkoli velký absolutní rozdíl v nákladech.
6. Klasifikujte příčiny odchylek: odhady streamování, opakování, neúspěšné požadavky, účtování mezipaměti, změny aliasů modelu, zpožděné záznamy poskytovatelů nebo chybějící ID požadavků.
7. Vytvářejte události úprav namísto úpravy starých událostí vypořádání.

Doporučení: tam, kde je to provozně proveditelné, použijte klíče API poskytovatele pro každého tenanta, protože to zjednodušuje odsouhlasení. Pokud to vytváří příliš mnoho režijních nákladů na správu klíčů, namapujte interní ID tenantů na metadata poskytovatele, pokud jsou podporována, a udržujte spolehlivý most ID požadavku.

Zákazníci s fakturačními řádky rozumí

Faktura vystavená zákazníkovi by neměla odrážet JSON poskytovatele. Mělo by to vysvětlit účet ve stabilních obchodních podmínkách.

Užitečné sloupce faktury:

• časové období;
• nájemce, projekt nebo štítek klíče API;
• profil modelu nebo modelu;
• počet požadavků;
• neuložené vstupní tokeny;
• v mezipaměti vstupní tokeny;
• výstupní tokeny;
• jednotky médií nebo nástrojů, jsou-li k dispozici;
• slevy, kredity nebo přirážky;
• celková částka a měna.

Pro partnery zahrňte velkoobchodní i maloobchodní náklady pouze v případě, že to obchodní model vyžaduje. Mnoho faktur od distributorů by mělo uvádět pouze maloobchodní použití, zatímco panely partnerů mohou marži zobrazovat samostatně.

Výměna: Jednotné schéma faktur zlepšuje čitelnost, ale fakturační údaje specifické pro poskytovatele stále potřebují únikové poklopy. Ve výchozím nastavení udržujte řádky faktur jednoduché a poskytněte export pro pokročilé zákazníky, kteří potřebují podrobná pole auditu.

Kontrolní seznam implementace

Před spuštěním

• Definujte normalizované fakturační třídy pro všechny podporované poskytovatele.
• Vytvořte neměnné verze ceníku s daty účinnosti.
• Vyžadovat omezení výstupu nebo použít výchozí nastavení brány.
• Implementujte atomové rezervace pomocí klíčů idempotence.
• Nastavte pravidla zaokrouhlování pro každou měnu.
• Rozhodněte se, jak fakturovat tokeny uložené v mezipaměti, tokeny zdůvodnění, mediální jednotky a poplatky za žádosti.
• Opakované pokusy o testování, vypršení časového limitu, odpojení klienta a chyby poskytovatele.
• Namísto úpravy ustálených událostí vytvořte mechanismus událostí úprav.

Během zpracování požadavku

• Ověřte nájemce a klíč.
• Vyřešte konečný model po směrování a záložních zásadách.
• Vyberte správnou verzi ceníku.
• Uveďte cenu v nejhorším případě.
• Rezervujte zůstatek nebo odmítněte požadavek.
• Zaznamenejte ID požadavku poskytovatele, je-li k dispozici.
• Normalizujte použití z odpovědi.
• Vypořádejte, uvolněte nevyužitou rezervaci a vystavte události připravené na fakturu.

Po zpracování požadavku

• Spouštějte denní odsouhlasení podle poskytovatele, klíče, modelu, fakturační třídy a dne.
• Zkontrolujte odhadované vypořádání streamování.
• Použití modelu vlajky s chybějícími záznamy v ceníku.
• Sledujte odchylky způsobené účtováním tokenů uložených v mezipaměti.
• Vygenerujte náhledy zákaznických faktur před konečným vyúčtováním.

Předpovědi k plánování

Předpověď: Fakturace AI API bude více vícerozměrná, nikoli méně. Třídy tokenů, třídy mezipaměti, jednotky médií, provádění nástrojů a čítače související s uvažováním se budou pravděpodobně neustále rozšiřovat, jak se mění možnosti modelu.

Předpověď: zákazníci budou očekávat vysvětlení použití na úrovni požadavku, klíče, projektu a faktury. Měsíční součet bez sledovatelných řádkových položek bude pro týmy, které přeprodávají přístup k rozhraní API nebo vynucují předplacené rozpočty, nedostatečný.

Predpověď: brány, které již oddělují nabídku, rezervaci, vypořádání a odsouhlasení, se rychleji přizpůsobí novým cenovým modelům, protože mohou přidávat fakturační třídy bez přepisování celého fakturačního systému.

Akční závěr

Pokud prostřednictvím jedné brány zpřístupníte několik poskytovatelů umělé inteligence, vytvořte účetní knihu dříve, než spory o fakturaci problém vynutí. Začněte se čtyřmi zárukami:

1. Každý fakturovatelný požadavek obdrží předtiskovou nabídku.
2. Každý nájemce s předplaceným nebo omezeným počtem má vyhrazený rozpočet před zahájením hovoru poskytovatele.
3. Každá odpověď poskytovatele je normalizována do stabilních fakturačních tříd.
4. Každou fakturu lze porovnat s použitím na straně poskytovatele a přesnou verzí ceníku používaného v danou chvíli.

Tato kontrolní smyčka činí jednotnou fakturaci AI API pro zákazníky srozumitelnou, vymahatelnou pro předplacené kredity, flexibilní pro přirážky partnerů a auditovatelnou při změně cen poskytovatele nebo formátu použití.

Související informace

• spojení trasování LLM se záznamy o využití a nákladech
• vytváření portálů pro distributory s měřením využití tenantů
• používání rychlého ukládání do mezipaměti při zachování srozumitelnosti fakturace