Declare an Audio Interaction

// // overview the first step in processing any audio file is to declare the interaction when the post post request successfully executes, an http status is returned to indicate the request was successful, along with a json response containing the interactionidentifier sample api response { "interactionidentifier" "2ebaffd6 7a4b 4bcf a169 678af0705779" } it is important you store the interactionidentifier as it will serve as a required parameter for all other elevateai endpoints, enabling you to post post , get get , and/or delete delete information associated with this interaction if an error occurs when requesting to declare the interaction, a standard http response code is retuned to indicate the request was unsuccessful, as well as a json response containing additional details to assist with troubleshooting all interactions successfully declared will count towards your monthly request quota , regardless of file upload status or processing outcome only interactions successfully processed are eligible for billing > once declared, you can confirm the check the processing status of your interaction, as well as tracking impacts to both usage and spend meet echo introducing elevateai echo , our most accurate transcription model yet! echo delivers a significant leap in accuracy , outperforming our previous, cx focused model by 40% and ensuring superior transcription quality across every use case > to use the echo model, add the body parameter model to your post declare and set the value to echo note currently, the echo model does not perform redaction future releases will continue to move echo towards feature parity with elevateai's cx transcription model access feature updates via our release notes contact the elevateai team with product or roadmap questions // // request parameters & code examples details on language support for cx ai features can be found on the cx ai features page { "tab" "examples", "url" "https //api elevateai com/v1/interactions", "name" "declare an interaction for processing (audio)", "method" "post", "request" { "pathparameters" \[], "queryparameters" \[], "headerparameters" \[ { "kind" "required", "name" "x api token", "type" "string", "description" "valid api key associated with your account for authentication and usage tracking" }, { "kind" "required", "name" "content type", "type" "string", "description" "will be 'application/json'" } ], "bodydataparameters" \[ { "kind" "required", "name" "type", "type" "string", "description" "type of interaction to be processed, will be \\"audio\\"", "" "type of interaction to be processed, will be \\"audio\\"" }, { "kind" "optional", "name" "languagetag", "type" "string", "description" "specifies the language to use when processing the audio \nnote for the echo model, use \\"auto\\" to automatically determine the language (over 50 supported) \n\nfor the cx model, the options are \n\nen us for north american english\nen for international english \nes 419 for north american spanish\npt br for brazilian portuguese\nja for japanese\n\nnote omitting this parameter will default to \\"auto\\" for model echo and \\"en us\\" for model cx ", "" "specifies the language to use when processing the audio \nnote for the echo model, use \\"auto\\" to automatically determine the language (over 50 supported) \n\nfor the cx model, the options are \n\nen us for north american english\nen for international english \nes 419 for north american spanish\npt br for brazilian portuguese\nja for japanese\n\nnote omitting this parameter will default to \\"auto\\" for model echo and \\"en us\\" for model cx " }, { "kind" "optional", "name" "vertical", "type" "string", "description" "vertical associated with interaction, will be\n\\"default\\"" }, { "name" "model", "kind" "optional", "type" "string", "description" "defines the transcription model to be used available options are \\"cx\\" and \\"echo\\" default is \\"cx\\" ", "children" \[] }, { "kind" "optional", "name" "audiotranscriptionmode", "type" "string", "description" "effective february 29 2024 with the v1 11 release, all declared interactions will be processed with \\"highaccuracy\\" \n\nnote this previously required parameter has been depricated and is no longer required any value will be ignored ", "" "effective february 29 2024 with the v1 11 release, all declared interactions will be processed with \\"highaccuracy\\" \n\nnote this previously required parameter has been depricated and is no longer required any value will be ignored " }, { "name" "originalfilename", "kind" "optional", "type" "string", "description" "the filename of the original file for this interaction", "children" \[] }, { "name" "externalidentifier", "kind" "optional", "type" "string", "description" "any external identifier that the user would like associated with this interaction", "children" \[] }, { "kind" "optional", "name" "downloaduri", "type" "string", "description" "the url of your audio file\n\nimportant do not include the downloaduri parameter if you wish to upload a local audio file; an empty string will cause the download to fail", "" "the url of your audio file\n\nimportant do not include the downloaduri parameter if you wish to upload a local audio file; an empty string will cause the download to fail" }, { "name" "downloadauth", "kind" "optional", "type" "object", "description" "this optional body parameter can be used when the downloaduri is specified and the download source requires authentication \n\nnote if an expiring token is used for authentication, make sure it has a reasonable amount of time left prior to expiration ", "" "this optional body parameter can be used when the downloaduri is specified and the download source requires authentication \n\nnote if an expiring token is used for authentication, make sure it has a reasonable amount of time left prior to expiration ", "children" \[ { "name" "scheme", "kind" "optional", "type" "string", "description" "specifies the download authentication method to use options are basic and bearer " }, { "name" "value", "kind" "optional", "type" "string", "description" "specifies the token or other authentication string to use when authenticating during the download process " } ], "schema" \[ { "name" "scheme", "kind" "optional", "type" "string", "description" "specifies the download authentication method to use options are basic and bearer " }, { "name" "value", "kind" "optional", "type" "string", "description" "specifies the token or other authentication string to use when authenticating during the download process " } ] }, { "kind" "optional", "name" "includeairesults", "type" "boolean", "description" "effective february 29, 2024 with the v1 11 release, all declared interactions will be processed with includeairesults set to 'true' \n", "" "effective february 29, 2024 with the v1 11 release, all declared interactions will be processed with includeairesults set to 'true' \n" }, { "name" "metadata", "kind" "optional", "type" "string", "description" "json payload containing the metadata for this audio file must only be used if the account has explore enabled if not, specifying this element will cause a response of 400 bad request ", "children" \[] } ], "formdataparameters" \[] }, "results" { "languages" \[ { "id" "ikvdsxifeiysauk1uae r", "code" "{\n \\"interactionidentifier\\" \\"string\\"\n} ", "language" "201", "customlabel" "" }, { "id" "ogn fhk6dtgaeyiv7jai", "code" "{\n \\"string\\"\n}", "language" "400", "customlabel" "" }, { "id" "x6cj5u7giqecvl 2yh9jn", "code" "{\r\n \\"string\\"\r\n}", "language" "401", "customlabel" "" }, { "id" "oa5jretm7 0dbef uj2ue", "code" "{\r\n \\"string\\"\r\n}", "language" "429", "customlabel" "" } ], "selectedlanguageid" "ogn fhk6dtgaeyiv7jai" }, "examples" { "languages" \[ { "id" "fcajf7sxfnehiyfvcyi3r", "code" "curl location request post 'https //api elevateai com/v1/interactions' \\\\\n header 'content type application/json' \\\\\n header 'x api token {your api token}' \\\\\n data raw '{\n \\"type\\" \\"audio\\",\n \\"languagetag\\" \\"auto\\",\n \\"vertical\\" \\"default\\",\n \\"model\\" \\"echo\\",\n \\"audiotranscriptionmode\\" \\"highaccuracy\\",\n \\"originalfilename\\" \\"abc00012 wav\\",\n \\"includeairesults\\" true,\n \\"metadata\\" \\"{your json metada payload}\\"\n}'", "language" "curl", "customlabel" "" }, { "id" "ymci9bw9qn c2fwxj2naz", "code" "var request = require('request');\nvar options = {\n 'method' 'post',\n 'url' 'https //api elevateai com/v1/interactions',\n 'headers' {\n 'content type' 'application/json',\n 'x api token' '{your api token}'\n },\n body json stringify({\n \\"type\\" \\"audio\\",\n \\"languagetag\\" \\"auto\\",\n \\"vertical\\" \\"default\\",\n \\"model\\" \\"echo\\",\n \\"audiotranscriptionmode\\" \\"highaccuracy\\",\n \\"originalfilename\\" \\"abc00012 wav\\",\n \\"includeairesults\\" true,\n \\"metadata\\" \\"{your json metada payload}\\"\n })\n\n};\nrequest(options, function (error, response) {\n if (error) throw new error(error);\n console log(response body);\n});", "language" "nodejs", "customlabel" "" }, { "id" "lgaq 0y77xjz5joa88eed", "code" "var myheaders = new headers();\nmyheaders append(\\"content type\\", \\"application/json\\");\nmyheaders append(\\"x api token\\", \\"{your api token}\\");\n\nvar raw = json stringify({\n \\"type\\" \\"audio\\",\n \\"languagetag\\" \\"auto\\",\n \\"vertical\\" \\"default\\",\n \\"model\\" \\"echo\\",\n \\"audiotranscriptionmode\\" \\"highaccuracy\\",\n \\"originalfilename\\" \\"abc00012 wav\\",\n \\"includeairesults\\" true,\n \\"metadata\\" \\"{your json metada payload}\\"\n});\n\nvar requestoptions = {\n method 'post',\n headers myheaders,\n body raw,\n redirect 'follow'\n};\n\nfetch(\\"https //api elevateai com/v1/interactions\\", requestoptions)\n then(response => response text())\n then(result => console log(result))\n catch(error => console log('error', error));", "language" "javascript", "customlabel" "" }, { "id" "ewmdpghous2hmvx2d4fsg", "code" "import http client\nimport json\n\nconn = http client httpsconnection(\\"api elevateai com\\")\npayload = json dumps({\n \\"type\\" \\"audio\\",\n \\"languagetag\\" \\"auto\\",\n \\"vertical\\" \\"default\\",\n \\"model\\" \\"echo\\",\n \\"audiotranscriptionmode\\" \\"highaccuracy\\",\n \\"originalfilename\\" \\"abc00012 wav\\",\n \\"includeairesults\\" true,\n \\"metadata\\" \\"{your json metada payload}\\"\n})\nheaders = {\n 'content type' 'application/json',\n 'x api token' '{your api token}'\n}\nconn request(\\"post\\", \\"/v1/interactions\\", payload, headers)\nres = conn getresponse()\ndata = res read()\nprint(data decode(\\"utf 8\\"))", "language" "python", "customlabel" "" }, { "id" "ygjx3ttjcuv4suns2cji9", "code" "require \\"uri\\"\nrequire \\"json\\"\nrequire \\"net/http\"\n\nurl = uri(\\"https //api elevateai com/v1/interactions\\")\n\nhttps = net http new(url host, url port)\nhttps use ssl = true\n\nrequest = net http post new(url)\nrequest\[\\"content type\\"] = \\"application/json\\"\nrequest\[\\"x api token\\"] = \\"{your api token}\\"\nrequest body = json dump({\n \\"type\\" \\"audio\\",\n \\"languagetag\\" \\"auto\\",\n \\"vertical\\" \\"default\\",\n \\"model\\" \\"echo\\",\n \\"audiotranscriptionmode\\" \\"highaccuracy\\",\n \\"originalfilename\\" \\"abc00012 wav\\",\n \\"includeairesults\\" true,\n \\"metadata\\" \\"{your json metada payload}\\"\n})\n\nresponse = https request(request)\nputs response read body", "language" "ruby", "customlabel" "" }, { "id" "awyjabfm8e7uv azdwoxd", "code" "var client = new restclient(\\"https //api elevateai com/v1/interactions\\");\nclient timeout = 1;\nvar request = new restrequest(method post);\nrequest addheader(\\"content type\\", \\"application/json\\");\nrequest addheader(\\"x api token\\", \\"{your api token}\\");\nvar body = @\\"{\n\\" + \\"\\\n\\" +\n@\\" \\"\\"type\\"\\" \\"\\"audio\\"\\",\n\\" + \\"\\\n\\" +\n@\\" \\"\\"languagetag\\"\\" \\"\\"auto\\"\\",\n\\" + \\"\\\n\\" +\n@\\" \\"\\"vertical\\"\\" \\"\\"default\\"\\",\n\\" + \\"\\\n\\" +\n@\\" \\"\\"model\\"\\" \\"\\"echo\\"\\",\n\\" + \\"\\\n\\" +\n@\\" \\"\\"audiotranscriptionmode\\"\\" \\"\\"highaccuracy\\"\\",\n\\" + \\"\\\n\\" +\n@\\" \\"\\"originalfilename\\"\\" \\"\\"abc00012 wav\\"\\",\n\\" + \\"\\\n\\" +\n@\\" \\"\\"includeairesults\\"\\" true,\n\\" + \\"\\\n\\" +\n@\\" \\"\\"metadata\\"\\" \\"\\"{your json metada payload}\\"\\"\n\\" + \\"\\\n\\" +\n@\\"}\\";\nrequest addparameter(\\"application/json\\", body, parametertype requestbody);\nirestresponse response = client execute(request);\nconsole writeline(response content);", "language" "csharp", "customlabel" "" }, { "id" "nl5scdbykkbrh1uspbk s", "code" "\<?php\n\n$curl = curl init();\n\ncurl setopt array($curl, array(\n curlopt url => 'https //api elevateai com/v1/interactions',\n curlopt returntransfer => true,\n curlopt encoding => '',\n curlopt maxredirs => 10,\n curlopt timeout => 0,\n curlopt followlocation => true,\n curlopt http version => curl http version 1 1,\n curlopt customrequest => 'post',\n curlopt postfields =>'{\n \\"type\\" \\"audio\\",\n \\"languagetag\\" \\"auto\\",\n \\"vertical\\" \\"default\\",\n \\"model\\" \\"echo\\",\n \\"audiotranscriptionmode\\" \\"highaccuracy\\",\n \\"includeairesults\\" true,\n \\"metadata\\" \\"{your json metada payload}\\"\n}',\n curlopt httpheader => array(\n 'content type application/json',\n 'x api token {your api token}'\n ),\n));\n\n$response = curl exec($curl);\n\ncurl close($curl);\necho $response;\n", "language" "php", "customlabel" "" } ], "selectedlanguageid" "fcajf7sxfnehiyfvcyi3r" }, "description" "", "currentnewparameter" { "label" "body parameter", "value" "bodydataparameters" } } details on transcription and cx ai features – supported by language – can be found on the elevateai overview page // // submitting an audio file for processing download uri providing access to audio files via the downloaduri parameter is highly recommended for faster processing times when using the download uri option , authentication parameters can be included in the declare for source systems which require it see body parameters , above local file if the downloaduri parameter is not included when declaring the interaction, the audio file(s) should be uploaded to the api directly for processing // // submitting metadata metadata must only be submitted with an api token for an account that has elevateai explore enabled any use or submission under other circumstances will cause the declare to fail, and a response of 400 bad request for details on the types and formatting of metadata, please see elevateai's metadata or contact the elevateai support team