Align an upload to the text it reads

POST /v1/alignments

Starts aligning an upload to its text, given as sections with your own ids: paragraphs, sentences, verses or lines. The job runs in the background; poll GET /v1/jobs/{id} for the result.

Announcements and closing lines set apart by a pause are found and left out of the sections. Wording that differs slightly from your text is tolerated.

Leave out segments for a Bible reading: the passage is identified from what is said, from any verse to any verse and across chapters, and its verses become the sections. The result then holds passage. A recording that is not a reading, or only quotes a verse, fails with the code api_passage_unknown. Only the World English Bible is held, so a reading of another translation is found only when enough of its wording agrees.

Billed per second of audio when the job is done. Limited to 30 a minute per key.

Authentication

Send Authorization: Bearer $KEY from your server. Create or rotate keys.

Example request

bash

curl https://play.fellowverse.app/v1/alignments \
  -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"upload":"upl_Hk3vQ9xTmP2a","clips":true,"segments":[{"id":"v1","text":"Yahweh is my shepherd; I shall lack nothing."}]}'

Example IDs are placeholders. Use the upload or job ID returned by your own request.

Request body

Accepted content types: application/json.

Field	Type	Required	Description and constraints
`upload`	string	Yes	The id from `POST /v1/uploads`. Pattern: `^upl_[A-Za-z0-9_-]{12}$`.
`clips`	boolean	No	Make an MP3 clip of each section, cut in the quiet around it. Default: `false`.
`segments`	object[]	No	The text the recording reads, in order, as sections with your own ids. Leave it out for a Bible reading whose passage is to be found. The text may be up to 200,000 characters in all, about an hour of reading. Minimum items: `1`. Maximum items: `5000`.
`segments[].id`	string	Yes	Minimum length: `1`. Maximum length: `100`.
`segments[].text`	string	Yes	Minimum length: `1`. Maximum length: `20000`.

Unknown request fields are not accepted.

Responses

Status	Meaning
202	The job was queued.
400	The request could not be used. `invalid_request` when a field is missing or has the wrong type; `bad_request` when the audio or a value could not be read.
401	The key is missing, wrong, revoked, or past the end of its grace period after a roll. The code is `api_unauthorized`, and the reason says which.
403	The account is suspended (`api_suspended`), or a live key was used on an account that has test keys only (`api_live_locked`).
404	The upload, job or clip does not exist, or belongs to another account. The codes are `api_upload_missing`, `api_job_missing` and `api_file_missing`. `api_off` means the request went to an address that does not serve the API; use https://play.fellowverse.app.
429	A per-key limit for the minute was reached (`api_rate_limited`; the reason names the limit), or a test key used up its account's daily allowance (`api_test_quota`; the fix says when it resets).
500	Something went wrong on our side. The code is `internal`.

202: application/json

Field	Type	Required	Description and constraints
`id`	string	Yes
`status`	string	Yes	Always `queued`.
`url`	string	Yes	Where to poll for the job.

“Required” is relative to the containing object. Optional success results and failure errors depend on the job state.

Errors and limits

JSON errors contain error.code, error.problem, error.reason and error.fix. Handle errors and retries and check test and live limits.

Need the contract? Download OpenAPI. Manage keys and account access in the developer console.

Start here · Guides · API reference