Token-cost-calc

Use when calculating, auditing, implementing, or reviewing token pricing and billing formulas for OpenAI-style APIs, NewAPI-compatible gateways, cached input...

Security Scan

The skill's requirements, instructions, and included reference material are consistent with a token-cost calculation/audit tool and do not request unrelated credentials, installs, or system access.

Purpose & Capability

The name and description match the actual content: formulas, rules, and examples for OpenAI-style and NewAPI-style token/quota pricing. The skill does not request unrelated credentials, binaries, or config paths.

Instruction Scope

SKILL.md stays on-topic: it contains step-by-step formulas, normalization rules, a verification checklist, common mistakes, and refers only to the included references/formulas.md. It does not instruct the agent to read unrelated files, contact external endpoints, or access environment variables.

Install Mechanism

No install spec or code files that would be downloaded or executed are present. This instruction-only skill writes nothing to disk and has minimal surface area.

Credentials

The skill declares no required environment variables or credentials. That is proportionate for a calculation/audit skill which only needs numeric inputs from the user at runtime.

Persistence & Privilege

always is false (default) and the skill does not request persistent system-wide configuration or modification of other skills. Autonomous invocation is allowed by default, which is normal for skills and not by itself a concern.

Assessment

This skill appears coherent and safe from a packaging standpoint. Before installing, consider: (1) verify inputs you pass (token counts, price tables, recharge ratios) come from trusted sources—this skill will compute based on whatever numbers it receives; (2) review and test edge cases (zero and negative tokens, division-by-zero for rechargeRatio) as the checklist suggests; (3) if you dislike autonomous invocation, keep the skill user-invocable only or disable autonomous use in agent settings; and (4) if you integrate these formulas into production billing, add unit tests and compare results against the official provider billing docs to ensure no subtle mismatch in units or quotas.

Token Cost Skill

Use this skill to calculate or review token billing without double-counting cached tokens or mixing incompatible pricing units.

Core Rules

1. Identify the billing mode before calculating:
   • openai-raw: provider price table has input, cached input, and output prices.
   • newapi-quota: gateway billing uses model ratio, completion/output ratio, and group ratio.
   • custom-multiplier: dashboard-specific per-1K/per-1M cost projection.
2. Normalize price units first:
   • /1K prices use divisor 1000.
   • /1M prices use divisor 1000000.
3. Treat cached input as a subset of input tokens, not an extra token bucket.
4. Keep quota formulas separate from money formulas; only convert quota to money after quota is computed.
5. Show the expanded formula with the final result so users can audit every multiplier.

OpenAI-Style Raw Pricing

Inputs:

• inputTokens: total input tokens reported for the request.
• cachedInputTokens: cached input tokens inside inputTokens.
• outputTokens: output tokens.
• inputPrice: non-cached input price per selected unit.
• cachedInputPrice: cached input price per selected unit.
• outputPrice: output price per selected unit.

Formula:

unitDivisor = 1000 if priceUnit = "1K", else 1000000
cachedInputTokens = min(max(cachedInputTokens, 0), max(inputTokens, 0))
nonCachedInputTokens = max(inputTokens, 0) - cachedInputTokens

inputCost = (nonCachedInputTokens / unitDivisor) * inputPrice
cachedInputCost = (cachedInputTokens / unitDivisor) * cachedInputPrice
outputCost = (max(outputTokens, 0) / unitDivisor) * outputPrice
totalCost = inputCost + cachedInputCost + outputCost
totalTokens = max(inputTokens, 0) + max(outputTokens, 0)

Never use:

totalTokens = inputTokens + cachedInputTokens + outputTokens

cachedInputTokens is already included in inputTokens.

NewAPI-Compatible Quota Pricing

Use this mode when the gateway bills quota/credits by ratios.

Standard request quota formula:

quota = (promptTokens + completionTokens * completionRatio) * modelRatio * groupRatio

Common money conversion:

usdEquivalent = quota / 500000
actualCost = usdEquivalent / rechargeRatio

Notes:

• completionRatio is also called output ratio, completion multiplier, or completion billing ratio.
• groupRatio is the group multiplier.
• modelRatio is the model multiplier.
• rechargeRatio is not part of the quota formula; it is a post-processing conversion for real paid cost.

Custom Multiplier Dashboards

Use only when a dashboard intentionally projects per-1K or per-1M prices instead of computing gateway quota.

inputCost1K = basePrice1K * modelMultiplier * groupMultiplier / rechargeRatio
outputCost1K = basePrice1K * modelMultiplier * outputMultiplier * groupMultiplier / rechargeRatio
cacheReadCost1K = basePrice1K * modelMultiplier * cacheReadMultiplier * groupMultiplier / rechargeRatio
cacheCreateCost1K = basePrice1K * modelMultiplier * cacheCreateMultiplier * groupMultiplier / rechargeRatio

If basePrice is entered per 1M, convert first:

basePrice1K = basePrice1M / 1000

Verification Checklist

• Confirm whether token counts are request usage counts or price table units.
• Confirm whether cachedInputTokens is included inside inputTokens.
• Confirm whether prices are per 1K or per 1M.
• For OpenAI-style pricing, calculate non-cached input before calculating cost.
• For NewAPI-style pricing, calculate quota before converting to USD or local currency.
• Clamp negative token counts to 0.
• Clamp cached input to no more than total input.
• Protect against division by zero in recharge ratio.
• Add tests for one normal case, one cached-input case, one unit-conversion case, and one zero-token case.

Common Mistakes

Mistake	Correct handling
Adding cached input to total input	Subtract cached input from input to get non-cached input
Mixing /1K and /1M prices	Normalize with the correct divisor first
Applying recharge ratio inside NewAPI quota	Compute quota first; apply recharge ratio only to money conversion
Using output price for cached input	Cached input uses its own price
Letting cached input exceed input	Clamp cached input to input tokens

Reference

Read references/formulas.md when you need source notes, examples, or implementation snippets.