This tutorial will show you how to use the textreel API to convert an audio file into a video file.
All example requests are made to the test environment https://sandbox.textreel.com. Before using your code in production you will want to switch to the live environment by using https://api.textreel.com.
Authentication
All requests are made over HTTPS using HTTP Basic authentication. Use your API key as the username. No password is required.
To start your first conversion, send a POST request to the /v1/conversions endpoint. See the Create a conversion endpoint for a full list of parameters.
If successful, the response object will contain the ID of the conversion, along with the amount of credits the conversion has cost. You can read the pricing section for a full breakdown of costs.
If you choose to add a transcript of the audio to the video you will then need to use the transcript endpoints to view the transcript and correct any mistakes.
You can use the retrieve a conversion endpoint to check if your video has been generated. If it has, the response will contain a status of "Ready to download" along with a URL to download the video
Once you've seen that your video is ready to download, simply send a GET request to /v1/videos/{id}/content to retrieve your video and save the contents to a local file.
This is a basic example and you may wish to opt for a more complex integration such as adding a transcript as well as making use of all of the customization options available. Take a look at the full list of endpoints for more detail.
Reference
Securing API keys
Your API keys are used to identify you and to bill usage of the textreel API to your account. Therefore it's important to maintain the secrecy of your API keys, as you would a password or payment details for any other account.
If you discover that you have accidentally shared one or more of your API keys, you should immediately deactivate the affected keys via the textreel developer portal.
Do not store your textreel API keys in publicly accessible source code repositories.
Paging
When you make a request that can contain more than one result such as the /v1/conversions endpoint the items in the response will be paged. The response will contain paging information.
You can control the paging by using the start and limit parameters. For example https://api.textreel.com/v1/conversions?start=51&limit=50.
Response codes
textreel uses standard HTTP response codes. Response codes starting with 2 indicate that the call has been successful, codes starting with 4 indicate that there was an error caused by the information suppied by the user (e.g Incorrect credentials, missing data or a validation error) and codes starting with 5 indicate a server error.
Rate limits
We impose rate limits to ensure the API is accesible to all users, please find details of these limits below.
https://api.textreel.com
3 calls per second
https://sandbox.textreel.com
1 call per second
If you exceed the rate limit the API will return the 429 HTTP status code. If you receive this error you should program your application to wait for a period of time before retrying the request. If you find the rate limits too restrictive please contact us.
Test and Live Environments
Environment
Endpoint
Example key
Test
https://sandbox.textreel.com
text_a2kjfDFMK30rtkgfdsjnm3
Live
https://api.textreel.com
live_40ksfKLMdsfF3F0IK4Md24
In the test environment you can generate as many videos as you like, free of charge, until you are happy with your integration. However your audio clips must be less than 2 minutes long and they will have the textreel watermark on them. When you are ready to switch to the live environment you will need to start using your live key and use the https://api.textreel.com endpoint.
Versioning
At the moment the latest version of the API is v1. To use a specfic version of the API you'll need to prefix your API calls with the version number. For example, to use v1 of the Create a conversion endpoint you'll need to make a POST request to https://api.textreel.com/v1/conversions.
Once a new version of the API is released you will be notified via email with instructions on how to upgrade to the latest version.
Pricing
The textreel API works on a "pay as you go" basis whereby you buy credits that are deducted from your account as you make conversions. Every minute of audio you convert costs 1 credit. Audio length is always rounded up to the nearest minute (e.g a video of 1 minute 30 seconds will cost 2 credits).
The more credits you buy the cheaper each credit will be, as demonstrated from the table below.
The audio file you want to convert to video. Must be in mp3, m4a, ogg of wav format.
namestringRequired
The name of the conversion. This won't be displayed on the video but can used to identify a conversion with a human readable name.
titlestring
A title to be added to the finished video. This will only been shown if transcript is set to false.
resolutionstringRequired
The resolution you would like for the generated video. Please make sure you select a valid resolution
transcriptbool
Whether or not you would like a transcription of the audio to appear on the video
text_colourstring
The colour of the transcription text. The default value is #ffffff. Only applicable if transcript is set to true
background_colourstring
The colour of the video background. The default value is #000000
background_imagefile
A background image for the video, if not supplied the background_colour will be used instead. For the best results upload an image with the same aspect ratio as the resolution you've selected. Max file size 8MB.
logofile
Use this paramater if you would like a logo to appear on the bottom left of the video. If you are going to supply a logo, the dimensions must be square and no larger than 500px x 500px.
fontstring
The font of the transcription text. Only applicable if transcript is set to true. Please make sure you select a valid font
soundwavebool
Whether or not you would like a soundwave to appear on the video. Default is false
profanity_filterbool
Set to true to filter profanities with asterisks. Default is true.
languagestring
The language of the audio file, used to help with transcription accuracy. Only applicable if transcript is set to true. Please make sure you select a valid language
video_formatstringRequired
The desired format for the generated video. Please make sure you select a valid video format
templatestringRequired
The animation style to apply to the transcription text. Only applicable if transcript is set to true. Please make sure you select a valid template
Cancels a conversion. If the video hasn't already been generated, or the transcript hasn't already been fetched, your credits for this conversion will be refunded.
If you opted to add a transcript to your video, by setting the transcript paramter to true when creating your conversion, you can use this endpoint to fetch the transcript.
Once you have retrieved your transcript you may notice that some words are incorrect. This is more often the case if the word has a low confidence score.
Use this endpoint to correct any mistakes using the word parameter. You can also replace a word with multiple words, for example the transcript might have interpreted "sell her" as "cellar".
curl https://sandbox.textreel.com/v1/conversions/1/transcript/1?word=corrected%20word \
-u test_lglFMa20EdjD09df2KFZAs49: \
-X PUT
Below is a list of fonts we support. Please use the numeric ID when making your request. If you require a font that's not on this list, please get in touch.
ID
Font
1
Aller
2
Amatic
3
Antonio
4
Caviar Dreams
5
Helsinki
6
Komikax
7
Lato
8
Lineto Circular
9
Open Sans
10
Oswald
11
Pacifico
12
Roboto
Resolutions
Below is a list of resolutions we support. Please use the code when making your request. If you require a resolution that's not on this list, please get in touch.
code
Width
Height
1080x720
1080px
720px
720x720
720px
720px
Languages
Below is a list of langauges we support for transcriptions. Please use the 5 character code when making your request.
Code
Language
ar-AR
Arabic
pt-BR
Brazilian Portuguese
zh-CN
Chinese
nl-NL
Dutch
en-AU
English (Australian)
en-GB
English (United Kingdom)
en-US
English (United States)
fr-FR
French
fr-CA
French (Canadian)
de-DE
German
it-IT
Italian
ja-JP
Japanese
ko-KR
Korean
es-AR
Spanish (Argentinian)
es-ES
Spanish (Castilian)
es-CL
Spanish (Chilean)
es-CO
Spanish (Colombian)
es-MX
Spanish (Mexican)
es-PE
Spanish (Peruvian)
Video formats
Below is a list of video formats we support for conversions. Please use the 3 character code when making your request.
Code
Format
mp3
MP3
avi
AVI
Templates
If you are adding a transcript to your video, you have 4 different templates to choose from, which apply a different animation style to the text.