Danger

V1 API is deprecated and will be removed in the future. See API V2 documentation for information about how to migrate.

Beey API V1 documentation

This documentation discusses the Beey API V1.

How to use this API documentation

  • To access Beey API, you need to first have an account in Beey, either on our cloud at editor.beey.io or on your own instance if you self-host Beey on your own infrastructure.

  • To authenticate, you need to have an API token. You can find it in your Account page in Beey under My Profile -> API Token.

What Beey API does

The Beey API allows you not only to transcribe audio or video in almost any format, it also enables you to manage the transcribed projects – typically share the project with Beey users in your team for manual correction, or update notes, tags or name on the project. Various export options are available for the transcribed projects including xml, pdf, docx, srt, vtt, ssa.

Typical workflow directed over API works as follows:

  • Create project.

  • Start media upload.

  • Enqueue the project for transcription. If your queue is empty, transcription starts immediately while the media is uploading.

  • Optionally share the project with other Beey users for editing. The project is editable even while the transcription is running.

  • Poll for transcription completion.

  • After transcription finishes, export transcription in any format.

  • Optionally poll for tag update by editor and export the corrected transcription after that.

C# library

If you are using .NET, a library implementing connection to the most important endpoints including examples is available here: beey-data-exchange-model.

Direct HTTP

An example script in Python that shows the basic usage of Beey API can be found here: beey-example.py.

The script obtains authentication token, creates a project, uploads media file, enqueues the project for transcription and waits until the transcription is finished. After that it downloads the transcription as either xml or subtitles.

Frequently asked questions

What are the differences between CurrentTrsx and OriginalTrsx?

OriginalTranscription is always created if the transcription is successful. It does not change when someone edits the document in Beey.

CurrentTranscription updates when anyone edits the document in Beey, but it is available only after someone edits the document in editor (or uploads CurrentTrsx via API)

There are two major differences between OriginalTranscription and CurrentTranscription: OriginalTranscription contains additional information about non-speech events – phrases containing string [n:: or [h::. Moreover, unidentified speakers are saved in different format. If you need to parse unknown speakers from OriginalTranscription,you need to match the surname with this regex: /^S[0-9]{4,5}$/ (S and four or five digits) to detect that it is an unknown speaker and convert it to any format that you want.

Why do I get error 409? What is AccessToken?

Whenever you make any change of a project – updating trsx, changing tags, sharing, changing name, etc, You need to prove that you had up to date version of the project before you made that change. Otherwise the change will be rejected to prevent conflicts.

Every operation that changes project returns project in body. In the response, you can find an integer AccessToken. You can think of AccessToken as the project version. In the next request, you must send the last AccessToken that you received after your last change of the project.

If you still get error 409, there was probably some unexpected change of the project. Fetch Project to to update the project with the changes made by someone else. Then send your request again with the correct AccessToken.

Do not confuse AccessToken and API token. API token is a string that proves that you are authorized to make the change. AccessToken is an integer that tells the current version of the project.

How long is the API token valid?

The API token is valid indefinitely as long as your account is active.

Media file was uploaded but the transcription is loading and there is no error

Check that you called the Enqueue endpoint, which triggers the transcription, see the example scripts.