OMR API FAQ
The questions developers ask us most about Flat's Optical Music Recognition API, grouped by topic. If your question is not answered here, email developers@flat.io.
Browse by topic
| Topic | What it covers |
|---|---|
| Credits and billing | How credits are counted, what a job costs, refunds, 402 errors, packs, and volume pricing. |
| Limits, performance, and integration | Page, file, and size limits, concurrency, processing time, and serving many end users from one account. |
| Recognition quality and languages | What OMR reads well, lyric language support, what to do about a bad conversion, and ML model versions. |
| Commercial use, privacy, and data | Commercial rights to the output, model training, data retention, deletion, and the DPA. |
Getting started
How do I get access to the OMR API?
Create a Flat account, then generate a personal access token from your developer settings. There is no separate OMR signup, waitlist, or approval step, and the same token works for both OMR flows.
If you are building an OAuth2 app for other people's accounts instead, request the omr scope, plus scores when the result goes into their Flat Library. See Authentication and scopes.
Is there a free trial or a sandbox?
There is no self-serve trial or sandbox environment, but almost the entire integration can be built and tested for free. Only starting a job costs anything.
Free, no credits consumed:
GET /omr/capabilities, which needs no authentication at all, so you can wire up feature detection, limits, and your language picker before a user ever connects an account.- Creating a draft job with
POST /omr/jobs. - Uploading files to it with
POST /omr/jobs/{job}/files, including the multi-page and incremental-capture flow. - Listing your jobs, and canceling a draft you never started.
Only POST /omr/jobs/{job}/start runs the conversion and charges credits, along with autoStart: true on the one-shot form and the auto simple import. So you can exercise your upload path, your error handling, and your whole draft state machine end to end before spending a single credit.
If you are evaluating OMR for a product and need to discuss it, email developers@flat.io and tell us what you are building and roughly what volume you expect.
Which flow should I use, the Jobs API or the simple import?
Reach for the Interactive Jobs API when you want live progress, an optional step for the user to correct detected instruments, MusicXML or MIDI output without creating a Flat score, or the ability to add pages one at a time (which is how mobile capture works).
Reach for the auto simple import when you just want a score in the Flat Library and you are already importing MusicXML or MIDI through POST /scores. It is two calls and one code path for every format.
The comparison table on the overview page lays the two side by side.
Is the OMR API the same thing as Opuscan?
No. Opuscan is our dedicated consumer scan-to-score product, sold through the app stores. It runs on the same recognition engine, but it is a separate product with no developer API, and its credits are not shared with a Flat account or with this API. See Do credits bought in the Opuscan apps work with the API?
Related
- OMR overview for scopes, credits, capabilities, and error codes.
- Interactive Jobs API and auto simple import.
- API Reference: OMR.