Credits & Billing

All generations consume credits from your account. Credits come from your subscription plan, credit packs, and redemptions.

Endpoint

GET /api/v1/account/credits

The endpoint takes no query parameters and no request body. It always reports the balance of the account the API key belongs to — there is no way to query another user.

curl

curl https://api.kolbo.ai/api/v1/account/credits \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

async function main() {
  const response = await fetch("https://api.kolbo.ai/api/v1/account/credits", {
    headers: { "X-API-Key": "YOUR_API_KEY" }
  });
  const data = await response.json();
  console.log(data.credits.total);
}
main();

Python

import requests

response = requests.get(
    "https://api.kolbo.ai/api/v1/account/credits",
    headers={"X-API-Key": "YOUR_API_KEY"}
)
print(response.json()["credits"]["total"])

Response

{
  "success": true,
  "credits": {
    "total": 1500,
    "plan_credits": 1000,
    "credit_pack": 400,
    "redemption": 100
  }
}

Response Fields

Balances are numbers, not integers — some charges (chat turns, for example) are billed in tenths of a credit, so expect values like 1499.7.

Credit Types

The three-allocation subscription cap is a balance cap, not a three-month expiry. When paid access ends, the subscription bucket returns to the free allowance; purchased pack credits remain. See Subscription & Billing for retention and comparison rules. The Developer USD wallet is a separate product; these credit-bucket rules describe the credit-billed API.

Credit Deduction

Credits are reserved when a generation starts and confirmed at the real, multiplier-adjusted cost when it finishes. If a generation fails or is cancelled, the reservation is released and any already-deducted credits are refunded.

Deduction Order

1. Plan credits (used first)
2. Credit pack credits
3. Redemption credits

Legacy accounts with no buckets deduct from their single credit field instead. Every bucket is floored at zero, so a race can never drive a balance negative.

What a Generation Actually Cost

Poll GET /api/v1/generate/{generation_id}/status. Once state is completed the response carries the authoritative numbers:

Both fields are omitted when no deduction rows exist yet — do not treat their absence as "free". Base vs. final cost and resolution per deduction are available from the caller-session endpoint below (recent[].base / final / resolution).

GET /api/v1/generate/creative-director/{id}/status never carries credits_used or credits_breakdown — each scene is billed independently. Reconcile Creative Director batches with the caller-session endpoint below.

Cancelling returns credits_refunded on the cancel response:

curl -X POST https://api.kolbo.ai/api/v1/generate/GENERATION_ID/cancel \
  -H "X-API-Key: YOUR_API_KEY"

{
  "success": true,
  "generation_id": "6650...",
  "type": "video",
  "state": "cancelled",
  "credits_refunded": 40
}

credits_refunded falls back to 0 when the cancel reports no refunded amount. Cancelling a batch also returns batch_cancelled_count. Cancel failures return 404 (NOT_FOUND, or no code at all when the id is not one of your API generations), 403 (FORBIDDEN), 409 (CANNOT_CANCEL, NOT_IN_PROGRESS) or 503 (CANCELLATION_SETTLEMENT_PENDING).

What a Whole Integration Session Cost

Every request may carry an optional X-Kolbo-Caller-Session-Id header — a stable identifier you choose for one run of your integration (see Authentication). Credit deductions made while that header is present are tagged with it, and you can aggregate them afterwards:

GET /api/credit-usage/by-caller-session

Query Parameters

curl "https://api.kolbo.ai/api/credit-usage/by-caller-session?caller_session_id=run-2026-07-27-a" \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
  "message": "Caller-session usage retrieved successfully",
  "data": {
    "caller_session_id": "run-2026-07-27-a",
    "total": 184,
    "count": 12,
    "by_tool": [{ "generation_type": "image", "amount": 96, "count": 8 }],
    "by_model": [{ "model": "nano-banana-2", "amount": 96, "count": 8 }],
    "recent": [
      {
        "amount": 12,
        "model": "nano-banana-2",
        "generation_type": "image",
        "generation_id": "6650...",
        "created_at": "2026-07-27T10:00:00Z",
        "base": 8,
        "final": 12,
        "resolution": "2K"
      }
    ]
  }
}

Only deduction records are counted (refunds are not netted out). Charges where you were the requester on a shared project but another account paid are included. by_tool and by_model are sorted by amount, highest first.

total is the real, multiplier-adjusted spend — not an estimate from base credits. recent is capped at the 50 most recent deductions, newest first. Missing the id entirely returns 400 with caller_session_id required as a string (query param or X-Kolbo-Caller-Session-Id header).

Insufficient Credits

The generation routes listed in the table below run a pre-flight balance check before doing any work. It compares your total against a per-type minimum floor — a lower bound meant to reject requests that cannot succeed with any model of that type. Failing it returns 403:

{
  "success": false,
  "error": "Insufficient credits for image. Your balance is 1, minimum required: 2. Top up at app.kolbo.ai to continue.",
  "code": "INSUFFICIENT_CREDITS",
  "balance": 1,
  "required": 2,
  "pricing_url": "https://app.kolbo.ai/pricing?..."
}

Pre-flight minimums

Any generation type not in this table falls back to a floor of 1. These are floors, not prices — clearing one says nothing about whether the model you picked is affordable.

Other credit-spending routes carry no SDK-layer floor at all — POST /visual-dna/character-sheet, POST /video/trim, POST /voices/clone, POST /generate/music/reference-audio, POST /generate/music/edit-section and the two paid /music-library actions go straight to the underlying controller, whose own reservation is the first and only credit check. Expect the insufficient-credits error from those to arrive later and in the controller's own shape, not as a synchronous INSUFFICIENT_CREDITS.

Getting More Credits

• Upgrade your plan at kolbo.ai/pricing
• Purchase credit packs from your dashboard

There is no API to buy credits — top-ups happen in the app only. To show a user what they could buy, read the read-only catalog:

GET /api/v1/account/plans

curl https://api.kolbo.ai/api/v1/account/plans \
  -H "X-API-Key: YOUR_API_KEY"

The response carries your account's real plans, prices and promotions:

This route never creates a checkout session or payment link.

Related