Limits, performance, and integration
What Flat's Optical Music Recognition API can handle, how fast it runs, and how to shape a production integration around it.
Limits
What are the limits?
These are the current values. They are not contractual: read them at runtime from GET /omr/capabilities rather than hardcoding them, so your client keeps working when they change.
| Limit | Current value | Capabilities field |
|---|---|---|
| Pages per job | 50 | maxPages |
| Files per job | 100 | maxFiles |
| Size per file | 25 MiB (26,214,400 bytes) | maxFileSize |
| Jobs processing in parallel | 10 per account | maxParallelJobs |
| Accepted input types | PDF, JPEG, PNG | acceptedMimeTypes |
If your workload needs more than this, email developers@flat.io and tell us what you are running. These limits are adjustable.
How many jobs can I run at the same time?
10 per account, as reported by maxParallelJobs. Queue beyond that in your own worker rather than firing everything at once.
This is a different limit from the REST API request rate, which is 7,200 authenticated requests per hour. See Rate limits for the request headers that tell you where you stand. Polling a job with the wait parameter is the cheapest way to follow progress without burning request quota. See Follow progress.
Which file formats are accepted?
PDF, JPEG, and PNG, as reported by acceptedMimeTypes.
One caveat worth knowing: the auto simple import through POST /scores handles PDF only. If you need to send photos or scanned images, use the Interactive Jobs API, which accepts all three and lets you add pages one at a time.
Give each file either a filename with a recognizable extension or an explicit mimeType. If neither is present the call returns 400 (OMR_MIME_REQUIRED).
Performance
How long does a conversion take?
A single page document typically takes around 30 seconds. Occasionally it can take up to about a minute per page.
Multi-page documents are processed partly in parallel, depending on the number of pages, parts, and instruments, so total time does not grow linearly with page count. A 10 page score is considerably faster than 10 times a single page.
Design for this rather than guessing: the Jobs API reports a progress object with a percent and a stable key you can map onto your own UI, and long-polling with wait returns as soon as the state changes. See Follow progress.
Integration patterns
Can my backend use one account for all my end users?
Yes. A single Flat account and token can process files on behalf of any number of end users. Your users do not need their own Flat accounts, and they never have to connect one.
All credits are billed to the account behind the token, so this is the usual shape for a commercial product: your backend holds one personal access token, and your users never see Flat. See Whose credits are spent and Commercial use.
Use OAuth2 instead when you want each conversion billed to your user's own Flat account, for example in an app that plugs into their existing Flat library.
Can I cache and reuse the output instead of converting the same pages again?
Yes, and you should. The MusicXML and MIDI a job produces are yours to store, reuse, and serve to as many of your own users as you like. See Commercial use.
Deduplicating uploads on your side, by hashing the file before you submit it, is the single easiest way to cut credit spend when several users upload the same score.
Do I have to create a Flat score?
No. Create the job with output: "musicxml" and the result never enters a Flat Library. You download MusicXML, compressed MusicXML (.mxl), MIDI, or a thumbnail.png preview of the first page straight from the exports endpoint.
This path also needs only the omr scope, not scores, and it is the one covered by the 30 day retention window, so you can delete the data as soon as you have collected it.
Use output: "library" (the default) when you do want a score in the user's Flat Library, for example so they can edit it in the Flat editor afterwards.
Related
- Capabilities and credits on the OMR overview.
- Rate limits for the request-per-hour quota.
- Credits and billing.