Bytefusedocs
Subscribe

Getting started

Credits & billing

Every tool call is metered in credits. The system is built so you’re only ever charged for work that succeeds — failures are refunded automatically.

The credit model

Each operation has a fixed credit cost. When you call a tool, the API quotes the cost, debits it from your balance before doing the work, and records a usage event. Anonymous free-try calls are always metered at 0 credits.

Per-operation prices are set server-side and can change between versions, so read them from the pricing endpoint rather than hardcoding:

Public — no auth required
GET https://api.bytefuse.in/api/v1/billing/pricing

Four guarantees

Metering runs through a single path with four properties you can rely on:

  1. Rate-limit first. A throttled request is rejected before any charge — you’re never billed for a 429.
  2. Debit before work. Credits are reserved up front; if your balance is too low, the call fails before any processing starts.
  3. Exactly once per attempt. The debit and usage record are idempotent on the server-generated request ID, so a retried network call can’t double-charge.
  4. Refund on failure. If the work raises an error, the reserved credits are refunded and the usage row records 0 net credits. You’re charged if and only if the work succeeded.

Why some tools require login

Anonymous calls are free, so heavier tools (AI, OCR, redaction, certificates) are login-only to keep them metered. See Authentication.

Every metered response includes an X-Credits-Charged header with the exact number of credits billed for that call. It’s 0 for anonymous free-try calls. This header is exposed to browser JavaScript via CORS, so you can read it client-side.

Reading the header
credits = res.headers.get("X-Credits-Charged")  // e.g. "20"

Cost per operation

Costs for the tools currently documented here. The operation key is the internal identifier the pricing and usage endpoints use.

OperationCredits
pdf.compressCompress a PDF20
convert.documentConvert a document (default)40
convert.pdf_to_docx.aiAI (vision) PDF → Word200
pdf.to_xlsxPDF → Excel (deterministic)40
pdf.to_xlsx.aiAI (vision) PDF → Excel200

AI tools cost more

Vision/AI engines (the .ai operation keys) run large models and are priced accordingly — 200 credits versus 40 for the deterministic path.

Running out of credits

If your balance can’t cover a call, it fails with 402 Payment Required before any work runs — so it costs nothing. The message names the operation and the shortfall:

402 Payment Required
{
  "error": "InsufficientCreditsError",
  "message": "Insufficient credits: pdf.compress needs 20, balance is 1",
  "details": null,
  "request_id": "…",
  "timestamp": "2026-07-04T…Z"
}

Hitting a per-key or per-member spend budget also returns 402. Top up or raise the budget, then retry.

Checking your balance

Authenticated endpoints let you inspect credits and history:

Billing endpoints (auth required)
GET /api/v1/billing/balance   # current credit balance
GET /api/v1/billing/ledger    # credit movements (debits, refunds, top-ups)
GET /api/v1/billing/usage     # aggregated usage
GET /api/v1/billing/logs      # per-call metering logs
PreviousAuthenticationNext Errors