Why the Image API Is Priced in Coins (and Refunds Itself)

When we built the public image API on top of Fellowi Images, we had to make a handful of decisions that don’t show up in the docs as features - they show up as the absence of problems. This is the reasoning behind them: why it’s priced in coins, what happens when a generation fails, and why a couple of numbers in the docs (rate limits, retention days) mean less than they look like they do.

Coins, not a subscription

Image generation has a real, variable cost per call. A flat monthly subscription either overcharges someone who generates five images a month, or undercharges someone who generates five hundred - there’s no seat count or request quota that maps cleanly onto that. Coins let cost track usage directly instead: you spend what you actually generate, nothing more. Coins never expire and there’s nothing to cancel, which also means there’s no billing cycle to worry about missing - buy a package when you need one, and it just sits in the wallet until you do.

A failed generation refunds itself

If a generation times out or gets rejected before it produces an image, the coins you spent on it come back automatically and immediately. This isn’t a support ticket you have to file - it’s a property of the system: you are never charged for an image you didn’t receive. We treat that as a reliability guarantee, not a courtesy.

Every failure resolves to exactly one of four codes, deliberately kept small:

• TIMEOUT - the generation took too long and was abandoned.
• MODERATION_REJECTED - the request violated content policy.
• VENDOR_ERROR - something failed upstream, on the generation side.
• UNKNOWN - a genuine catch-all for anything that doesn’t fit the other three.

A small, fixed set of codes is a deliberate choice - it’s something you can actually write a switch statement against, rather than pattern-matching on freeform error strings that might change underneath you.

Images expire in 30 days

Generated image bytes are kept for 30 days. After that, the history record of the generation still exists - your list endpoint still shows that it happened, when, and what it cost - but fetching the actual image content returns an HTTP 410 Gone. This is a plain storage-cost tradeoff, not a hidden one: if you want to keep an image past 30 days, download it and store it yourself. We won’t silently delete the record of the generation, only the bytes.

Rate limits aren’t the real ceiling

The per-minute rate limit on your API key (20 requests a minute for generation, 120 for reads, by default) exists to damp abuse, not to be the thing that actually limits how many images you can make. Your Fellowi Coins balance is the real ceiling - if you have the coins, you can spend them, up to that rate. If you want a tighter budget than your balance allows, a key can also carry an optional daily coin cap you set yourself, for your own cost control rather than ours.

Keys you can’t get back

An API key is shown to you exactly once, at creation. After that, only a hashed value and a short preview are stored on our side - the same posture we take with any other secret in the product. If you lose a key, you generate a new one; there is no recovery flow, because there is nothing on our end capable of recovering it.

Same wallet, same price

The API and the web appspend against the exact same Fellowi Coins balance, at the exact same price per quality tier - 40 coins for Standard, 60 for High quality. There is no separate “API pricing.” That’s deliberate: your cost is predictable no matter which door you generate through.

For the actual request/response shapes and working code samples, see our API quickstart, or head straight to the API Console to create a key.