Credits and billing
How Flat's Optical Music Recognition API is paid for. See Capabilities and credits on the overview page for the reference version.
Counting and charging
How are credits counted?
1 credit is 1 page. A 4 page PDF costs 4 credits, whichever flow you use. Credits are charged when the job starts, based on the total page count across every file in the job.
Everything before that point is free. Creating a draft job, uploading its files, listing your jobs, and canceling a draft cost nothing: only POST /omr/jobs/{job}/start (and autoStart: true, and the auto simple import) runs the conversion and bills for it.
Do not hardcode the ratio. Read costPerPage from GET /omr/capabilities, which is the authoritative value for the authenticated account.
Does the API use the same credits as the Flat apps?
Yes. One pool per Flat account, shared by the web, desktop, and mobile apps and the API.
For each job, credits are taken in this order:
- The page allowance included in the account's Flat or Flat for Education subscription.
- Any credit packs bought on the account.
This surprises people who expect the API to meter separately. If your subscription includes a monthly page allowance, a handful of API conversions can use it up.
Whose credits are spent?
The credits of the Flat account that owns the token you authenticate with. With a personal access token that is your own account; with OAuth2, it is the account of the user who authorized your app. See Whose credits are spent.
Do failed, cancelled, or retried jobs consume credits?
Only successful conversions ultimately consume credits. Credits are charged at job start, then reverted when:
- the job ends in
error, whatever theerrorCode, or - the job is cancelled before the worker finishes, including a draft you created and never started.
A job you retry after a failure is charged like any other job, and the failed attempt is refunded.
Estimating and monitoring spend
How do I estimate cost before running a batch?
Multiply your total page count by costPerPage. To avoid a 402 in the middle of a user flow, preflight against GET /omr/capabilities, which returns both costPerPage and the account's remainingCredits:
const caps = await fetch('https://api.flat.io/v2/omr/capabilities', { headers: auth }).then((r) => r.json());
const cost = pageCount * caps.costPerPage;
if (cost > caps.remainingCredits) {
// Send the user to https://flat.io/settings/ai-credits before starting the job.
}remainingCredits is only returned on an authenticated request, since there is no account to report a balance for otherwise. The rest of the response, costPerPage included, works unauthenticated, so you can feature-detect before a user connects an account.
Why did I get a 402?
A 402 means the account behind your token cannot pay for the job. It is out of credits, over quota, or on a plan that does not include OMR. Top up at flat.io/settings/ai-credits.
The fix in your code is the preflight check above: read remainingCredits before you start a job and surface a clear message, rather than letting the user discover the problem when the job fails.
Where can I see my usage history?
There is no credit-usage history endpoint in the public API yet. To audit what you have spent, list your finished jobs and count their pages:
curl -H "Authorization: Bearer $TOKEN" "https://api.flat.io/v2/omr/jobs?status=done"GET /omr/jobs returns your jobs newest first with cursor pagination through the Link header. Your current balance is always available as remainingCredits on GET /omr/capabilities.
Buying credits
Do credit packs expire or auto-renew?
Credit packs are one-off purchases. They are not a subscription, they do not auto-renew, and they do not expire while the account is active. Buy them on your account's AI credits page.
Packs currently on sale, generated from the live catalog:
| Pack | Price | Per page |
|---|---|---|
| 30 pages | $9.99 | $0.333 |
| 70 pages | $18.99 | $0.271 |
| 300 pages | $49.99 | $0.167 |
| 1,000 pages | $149 | $0.149 |
| 3,000 pages | $300 | $0.10 |
List prices in USD, excluding any local tax. Your own currency and the tax that applies to you are shown at checkout on your account's AI credits page.
The 1,000 and 3,000 page packs are behind the "Need 1000+ credits?" link on that page, not in the default grid. If you only see the smaller packs, that link is what you are looking for.
Is there volume pricing?
Yes, and it is self-serve. The price per page improves at every pack size, not just the largest ones, as the table above shows. Most integrations never need to talk to us about pricing: buy the pack that matches your volume.
If you expect volumes well beyond the largest pack, or you have specific contractual requirements, email developers@flat.io and we will work out something that fits.
Do credits bought in the Opuscan apps work with the API?
No. Opuscan is a separate consumer product sold through the app stores. Purchases made inside Opuscan are tied to the store account that made them, and are not shared with a Flat account or with this API.
Credits for the API must be on the Flat account behind your token, bought at flat.io/settings/ai-credits. The same applies in reverse: credits on your Flat account do not appear inside the Opuscan apps.