Billing & usage

Running a character costs money — every reply, opener, comment, and follow-up is a real call to an upstream model. FluidTalk meters the exact dollar cost of each generated message, applies your plan's conversation rate, and charges the character owner's wallet. Balances and charges are denominated in tokens at 1 token = $1, so a turn costs a small decimal like 0.00127932 — you're billed for exactly what you used, at your plan's rate.

The story is simple: the bigger your plan, the cheaper every conversation. Higher plans apply a lower rate to the same real cost, so each message — and each chat — costs less as you grow.

This page covers what you pay, the wallet behind it, the billing object on responses, and how to handle an empty balance.

What you pay

For every message the character generates — a chat reply, a trigger opener, a comment, a follow-up — FluidTalk sums the real cost of each underlying model call (the prompt/completion, plus any retrieval or vision steps) and charges it at your plan's rate:

charge = real_cost × your_plan_rate

• real_cost is the genuine dollar cost of the turn's model calls — pure usage, no fixed per-turn price. (Example: 0.000187 planning + 0.00000338 + 0.00000004 retrieval + 0.0000228 reply generation = 0.00021322.)
• your_plan_rate is the per-plan multiplier applied to that cost. It falls as you move up tiers, so conversations get cheaper on bigger plans:

Plan	Price	Rate	Typical 50-message chat	Cheaper per chat vs Free
Free	$0	×10	~$0.11	—
Pro	$19/mo	×8	~$0.09	20%
Elite	$49/mo	×6	~$0.07	40%
Agency	$99/mo	×4	~$0.05	60%
Enterprise	$249/mo	×2	~$0.02	80%

Everything is in tokens where 1 token = $1, so the numbers are small decimals (0.000…), never inflated counts.

Typical conversation cost per plan

A typical text-only AI message has a real cost of about $0.000228. What it costs you is that real cost at your plan's rate, and a 50-message chat is roughly that per-message cost × 50. These are typical/estimated figures for text-only messages — messages with photos or extra retrieval cost more.

Plan	Rate	Est. cost per message	Est. 50-message chat
Free	×10	~$0.00228	~$0.11
Pro	×8	~$0.00182	~$0.09
Elite	×6	~$0.00137	~$0.07
Agency	×4	~$0.00091	~$0.05
Enterprise	×2	~$0.00046	~$0.02

The wallet

The balance is a pool of tokens worth $1 each — effectively your dollar balance, shown as tokens. You top up in dollars; each message draws down its cost at your plan's rate. You only run out when the real balance is exhausted.

The gate. When billing is enabled and your wallet can't cover a turn, the API returns 402 payment_required before any model call runs — so you are never charged for a refused turn. Top up to continue.

The billing object

Billable responses include a billing object under data so you can reconcile usage. All values are in tokens (1 token = $1):

{
  "data": {
    "session_id": "0c2f…",
    "bubbles": [ { "text": "heyy 🙈", "delay_ms": 0, "image_url": null } ],
    "billing": {
      "tokens": 0.00127932,
      "tokens_used": 0.00021322,
      "balance_after": 9.99872068,
      "collected": true
    }
  },
  "request_id": "req_8f3c…"
}

Field	Type	Description
tokens	number	What this message cost you = tokens_used × your plan's rate (1 token = $1).
tokens_used	number	The raw model cost of this turn, in tokens (= the real dollars spent, before your plan's rate).
balance_after	number	The owner's wallet token balance after this charge.
collected	boolean	true when the charge was applied; false on a rare concurrent-drain miss.

If billing is absent, the turn made no billable model call (e.g. a no-op) or metered billing isn't enabled in this environment.

Examples

# the reply carries data.billing (tokens / tokens_used / balance_after)
curl -X POST "https://api-talk.fluidvip.com/api/v1/characters/chat" \
  -H "X-Connector-Token: ftc_live_..." \
  -H "Content-Type: application/json" \
  -d '{"platform":"instagram","handle":"mark","message":"hey ava"}'

reply = ft.chat(platform="instagram", handle="mark", message="hey ava")
if reply.billing:
    print(f"charged {reply.billing.tokens} — {reply.billing.balance_after} left")

const reply = await ft.chat({ platform: "instagram", handle: "mark", message: "hey ava" });
if (reply.billing) {
  console.log(`charged ${reply.billing.tokens} — ${reply.billing.balance_after} left`);
}

A worked example

A chat turn whose model calls cost a real $0.00021322, on an Elite account (rate ×6):

Real model cost	0.00021322 (tokens_used)
Your plan's rate (Elite, ×6)	0.00021322 × 6
Total charge	0.00127932 tokens (tokens)
Wallet before	10.0 tokens ($10)
Wallet after	9.99872068 tokens (balance_after)

The same turn on Free (×10) would charge 0.0021322, and on Enterprise (×2) just 0.00042644 — the bigger the plan, the cheaper the conversation. Because you're billed the real cost at your rate, the charge tracks actual usage exactly: heavier turns cost more, lighter turns cost less.

Handling an empty balance

When the wallet can't cover a turn you get 402 payment_required before the model runs:

from fluidtalk import PaymentRequiredError

try:
    reply = ft.chat(platform="instagram", handle="mark", message="hey")
except PaymentRequiredError:
    notify_operator_to_top_up()   # the character won't reply until the wallet is funded

Top up the wallet in the dashboard; it takes effect immediately.

Notes

• Reconcile with billing. Use tokens (what you were charged) and tokens_used (real cost) per turn for your own usage tracking and cost attribution.
• Per environment. Metered billing is controlled by the platform; if it's off, responses simply carry no billing object and nothing is charged.
• Bot-initiated work is billed too. Trigger openers, comments, and proactive follow-ups all cost money and are metered the same way.