textreel: Docs

Getting started

Introduction

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.

curl https://sandbox.textreel.com/v1/conversions \
-u test_lglFMa20EdjD09df2KFZAs49:

$endpoint = "https://sandbox.textreel.com/v1/conversions";
$api_key = "test_lglFMa20EdjD09df2KFZAs49"; // Find your API keys at https://textreel.com/dashboard/keys

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $endpoint);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, $api_key . ":"); // Authenticate using key
$body = curl_exec($ch);
curl_close($ch);

$conversions = json_decode($body, true);

const request = require('request');
const apiKey = 'test_lglFMa20EdjD09df2KFZAs49';

request.get({
    url: 'https://sandbox.textreel.com/v1/conversions',
    headers: {
        Authorization: 'Basic ' + Buffer.from(apiKey).toString('base64')
    }
}, function(error, response, body) {
    console.log(body);
});

{
    "status": 200,
    "message": "Sucessfully fetched conversions",
    "sandbox": true,
    "data": [
        {
            id: 20,
            name: 'Audio conversion through API',
            ...
        },
        {
            id: 21,
            name: 'My first audio conversion',
            ...
        },
        {
            id: 22,
            name: 'Yet another audio conversion',
            ...
        }
    ],
    "paging": {
        total: 60,
        count: 10,
        start: 51,
        limit: 25
    }
}

Your test key - to be used with the sandbox - is prefixed with test_ and your live key to be used in a production environment is prefixed with live_

If you try and use your test key in production or your live key in sandbox your request will fail and an error will be returned.

To generate your API keys please create an account.

Starting your first conversion

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.

curl https://sandbox.textreel.com/v1/conversions \
 -u test_lglFMa20EdjD09df2KFZAs49: \
 -X POST \
 -F "audio_file=@/path/to/audio.mp3" \
 -F "video_format=mp4"

$endpoint = "https://sandbox.textreel.com/v1/conversions";
$api_key = "test_lglFMa20EdjD09df2KFZAs49"; // Find your API keys at https://textreel.com/dashboard/keys
$audio_file_path = "/path/to/audio.mp3"

// Since PHP 5.5+ CURLFile is the preferred method for uploading files
if(function_exists('curl_file_create')) {
  $audio_file = curl_file_create($audio_file_path);
} else {
  $audio_file = '@' . realpath($audio_file_path);
}

$post_data = array(
  "audio_file" => $audio_file,
  "video_format" => 'mp4'
);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $endpoint);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
curl_setopt($ch, CURLOPT_SAFE_UPLOAD, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, $api_key . ":"); // Authenticate using key
$body = curl_exec($ch);
curl_close($ch);

$response = json_decode($body, true);

const fs = require('fs');
const request = require('request');
const apiKey = 'test_lglFMa20EdjD09df2KFZAs49';

request.post({
    url: 'https://sandbox.textreel.com/v1/conversions',
    formData: {
        audio_file: fs.createReadStream('/path/to/audio.mp3'),
        logo: fs.createReadStream('/path/to/logo.jpg'),
        title: 'A title for the video',
        video_format: 'mp4',
        resolution: '720x720',
        template: 1,
        transcript: 0,
        name: 'The name of the conversion'
    },
    headers: {
        Authorization: 'Basic ' + Buffer.from(apiKey).toString('base64')
    }
}, function(error, response, body) {
    console.log(body);
});

{
    "status": 201,
    "message": "Sucessfully created conversion",
    "sandbox": true,
    "data": {
        id: 20,
        name: 'Audio conversion through API',
        file_extension: '.mp3',
        size: 74.61,
        audio_length: 19,
        resolution: '720x720',
        text_colour: '#ffffff',
        background_colour: '#000000',
        background_image: null,
        background_image_extension: null,
        profanity_filter: true,
        language: 'en-US',
        soundwave: true,
        template: 1,
        video_format: 'mp4',
        credits: 1,
        status: 'Fetching transcript',
    }
}

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

{
    "status": 200,
    "message": "Sucessfully fetched conversion",
    "sandbox": true,
    "data": {
        id: 20,
        name: 'Audio conversion through API',
        ...
        status: 'Ready to download',
        download_url: 'https://sandbox.textreel.com/v1/videos/1'
    }
}

Download the generated 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.

curl https://sandbox.textreel.com/v1/videos/1/content \
 -u test_lglFMa20EdjD09df2KFZAs49: \
 -L \
 -O \
 -J

$endpoint = "https://sandbox.textreel.com/v1/videos/1/content";
$api_key = "test_lglFMa20EdjD09df2KFZAs49"; // Find your API keys at https://textreel.com/dashboard/keys

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $endpoint);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, $api_key . ":"); // Authenticate using key

$fh = fopen('path/to/local_video.mp4', "wb");
curl_setopt($ch, CURLOPT_FILE, $fh);

$body = curl_exec($ch);
curl_close($ch);

$conversion = json_decode($body, true);

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.

{
    "status": 200,
    "message": "Sucessfully fetched conversions",
    "sandbox": true,
    "data": {
        ...
    }
    "paging": {
        total: 60,
        count: 10,
        start: 51,
        limit: 25
    }
}

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.

Number of credits	Cost per credit
20	$0.50 each	Buy 20 credits for $9.99
50	$0.45 each	Buy 50 credits for $22.50
100	$0.40 each	Buy 100 credits for $39.99
200	$0.35 each	Buy 200 credits for $69.99

Endpoints

Get balance

GET

/v1/balance

Retrieve your balance to find out how many credits you have in your account.

curl https://sandbox.textreel.com/v1/balance \
-u test_lglFMa20EdjD09df2KFZAs49:

$endpoint = "https://sandbox.textreel.com/v1/balance";
$api_key = "test_lglFMa20EdjD09df2KFZAs49"; // Find your API keys at https://textreel.com/dashboard/keys

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $endpoint);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, $api_key . ":"); // Authenticate using key
$body = curl_exec($ch);
curl_close($ch);

$balance = json_decode($body, true);

const request = require('request');
const apiKey = 'test_lglFMa20EdjD09df2KFZAs49';

request.get({
    url: 'https://sandbox.textreel.com/v1/balance',
    headers: {
        Authorization: 'Basic ' + Buffer.from(apiKey).toString('base64')
    }
}, function(error, response, body) {
    console.log(body);
});

{
    "status": 200,
    "message": "Successfully fetched balance",
    "sandbox": true,
    "data": {
        "credits_bought": 290,
        "credits_used": "11",
        "balance": 279
    }
}

Create a conversion

POST

/v1/conversions

audio_file file Required

The audio file you want to convert to video. Must be in mp3, m4a, ogg of wav format.

name string Required

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.

title string

A title to be added to the finished video. This will only been shown if transcript is set to false.

resolution string Required

The resolution you would like for the generated video. Please make sure you select a valid resolution

transcript bool

Whether or not you would like a transcription of the audio to appear on the video

text_colour string

The colour of the transcription text. The default value is #ffffff. Only applicable if transcript is set to true

background_colour string

The colour of the video background. The default value is #000000

background_image file

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.

logo file

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.

font string

The font of the transcription text. Only applicable if transcript is set to true. Please make sure you select a valid font

soundwave bool

Whether or not you would like a soundwave to appear on the video. Default is false

profanity_filter bool

Set to true to filter profanities with asterisks. Default is true.

language string

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_format string Required

The desired format for the generated video. Please make sure you select a valid video format

template string Required

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

curl https://sandbox.textreel.com/v1/conversions \
 -u test_lglFMa20EdjD09df2KFZAs49: \
 -X POST \
 -F "audio_file=@/path/to/audio.mp3" \
 -F "video_format=mp4"

$endpoint = "https://sandbox.textreel.com/v1/conversions";
$api_key = "test_lglFMa20EdjD09df2KFZAs49"; // Find your API keys at https://textreel.com/dashboard/keys
$audio_file_path = "/path/to/audio.mp3"

// Since PHP 5.5+ CURLFile is the preferred method for uploading files
if(function_exists('curl_file_create')) {
  $audio_file = curl_file_create($audio_file_path);
} else {
  $audio_file = '@' . realpath($audio_file_path);
}

$post_data = array(
  "audio_file" => $audio_file,
  "video_format" => 'mp4'
);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $endpoint);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
curl_setopt($ch, CURLOPT_SAFE_UPLOAD, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, $api_key . ":"); // Authenticate using key
$body = curl_exec($ch);
curl_close($ch);

$response = json_decode($body, true);

const fs = require('fs');
const request = require('request');
const apiKey = 'test_lglFMa20EdjD09df2KFZAs49';

request.post({
    url: 'https://sandbox.textreel.com/v1/conversions',
    formData: {
        audio_file: fs.createReadStream('/path/to/audio.mp3'),
        logo: fs.createReadStream('/path/to/logo.jpg'),
        title: 'A title for the video',
        video_format: 'mp4',
        resolution: '720x720',
        template: 1,
        transcript: 0,
        name: 'The name of the conversion'
    },
    headers: {
        Authorization: 'Basic ' + Buffer.from(apiKey).toString('base64')
    }
}, function(error, response, body) {
    console.log(body);
});

{
    "status": 201,
    "message": "Sucessfully created conversion",
    "sandbox": true,
    "data": {
        id: 20,
        name: 'Audio conversion through API',
        file_extension: '.mp3',
        size: 74.61,
        audio_length: 19,
        resolution: '720x720',
        text_colour: '#ffffff',
        background_colour: '#000000',
        background_image: null,
        background_image_extension: null,
        profanity_filter: true,
        language: 'en-US',
        soundwave: true,
        template: 1,
        video_format: 'mp4',
        credits: 1,
        status: 'Fetching transcript',
    }
}

Retrieve a conversion

GET

/v1/conversions/{$id}

Retrieves a single conversion.

curl https://sandbox.textreel.com/v1/conversions/1 \
-u test_lglFMa20EdjD09df2KFZAs49:

$endpoint = "https://sandbox.textreel.com/v1/conversions/1";
$api_key = "test_lglFMa20EdjD09df2KFZAs49"; // Find your API keys at https://textreel.com/dashboard/keys

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $endpoint);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, $api_key . ":"); // Authenticate using key
$body = curl_exec($ch);
curl_close($ch);

$conversion = json_decode($body, true);

const request = require('request');
const apiKey = 'test_lglFMa20EdjD09df2KFZAs49';
const conversionID = 1;

request.get({
    url: 'https://sandbox.textreel.com/v1/conversions/' + conversionID,
    headers: {
        Authorization: 'Basic ' + Buffer.from(apiKey).toString('base64')
    }
}, function(error, response, body) {
    console.log(body);
});

{
    "status": 200,
    "message": "Sucessfully fetched conversion",
    "sandbox": true,
    "data": {
        id: 20,
        name: 'Audio conversion through API',
        file_extension: '.mp3',
        size: 74.61,
        audio_length: 19,
        resolution: '720x720',
        text_colour: '#ffffff',
        background_colour: '#000000',
        background_image: null,
        background_image_extension: null,
        profanity_filter: true,
        language: 'en-US',
        soundwave: true,
        template: 1,
        video_format: 'mp4',
        credits: 1,
        status: 'Fetching transcript',
    }
}

Edit a conversion

PUT

/v1/conversions/{$id}

generate_video boolean Required

Setting this paramter to true will start the video generation for your conversion.

Please note you only have to use this endpoint if your conversion has a transcript.

Once you are happy with your transcript, use this endpoint to start generating the video for your conversion.

curl https://sandbox.textreel.com/v1/conversions/1?generate_video=true \
 -u test_lglFMa20EdjD09df2KFZAs49: \
 -X PUT

$endpoint = "https://sandbox.textreel.com/v1/conversions/1";
$api_key = "test_lglFMa20EdjD09df2KFZAs49"; // Find your API keys at https://textreel.com/dashboard/keys

$put_data = array(
  "generate_video" => true
);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $endpoint);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($put_data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, $api_key . ":"); // Authenticate using key
$body = curl_exec($ch);
curl_close($ch);

$response = json_decode($body, true);

const request = require('request');
const apiKey = 'test_lglFMa20EdjD09df2KFZAs49';
const conversionID = 1;

request.put({
    url: 'https://sandbox.textreel.com/v1/conversions/' + conversionID,
    json: {
        generate_video: true
    },
    headers: {
        Authorization: 'Basic ' + Buffer.from(apiKey).toString('base64')
    }
}, function(error, response, body) {
    console.log(body);
});

{
    "status": 200,
    "message": "Sucessfully updated conversion",
    "sandbox": true,
    "data": {
        id: 20,
        name: 'Audio conversion through API',
        file_extension: '.mp3',
        size: 74.61,
        audio_length: 19,
        resolution: '720x720',
        text_colour: '#ffffff',
        background_colour: '#000000',
        background_image: null,
        background_image_extension: null,
        profanity_filter: true,
        language: 'en-US',
        soundwave: true,
        template: 1,
        video_format: 'mp4',
        credits: 1,
        status: 'Generating video',
    }
}

Cancel a conversion

DELETE

/v1/conversions/{$id}

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.

curl https://sandbox.textreel.com/v1/conversions/1 \
 -u test_lglFMa20EdjD09df2KFZAs49: \
 -X DELETE

$endpoint = "https://sandbox.textreel.com/v1/conversions/1";
$api_key = "test_lglFMa20EdjD09df2KFZAs49"; // Find your API keys at https://textreel.com/dashboard/keys

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $endpoint);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, $api_key . ":"); // Authenticate using key
$body = curl_exec($ch);
curl_close($ch);

$conversions = json_decode($body, true);

const request = require('request');
const apiKey = 'test_lglFMa20EdjD09df2KFZAs49';
const conversionID = 1;

request.del({
    url: 'https://sandbox.textreel.com/v1/conversions/' + conversionID,
    headers: {
        Authorization: 'Basic ' + Buffer.from(apiKey).toString('base64')
    }
}, function(error, response, body) {
    console.log(body);
});

{
    "status": 204,
    "message": "Sucessfully deleted conversion",
    "sandbox": true,
}

List conversions

GET

/v1/conversions

Retrieves a paged list of all of your conversions.

curl https://sandbox.textreel.com/v1/conversions \
-u test_lglFMa20EdjD09df2KFZAs49:

$endpoint = "https://sandbox.textreel.com/v1/conversions";
$api_key = "test_lglFMa20EdjD09df2KFZAs49"; // Find your API keys at https://textreel.com/dashboard/keys

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $endpoint);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, $api_key . ":"); // Authenticate using key
$body = curl_exec($ch);
curl_close($ch);

$conversions = json_decode($body, true);

const request = require('request');
const apiKey = 'test_lglFMa20EdjD09df2KFZAs49';

request.get({
    url: 'https://sandbox.textreel.com/v1/conversions',
    headers: {
        Authorization: 'Basic ' + Buffer.from(apiKey).toString('base64')
    }
}, function(error, response, body) {
    console.log(body);
});

{
    "status": 200,
    "message": "Sucessfully fetched conversions",
    "sandbox": true,
    "data": [
        {
            id: 20,
            name: 'Audio conversion through API',
            ...
        },
        {
            id: 21,
            name: 'My first audio conversion',
            ...
        },
        {
            id: 22,
            name: 'Yet another audio conversion',
            ...
        }
    ],
    "paging": {
        total: 60,
        count: 10,
        start: 51,
        limit: 25
    }
}

Retrieve a transcript

GET

/v1/conversions/{$id}/transcript

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.

curl https://sandbox.textreel.com/v1/conversions/1/transcript \
-u test_lglFMa20EdjD09df2KFZAs49:

$endpoint = "https://sandbox.textreel.com/v1/conversions/1/transcript";
$api_key = "test_lglFMa20EdjD09df2KFZAs49"; // Find your API keys at https://textreel.com/dashboard/keys

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $endpoint);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, $api_key . ":"); // Authenticate using key
$body = curl_exec($ch);
curl_close($ch);

$transcript = json_decode($body, true);

const request = require('request');
const apiKey = 'test_lglFMa20EdjD09df2KFZAs49';
const conversionID = 1;

request.get({
    url: 'https://sandbox.textreel.com/v1/conversions/' + conversionID + '/transcript',
    headers: {
        Authorization: 'Basic ' + Buffer.from(apiKey).toString('base64')
    }
}, function(error, response, body) {
    console.log(body);
});

{
    "status": 200,
    "message": "Successfully fetched transcripts",
    "sandbox": true,
    "data": [
        {
            "sentence": "1",
            "words": [
            {
                "id": "450",
                "sentence": "1",
                "word": "Mr",
                "start": "0.89",
                "end": "1.27",
                "confidence": "1.0"
            },
            {
                "id": "451",
                "sentence": "1",
                "word": "and",
                "start": "1.27",
                "end": "1.37",
                "confidence": "0.8"
            },
            {
                "id": "452",
                "sentence": "1",
                "word": "Mrs",
                "start": "1.37",
                "end": "1.67",
                "confidence": "1.0"
            },
            {
                "id": "453",
                "sentence": "1",
                "word": "Dursley",
                "start": "1.67",
                "end": "2.40",
                "confidence": "1.0"
            },
            ...
        }
    ]
}

Edit transcript word

PUT

/v1/conversions/{$conversion_id}/transcript/{$word_id}

word string Required

What the current word should be replaced with

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

$endpoint = "https://sandbox.textreel.com/v1/conversions/1/transcript/1";
$api_key = "test_lglFMa20EdjD09df2KFZAs49"; // Find your API keys at https://textreel.com/dashboard/keys

$put_data = array(
  "word" => 'Test'
);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $endpoint);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($put_data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, $api_key . ":"); // Authenticate using key
$body = curl_exec($ch);
curl_close($ch);

$response = json_decode($body, true);

const request = require('request');
const apiKey = 'test_lglFMa20EdjD09df2KFZAs49';
const conversionID = 1;
const wordID = 1;

request.put({
    url: 'https://sandbox.textreel.com/v1/conversions/' + conversionID + 'transcript/' + wordID,
    json: {
        word: 'New word'
    },
    headers: {
        Authorization: 'Basic ' + Buffer.from(apiKey).toString('base64')
    }
}, function(error, response, body) {
    console.log(body);
});

{
    "status": 200,
    "message": "Successfully updated transcript word",
    "sandbox": true,
    "data": {
        "id": "450",
        "sentence": "1",
        "word": "Mr",
        "start": "0.89",
        "end": "1.27",
        "confidence": "1.0"
    }       
}

Delete transcript word

DELETE

/v1/conversions/{$conversion_id}/transcript/{$word_id}

If you want to remove a word from the transcript use this endpoint.

curl https://sandbox.textreel.com/v1/conversions/1/transcript/1 \
 -u test_lglFMa20EdjD09df2KFZAs49: \
 -X DELETE

$endpoint = "https://sandbox.textreel.com/v1/conversions/1/transcript/1";
$api_key = "test_lglFMa20EdjD09df2KFZAs49"; // Find your API keys at https://textreel.com/dashboard/keys

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $endpoint);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, $api_key . ":"); // Authenticate using key
$body = curl_exec($ch);
curl_close($ch);

$conversions = json_decode($body, true);

const request = require('request');
const apiKey = 'test_lglFMa20EdjD09df2KFZAs49';
const conversionID = 1;
const wordID = 1;

request.del({
    url: 'https://sandbox.textreel.com/v1/conversions/' + conversionID + 'transcript/' + wordID,
    headers: {
        Authorization: 'Basic ' + Buffer.from(apiKey).toString('base64')
    }
}, function(error, response, body) {
    console.log(body);
});

{
    "status": 204,
    "message": "Sucessfully deleted transcript word",
    "sandbox": true
}

Retrieve a video

GET

/v1/videos/{$id}

Once a conversion has been completed, you can use this endpoint to retrieve the generated video.

curl https://sandbox.textreel.com/v1/videos/1 \
 -u test_lglFMa20EdjD09df2KFZAs49:

$endpoint = "https://sandbox.textreel.com/v1/videos/1";
$api_key = "test_lglFMa20EdjD09df2KFZAs49"; // Find your API keys at https://textreel.com/dashboard/keys

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $endpoint);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, $api_key . ":"); // Authenticate using key

$body = curl_exec($ch);
curl_close($ch);

$conversion = json_decode($body, true);

const request = require('request');
const apiKey = 'test_lglFMa20EdjD09df2KFZAs49';
const videoID = 1;

request.get({
    url: 'https://sandbox.textreel.com/v1/videos/' + videoID,
    headers: {
        Authorization: 'Basic ' + Buffer.from(apiKey).toString('base64')
    }
}, function(error, response, body) {
    console.log(body);
});

{
    "status": 200,
    "message": "Sucessfully fetched video",
    "sandbox": true,
    "data": {
        id: 1,
        audio_id: 20,
        credits: 1,
        name: 'final.mp4',
        extension: '.mp4',
        size: 966304
    }
}

Retrieve video contents

GET

/v1/videos/{$id}/contents

Once a conversion has been completed, you can use this endpoint to retrieve the generated video contents and save them to a local file.

curl https://sandbox.textreel.com/v1/videos/1/content \
 -u test_lglFMa20EdjD09df2KFZAs49: \
 -L \
 -O \
 -J

$endpoint = "https://sandbox.textreel.com/v1/videos/1/content";
$api_key = "test_lglFMa20EdjD09df2KFZAs49"; // Find your API keys at https://textreel.com/dashboard/keys

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $endpoint);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, $api_key . ":"); // Authenticate using key

$fh = fopen('path/to/local_video.mp4', "wb");
curl_setopt($ch, CURLOPT_FILE, $fh);

$body = curl_exec($ch);
curl_close($ch);

$conversion = json_decode($body, true);

const fs = require('fs');
const request = require('request');
const apiKey = 'test_lglFMa20EdjD09df2KFZAs49';
const videoID = 1;

let writeStream = fs.createWriteStream('video.mp4');

request.get({
    url: 'https://sandbox.textreel.com/v1/videos/' + videoID + '/content',
    headers: {
        Authorization: 'Basic ' + Buffer.from(apiKey).toString('base64')
    }
}, function(error, response, body) {
    console.log(body);
}).pipe(writeStream);

Resources

Fonts

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.

About

Company

Getting started

Introduction

Authentication

Starting your first conversion

Download the generated video

Reference

Securing API keys

Paging

Response codes

Rate limits

Test and Live Environments

Versioning

Pricing

Endpoints

Get balance

Create a conversion

Retrieve a conversion

Edit a conversion

Cancel a conversion

List conversions

Retrieve a transcript

Edit transcript word

Delete transcript word

Retrieve a video

Retrieve video contents

Resources

Fonts

Resolutions

Languages

Video formats

Templates