Latest (v1.5.2)

Changelog

• 06.06.2025 - 1.5.2 [STT] Added AI summary of stt transcriptions

• 29.12.2024 - 1.5.1 [STT] Added known_speakers to assign a speaker name based on embedding similarity from diarization pipeline, and added possible_hallucination boolean to indicate if the model might be hallucinating

Postman collection

3KB

neura.al.json

API prefix: https://neura.al/api/v1.5

Speech to text

POST /stt

Submit a speech-to-text transcription request.

Headers

Name	Value
Content-Type	multipart/form-data
Authentication	Bearer your_api_key

Body

Name	Type	Description	Optional
audio	file	The content of the audio to be transcribed
callback_url	url	URL to be called once status changes
callback_info_only	boolean	Weather to return just the callbackID and status to callback_url
word_timestamps	boolean	Weather to include timestamps for each word
known_speaker_*	file	For each speaker you know, provide
summary	boolean	Weather to summarise the transcription content

Response

200

{
    "callbackID": "ID of the callback" 
}

400

{
    "url": "/api/v1/stt",
    "statusMessage": "",
    "message": "Error message",
    "stack": ""
}

Example

JavaScript

const axios = require('axios');
const fs = require('fs');

const apiPrefix = process.env.NEURA_API_PREFIX;
const apiKey = process.env.NEURA_API_KEY;

const url = `${apiPrefix}/stt`;
const audioFile = fs.createReadStream('path/to/audio/file');

const formData = new FormData();
formData.append('audio', audioFile);
formData.append('callback_url', 'https://example.com/callback');
formData.append('callback_info_only', true);
formData.append('word_timestamps', true);

axios.post(url, formData, {
  headers: {
    'Authorization': `Bearer ${apiKey}`
  }
})
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.error(error);
  });

Python

import os
import requests

api_prefix = os.environ['NEURA_API_PREFIX']
api_key = os.environ['NEURA_API_KEY']  

url = f'{api_prefix}/stt'
files = {'audio': open('path/to/audio/file', 'rb')}
data = {
    'callback_url': 'https://example.com/callback',
    'callback_info_only': True,
    'word_timestamps': True
}

headers = {
    'Authorization': f'Bearer {api_key}'
}

response = requests.post(url, files=files, data=data, headers=headers)
print(response.json())

Ruby

require 'httparty'

api_prefix = ENV['NEURA_API_PREFIX']
api_key = ENV['NEURA_API_KEY']

url = "#{api_prefix}/stt"
audio_file = File.open('path/to/audio/file', 'rb')

response = HTTParty.post(url,
  body: {
    audio: audio_file,
    callback_url: 'https://example.com/callback',
    callback_info_only: true,
    word_timestamps: true
  },
  headers: {
    'Authorization' => "Bearer #{api_key}"
  }
)

puts response.body

Java

import okhttp3.*;

import java.io.File;

public class Main {
    public static void main(String[] args) throws Exception {
        String apiPrefix = System.getenv("NEURA_API_PREFIX");
        String apiKey = System.getenv("NEURA_API_KEY");

        OkHttpClient client = new OkHttpClient();

        RequestBody requestBody = new MultipartBody.Builder()
                .setType(MultipartBody.FORM)
                .addFormDataPart("audio", "audio.wav",
                        RequestBody.create(new File("path/to/audio/file"), MediaType.parse("audio/wav")))
                .addFormDataPart("callback_url", "https://example.com/callback")
                .addFormDataPart("callback_info_only", "true")
                .addFormDataPart("word_timestamps", "true")
                .build();

        Request request = new Request.Builder()
                .url(apiPrefix + "/stt")
                .post(requestBody)
                .addHeader("Authorization", "Bearer " + apiKey) 
                .build();

        try (Response response = client.newCall(request).execute()) {
            System.out.println(response.body().string());
        }
    }
}

PHP

<?php

$apiPrefix = getenv('NEURA_API_PREFIX');
$apiKey = getenv('NEURA_API_KEY');

$url = $apiPrefix . '/stt';
$audioFile = new CURLFile('path/to/audio/file', 'audio/wav', 'audio.wav');

$data = [
    'audio' => $audioFile,
    'callback_url' => 'https://example.com/callback',
    'callback_info_only' => true,
    'word_timestamps' => true
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $apiKey
]);

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

echo $response;
?>

C#

using System;
using System.IO;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        string apiPrefix = Environment.GetEnvironmentVariable("NEURA_API_PREFIX");
        string apiKey = Environment.GetEnvironmentVariable("NEURA_API_KEY");

        using var client = new HttpClient();

        var requestContent = new MultipartFormDataContent();
        requestContent.Add(new StreamContent(File.OpenRead("path/to/audio/file")), "audio", "audio.wav");
        requestContent.Add(new StringContent("https://example.com/callback"), "callback_url");
        requestContent.Add(new StringContent("true"), "callback_info_only");
        requestContent.Add(new StringContent("true"), "word_timestamps");

        var request = new HttpRequestMessage
        {
            Method = HttpMethod.Post,
            RequestUri = new Uri($"{apiPrefix}/stt"),
            Headers = {
                { "Authorization", $"Bearer {apiKey}" }
            },
            Content = requestContent
        };

        var response = await client.SendAsync(request);
        string responseBody = await response.Content.ReadAsStringAsync();

        Console.WriteLine(responseBody);
    }
}

Text to speech

POST /tts

Submit a text-to-speech request

Headers

Name	Value
Content-Type	application/json
Authentication	Bearer your_api_key

Body

Name	Type	Description	Optional
text	string	The text you want to convert to speech
speaker	ENUM ['f1', f2', 'f3', 'f4', 'm1', 'm2', 'm3', 'm4']	The speaker you want to use
callback_url	url	URL to be called once status changes
callback_info_only	boolean	Weather to return just the callbackID and status to callback_url

Response

200

{
    "callbackID": "ID of the callback" 
}

400

{
    "url": "/api/v1/tts",
    "statusMessage": "",
    "message": "Error message",
    "stack": ""
}

Example

JavaScript

const axios = require('axios');

const apiPrefix = process.env.NEURA_API_PREFIX;
const apiKey = process.env.NEURA_API_KEY;

const url = `${apiPrefix}/tts`;
const data = {
  text: 'The text you want to convert to speech',
  speaker: 'f1',
  callback_url: 'https://example.com/callback',
  callback_info_only: true
};

axios.post(url, data, {
  headers: {
    'Authorization': `Bearer ${apiKey}`
  }
})
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.error(error);
  });

Python

import os
import requests

api_prefix = os.environ['NEURA_API_PREFIX']
api_key = os.environ['NEURA_API_KEY']  

url = f'{api_prefix}/tts'
data = {
    'text': 'The text you want to convert to speech',
    'speaker': 'f1',
    'callback_url': 'https://example.com/callback',
    'callback_info_only': True
}

session = requests.Session()
session.headers.update({'Authorization': f'Bearer {api_key}'})

response = session.post(url, json=data)
print(response.json())

Ruby

require 'httparty'

api_prefix = ENV['NEURA_API_PREFIX']
api_key = ENV['NEURA_API_KEY']

url = "#{api_prefix}/tts"
data = {
  text: 'The text you want to convert to speech',
  speaker: 'f1',
  callback_url: 'https://example.com/callback',
  callback_info_only: true
}

response = HTTParty.post(
  url,
  body: data.to_json,
  headers: {
    'Content-Type' => 'application/json',
    'Authorization' => "Bearer #{api_key}"
  }
)
puts response.body

Java

import com.google.gson.Gson;
import okhttp3.*;

public class Main {
    public static void main(String[] args) throws Exception {
        String apiPrefix = System.getenv("NEURA_API_PREFIX");
        String apiKey = System.getenv("NEURA_API_KEY");

        OkHttpClient client = new OkHttpClient();

        // Create a Java object to represent the request body
        TTSRequest requestBody = new TTSRequest("The text you want to convert to speech", "f1", "https://example.com/callback", true);

        Gson gson = new Gson();
        String json = gson.toJson(requestBody);

        RequestBody body = RequestBody.create(MediaType.parse("application/json"), json);

        Request request = new Request.Builder()
                .url(apiPrefix + "/tts")
                .post(body)
                .addHeader("Authorization", "Bearer " + apiKey) 
                .build();

        try (Response response = client.newCall(request).execute()) {
            System.out.println(response.body().string());
        }
    }

    private static class TTSRequest {
        private String text;
        private String speaker;
        private String callback_url;
        private boolean callback_info_only;

        public TTSRequest(String text, String speaker, String callback_url, boolean callback_info_only) {
            this.text = text;
            this.speaker = speaker;
            this.callback_url = callback_url;
            this.callback_info_only = callback_info_only;
        }
    }
}

PHP

<?php

$apiPrefix = getenv('NEURA_API_PREFIX');
$apiKey = getenv('NEURA_API_KEY');

$url = $apiPrefix . '/tts';
$data = array(
    'text' => 'The text you want to convert to speech',
    'speaker' => 'f1',
    'callback_url' => 'https://example.com/callback',
    'callback_info_only' => true
);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-Type: application/json',
    'Authorization: Bearer ' . $apiKey // Pass API key as Bearer token
));

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

echo $response;
?>

C#

using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        string apiPrefix = Environment.GetEnvironmentVariable("NEURA_API_PREFIX");
        string apiKey = Environment.GetEnvironmentVariable("NEURA_API_KEY");

        using var client = new HttpClient();

        var requestBody = new
        {
            text = "The text you want to convert to speech",
            speaker = "f1",
            callback_url = "https://example.com/callback",
            callback_info_only = true
        };

        var json = JsonSerializer.Serialize(requestBody);
        var content = new StringContent(json, Encoding.UTF8, "application/json");

 
        client.DefaultRequestHeaders.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", apiKey);

        var response = await client.PostAsync($"{apiPrefix}/tts", content);
        string responseBody = await response.Content.ReadAsStringAsync();

        Console.WriteLine(responseBody);
    }
}

Callback status

GET /callback/status

Check the result of a specific callback

Headers

Name	Value
Content-Type	application/json
Authentication	Bearer your_api_key

Parameters

Name	Type	Description	Optional
callbackId	string	Callback ID to be checked
result_as	ENUM ["json", "txt","srt", "srt_words"]	How to format the response for Speech to text: “json” → returns a json element “txt” → returns a txt element “srt” → returns a srt compatible file with segments “srt_words” → returns a srt compatible file with each word as a segment

Response

200

{
    "status": ENUM["done","processing","failed"],
    "data": "response if status is done"
}

400

{
    "url": "/api/v1/callback/status",
    "statusMessage": "",
    "message": "Error message",
    "stack": ""
}

Example

JavaScript

const axios = require('axios');

const apiPrefix = process.env.NEURA_API_PREFIX;
const apiKey = process.env.NEURA_API_KEY;
const callbackId = 'your_callback_id';

const url = `${apiPrefix}/callback/status?callbackId=${callbackId}`;

axios.get(url, {
  headers: {
    Authorization: `Bearer ${apiKey}`
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Python

import os
import requests

api_prefix = os.environ['NEURA_API_PREFIX']
api_key = os.environ['NEURA_API_KEY']
callback_id = 'your_callback_id'

url = f'{api_prefix}/callback/status?callbackId={callback_id}'

headers = {
    'Authorization': f'Bearer {api_key}'
}

response = requests.get(url, headers=headers)
print(response.json())

Ruby

require 'httparty'

api_prefix = ENV['NEURA_API_PREFIX']
api_key = ENV['NEURA_API_KEY']
callback_id = 'your_callback_id'

url = "#{api_prefix}/callback/status?callbackId=#{callback_id}"

response = HTTParty.get(url, headers: { 'Authorization' => "Bearer #{api_key}" })
puts response.body

Java

import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;

import java.io.IOException;

public class Main {
    public static void main(String[] args) throws IOException {
        String apiPrefix = System.getenv("NEURA_API_PREFIX");
        String apiKey = System.getenv("NEURA_API_KEY");
        String callbackId = "your_callback_id";

        OkHttpClient client = new OkHttpClient();

        Request request = new Request.Builder()
                .url(apiPrefix + "/callback/status?callbackId=" + callbackId)
                .header("Authorization", "Bearer " + apiKey)
                .build();

        try (Response response = client.newCall(request).execute()) {
            System.out.println(response.body().string());
        }
    }
}

PHP

<?php

$apiPrefix = getenv('NEURA_API_PREFIX');
$apiKey = getenv('NEURA_API_KEY');
$callbackId = 'your_callback_id';

$url = $apiPrefix . '/callback/status?callbackId=' . $callbackId;

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Authorization: Bearer ' . $apiKey));

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

echo $response;
?>

C#

using System;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        string apiPrefix = Environment.GetEnvironmentVariable("NEURA_API_PREFIX");
        string apiKey = Environment.GetEnvironmentVariable("NEURA_API_KEY");
        string callbackId = "your_callback_id";

        using var client = new HttpClient();

        var response = await client.GetAsync($"{apiPrefix}/callback/status?callbackId={callbackId}");
        string responseBody = await response.Content.ReadAsStringAsync();

        Console.WriteLine(responseBody);
    }
}

List

GET /list

List the operations performed in the API

Headers

Name	Value
Content-Type	application/json

Parameters

Name	Type	Description	Optional
keyId	string	Your API key
count	integer	Number of elements to retrieve
status	ENUM ["processing", "success", "failed"]	Filter by status of the requests
type	ENUM ["stt-api", "tts-api"]	Filter by type of request
include_body	boolean	Weather to return the response (Default = false)

Response

200 include_body=false

[
    {
        "id": "callbackId",
        "type": "tts-api",
        "status": 1
    },
    ... 
    {
        "id": "callbackId",
        "type": "stt-api",
        "status": 0
    },
]

200 include_body=true

[
    {
        "id": "callbackId",
        "type": "tts-api",
        "status": 1,
        "content": {
            "inputs": {
                "text": "The text requested",
                "speaker": "The speaker selected"
            },
            "result": "The url of the generated audio"
        }
    },
    ... 
]

400

{
    "url": "/api/v1/list",
    "statusMessage": "",
    "message": "Error message",
    "stack": ""
}

Example

JavaScript

const axios = require('axios');

const apiPrefix = process.env.NEURA_API_PREFIX;
const apiKey = process.env.NEURA_API_KEY;
const includeBody = true;
const count = 10;
const status = 'success';
const type = 'stt-api';

const url = `${apiPrefix}/list?keyId=${apiKey}&count=${count}&status=${status}&type=${type}&include_body=${includeBody}`;

axios.get(url)
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.error(error);
  });

Python

import os
import requests

api_prefix = os.environ['NEURA_API_PREFIX']
api_key = os.environ['NEURA_API_KEY']
include_body = True 
count = 10 
status = 'success'  
request_type = 'stt-api' 

url = f'{api_prefix}/list?keyId={api_key}&count={count}&status={status}&type={request_type}&include_body={include_body}'

response = requests.get(url)
print(response.json())

Ruby

require 'httparty'

api_prefix = ENV['NEURA_API_PREFIX']
api_key = ENV['NEURA_API_KEY']
include_body = true 

url = "#{api_prefix}/list?keyId=#{api_key}&count=10&status=success&type=stt-api&include_body=#{include_body}"

response = HTTParty.get(url)
puts response.body

Java

import okhttp3.*;

public class Main {
    public static void main(String[] args) throws Exception {
        String apiPrefix = System.getenv("NEURA_API_PREFIX");
        String apiKey = System.getenv("NEURA_API_KEY");
        boolean includeBody = true; 
        int count = 10;
        String status = "success"; 
        String type = "stt-api";

        HttpUrl.Builder urlBuilder = HttpUrl.parse(apiPrefix + "/list").newBuilder();
        urlBuilder.addQueryParameter("keyId", apiKey);
        urlBuilder.addQueryParameter("count", String.valueOf(count));
        urlBuilder.addQueryParameter("status", status);
        urlBuilder.addQueryParameter("type", type);
        urlBuilder.addQueryParameter("include_body", String.valueOf(includeBody));

        String url = urlBuilder.build().toString();

        OkHttpClient client = new OkHttpClient();

        Request request = new Request.Builder()
                .url(url)
                .get()
                .build();

        try (Response response = client.newCall(request).execute()) {
            System.out.println(response.body().string());
        }
    }
}

PHP

$apiPrefix = getenv('NEURA_API_PREFIX');
$apiKey = getenv('NEURA_API_KEY');
$includeBody = true; 
$count = 10; 
$status = 'success';  
$type = 'stt-api';  

$url = $apiPrefix . '/list?keyId=' . urlencode($apiKey) . '&count=' . $count . '&status=' . urlencode($status) . '&type=' . urlencode($type) . '&include_body=' . ($includeBody ? 'true' : 'false');

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

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

echo $response;

C#

using System;
using System.Net.Http;
using System.Text.Json;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        string apiPrefix = Environment.GetEnvironmentVariable("NEURA_API_PREFIX");
        string apiKey = Environment.GetEnvironmentVariable("NEURA_API_KEY");
        bool includeBody = true; 
        int count = 10;
        string status = "success"; 
        string type = "stt-api"; 

        using var client = new HttpClient();
        string url = $"{apiPrefix}/list?keyId={apiKey}&count={count}&status={status}&type={type}&include_body={includeBody}";
        
        var response = await client.GetAsync(url);
        string responseBody = await response.Content.ReadAsStringAsync();

        Console.WriteLine(responseBody);
    }
}

User quota

GET /user/quota

Returns the quota left in the account

Headers

Name	Value
Content-Type	application/json
Authentication	Bearer your_api_key

Response

200

[
    {
        "stt": number_of_seconds_left,
        "tts": number_of_words_left
    },
]

400

{
    "url": "/api/v1/user/quota",
    "statusMessage": "",
    "message": "Error message",
    "stack": ""
}

Example

JavaScript

const axios = require('axios');

const apiPrefix = process.env.NEURA_API_PREFIX;
const apiKey = process.env.NEURA_API_KEY;

const url = `${apiPrefix}/user/quota`;

axios.get(url)
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.error(error);
  });

Python

import os
import requests

api_prefix = os.environ['NEURA_API_PREFIX']
api_key = os.environ['NEURA_API_KEY']

url = f'{api_prefix}/user/quota'

response = requests.get(url)
print(response.json())

Ruby

require 'httparty'

api_prefix = ENV['NEURA_API_PREFIX']
api_key = ENV['NEURA_API_KEY']

url = "#{api_prefix}/user/quota"

response = HTTParty.get(url)
puts response.body

Java

import okhttp3.*;

public class Main {
    public static void main(String[] args) throws Exception {
        String apiPrefix = System.getenv("NEURA_API_PREFIX");
        String apiKey = System.getenv("NEURA_API_KEY");

        HttpUrl.Builder urlBuilder = HttpUrl.parse(apiPrefix + "/user/quota").newBuilder();
        String url = urlBuilder.build().toString();

        OkHttpClient client = new OkHttpClient();

        Request request = new Request.Builder()
                .url(url)
                .get()
                .build();

        try (Response response = client.newCall(request).execute()) {
            System.out.println(response.body().string());
        }
    }
}

PHP

$apiPrefix = getenv('NEURA_API_PREFIX');
$apiKey = getenv('NEURA_API_KEY');

$url = $apiPrefix . '/user/quota';

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

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

echo $response;

C#

using System;
using System.Net.Http;
using System.Text.Json;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        string apiPrefix = Environment.GetEnvironmentVariable("NEURA_API_PREFIX");
        string apiKey = Environment.GetEnvironmentVariable("NEURA_API_KEY");

        using var client = new HttpClient();
        string url = $"{apiPrefix}/user/quota";
        
        var response = await client.GetAsync(url);
        string responseBody = await response.Content.ReadAsStringAsync();

        Console.WriteLine(responseBody);
    }
}