v1

This version will be supported until 01.02.2025

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

Speech to text

POST /stt

Submit a speech-to-text transcription request.

Headers

Name	Value
Content-Type	multipart/form-data

Body

Name	Type	Description	Optional
keyId	string	Your API key
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

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('keyId', apiKey);
formData.append('callback_url', 'https://example.com/callback');
formData.append('callback_info_only', true);
formData.append('word_timestamps', true);

axios.post(url, formData)
  .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 = {
    'keyId': api_key,
    'callback_url': 'https://example.com/callback',
    'callback_info_only': True,
    'word_timestamps': True
}

response = requests.post(url, files=files, data=data)
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,
    keyId: api_key,
    callback_url: 'https://example.com/callback',
    callback_info_only: true,
    word_timestamps: true
  }
)

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("keyId", apiKey)
                .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)
                .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,
    'keyId' => $apiKey,
    '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);

$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(apiKey), "keyId");
        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 response = await client.PostAsync($"{apiPrefix}/stt", requestContent);
        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

Body

Name	Type	Description	Optional
keyId	string	Your API key
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 = {
  keyId: apiKey,
  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)
  .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 = {
    'keyId': api_key,
    'text': 'The text you want to convert to speech',
    'speaker': 'f1',
    'callback_url': 'https://example.com/callback',
    'callback_info_only': True
}

response = requests.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 = {
  keyId: api_key,
  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' })
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(apiKey, "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)
                .build();

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

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

        public TTSRequest(String keyId, String text, String speaker, String callback_url, boolean callback_info_only) {
            this.keyId = keyId;
            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(
    'keyId' => $apiKey,
    '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'));

$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
        {
            keyId = apiKey,
            text = "The text you want to convert to speech",
            speaker = "f1",
            callback_url = "https://example.com/callback",
            callback_info_only = true
        };

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

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

        Console.WriteLine(responseBody);
    }
}

Callback status

POST /callback/status

Check the result of a specific callback

Headers

Name	Value
Content-Type	application/json

Body

Name	Type	Description	Optional
keyId	string	Your API key
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`;
const data = {
  keyId: apiKey,
  callbackId: callbackId
};

axios.post(url, data)
  .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'
data = {
    'keyId': api_key,
    'callbackId': callback_id
}

response = requests.post(url, json=data)
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"
data = {
  keyId: api_key,
  callbackId: callback_id
}

response = HTTParty.post(url, body: data.to_json, headers: { 'Content-Type' => 'application/json' })
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");
        String callbackId = "your_callback_id";

        OkHttpClient client = new OkHttpClient();

        // Create a Java object to represent the request body
        StatusRequest requestBody = new StatusRequest(apiKey, callbackId);

        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 + "/callback/status")
                .post(body)
                .build();

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

    private static class StatusRequest {
        private String keyId;
        private String callbackId;

        public StatusRequest(String keyId, String callbackId) {
            this.keyId = keyId;
            this.callbackId = callbackId;
        }
    }
}

PHP

<?php

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

$url = $apiPrefix . '/callback/status';
$data = array(
    'keyId' => $apiKey,
    'callbackId' => $callbackId
);

$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'));

$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");
        string callbackId = "your_callback_id";

        using var client = new HttpClient();

        var requestBody = new
        {
            keyId = apiKey,
            callbackId = callbackId
        };

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

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

        Console.WriteLine(responseBody);
    }
}

List

POST /list

List the operations performed in the API

Headers

Name	Value
Content-Type	application/json

Body

Name	Type	Description	Optional
keyId	string	Your API key
count	number	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; // Set to true or false based on your requirement

const url = `${apiPrefix}/list`;
const data = {
  keyId: apiKey,
  count: 10, // Optional: Number of elements to retrieve
  status: 'success', // Optional: Filter by status of the requests
  type: 'stt-api', // Optional: Filter by type of request
  include_body: includeBody
};

axios.post(url, data)
  .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  # Set to True or False based on your requirement

url = f'{api_prefix}/list'
data = {
    'keyId': api_key,
    'count': 10,  # Optional: Number of elements to retrieve
    'status': 'success',  # Optional: Filter by status of the requests
    'type': 'stt-api',  # Optional: Filter by type of request
    'include_body': include_body
}

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

Ruby

require 'httparty'

api_prefix = ENV['NEURA_API_PREFIX']
api_key = ENV['NEURA_API_KEY']
include_body = true  # Set to true or false based on your requirement

url = "#{api_prefix}/list"
data = {
  keyId: api_key,
  count: 10,  # Optional: Number of elements to retrieve
  status: 'success',  # Optional: Filter by status of the requests
  type: 'stt-api',  # Optional: Filter by type of request
  include_body: include_body
}

response = HTTParty.post(url, body: data.to_json, headers: { 'Content-Type' => 'application/json' })
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");
        boolean includeBody = true; // Set to true or false based on your requirement

        OkHttpClient client = new OkHttpClient();

        // Create a Java object to represent the request body
        ListRequest requestBody = new ListRequest(apiKey, 10, "success", "stt-api", includeBody);

        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 + "/list")
                .post(body)
                .build();

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

    private static class ListRequest {
        private String keyId;
        private Integer count;
        private String status;
        private String type;
        private Boolean include_body;

        public ListRequest(String keyId, Integer count, String status, String type, Boolean include_body) {
            this.keyId = keyId;
            this.count = count;
            this.status = status;
            this.type = type;
            this.include_body = include_body;
        }
    }
}

PHP

<?php

$apiPrefix = getenv('NEURA_API_PREFIX');
$apiKey = getenv('NEURA_API_KEY');
$includeBody = true;  // Set to true or false based on your requirement

$url = $apiPrefix . '/list';
$data = array(
    'keyId' => $apiKey,
    'count' => 10,  // Optional: Number of elements to retrieve
    'status' => 'success',  // Optional: Filter by status of the requests
    'type' => 'stt-api',  // Optional: Filter by type of request
    'include_body' => $includeBody
);

$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'));

$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");
        bool includeBody = true; // Set to true or false based on your requirement

        using var client = new HttpClient();

        var requestBody = new
        {
            keyId = apiKey,
            count = 10, // Optional: Number of elements to retrieve
            status = "success", // Optional: Filter by status of the requests
            type = "stt-api", // Optional: Filter by type of request
            include_body = includeBody
        };

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

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

        Console.WriteLine(responseBody);
    }
}