> This page is for version latest (default).
> For other versions, use one of these documentation indexes:
> - latest (default): https://docs.machanirobotics.dev/latest/llms.txt
> - v2026.01.16-dev: https://docs.machanirobotics.dev/v-2026-01-16-dev/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.machanirobotics.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.machanirobotics.dev/_mcp/server.

# Recognise Audio

POST https://api.machanirobotics.com/v1/conversation/audio/recognise:recogniseAudio
Content-Type: application/json

RecogniseAudio processes the provided audio data to perform speech
 recognition.

 This RPC accepts a RecogniseAudioRequest containing raw audio input and
 returns a RecogniseAudioResponse. The response includes the transcribed
 text, the state of the audio processing session, and any associated
 metadata.

 HTTP Mapping:
   POST "/v1/conversation/audio/recognise"
   The entire request body is forwarded to the service.

Reference: https://docs.machanirobotics.dev/latest/2026-01-16-dev/audio-service/recogniseaudio

## Request

### Body (application/json)

This endpoint expects a RecogniseAudioRequest.

- `audio` (Audio, required) — Audio data and associated metadata for the recognition request.

## Response

### 200

OK

- `audioState` (integer, optional) — The current state of the audio processing session. Indicates relevant status information of the ongoing or completed audio processing.
- `audio` (Audio, optional) — Audio data and associated metadata included in the response.
- `message` (InferenceOutput, optional) — Covnersation Message containing the transcribed text from the audio.

## Errors

### 400 Bad Request Error

Bad Request

- `code` (integer, optional) — The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
- `message` (string, optional) — A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
- `details` (list of GoogleProtobufAny, optional) — A list of messages that carry the error details. There is a common set of message types for APIs to use.

## Types

### Audio

Audio represents an audio resource within the conversation processing system. It encapsulates raw audio data along with its metadata and parameters required for tasks such as transcription, voice activity detection, and further audio analysis.

- `service` (integer, required) — The audio processing service to be used for handling this audio. Examples include Whisper.CPP or Google Speech-to-Text.
- `languageTag` (InferenceLanguage, required) — InferenceLanguage represents the language of the audio data. It specifies the language code (e.g., "en-US") for the audio content. includes which service to use as well.
- `name` (string, optional) — Unique identifier for the audio resource. This field uniquely distinguishes an audio instance within the system.
- `audioData` (string, optional) — Raw audio data represented as a sequence of bytes. Audio may be provided in multiple chunks if needed.
- `uploadPath` (string, optional) — Optional upload path for storing the audio file. This may specify a cloud storage path or other destination for the processed audio.
- `livePipelineFilePath` (string, optional) — File path for the live audio processing pipeline. This is the location where the live audio file (default: /tmp/transcribe.wav) is stored during processing.
- `vadThreshold` (double, optional) — Voice Activity Detection (VAD) threshold. Specifies the minimum energy level for the microphone to consider input as speech, helping to distinguish speech from background noise.
- `sampleRate` (integer, optional) — The sample rate of the audio, expressed in Hertz (Hz). For example, a value of 16000 indicates the audio was sampled 16,000 times per second.
- `wordwiseTimestamps` (list of AudioWordwiseTimestamp, optional) — Optional word-level timestamps for the audio stream. Provides detailed timing (start, end) and confidence information for each recognized word. If multiple words are recognized, consider making this field repeated.

### InferenceOutput

InferenceOutput represents the output of a conversation message. It includes the role of the sender, the content of the message, and the language code.

- `id` (string, optional) — ID is the unique identifier for the conversation message. It is used to track the message within the conversation.
- `role` (integer, optional) — Role defines the role of the sender in the conversation. It uses the InferenceRole enum to indicate if the message comes from the user, assistant, system, or a custom role.
- `text` (InferenceText, optional) — Text message content.
- `image` (InferenceGenerateImageOutput, optional) — Image Generation message content.
- `vision` (InferenceVisionOutput, optional) — Vision message content.
- `options` (InferenceOptions, optional) — Inference Options provides additional settings for the conversation.

### GoogleProtobufAny

Contains an arbitrary serialized message along with a @type that describes the type of the serialized message.

- `@type` (string, optional) — The type of the serialized message.

### InferenceLanguage

InferenceLanguage is the language code for the robot's conversation.

- `countryTag` (integer, required) — The country code for the robot's conversation.
- `languageTag` (integer, required) — The language code for the robot's conversation.
- `inputAudio` (string, optional) — The audio input for the robot's conversation.
- `inputText` (string, optional) — The text input for the robot's conversation.
- `inputSpeech` (string, optional) — The speech input for the robot's conversation.
- `inputNone` (boolean, optional) — The none input for the robot's conversation.
- `outputAudio` (string, optional) — The audio output for the robot's conversation.
- `outputText` (string, optional) — The text output for the robot's conversation.
- `outputSpeech` (string, optional) — The speech output for the robot's conversation.
- `outputNone` (boolean, optional) — The none output for the robot's conversation.

### AudioWordwiseTimestamp

AudioWordWiseTimeStamp represents the timing and confidence details for each recognized word in an audio stream.

- `word` (string, optional) — The recognized word from the audio.
- `start` (string, optional) — The start time (in seconds) when the word begins in the audio stream.
- `end` (string, optional) — The end time (in seconds) when the word finishes in the audio stream.
- `probability` (double, optional) — The confidence probability of the recognized word. A value between 0.0 and 1.0, where 1.0 indicates highest confidence.

### InferenceText

InferenceText is a message that contains text content.

- `content` (list of string, required) — Content is the actual text content of the message.

### InferenceGenerateImageOutput

InferenceGenerateImageOutput is a message that contains the output of the image generation process.

- `id` (string, optional) — ID is the unique identifier for the conversation vision message. It is used to track the message within the conversation.
- `uris` (list of string, optional) — uris is a slice of URLs where images are stored.
- `b64Json` (list of string, optional) — B64JSON is a slice of base64-encoded image data.
- `savedPaths` (list of string, optional) — SavedPaths is a slice of local file paths where images are saved.

### InferenceVisionOutput

Output of vision processing on a InferenceVisionMessage.

- `id` (string, optional) — Matches the `id` of the source InferenceVisionMessage.
- `description` (string, optional) — Human-readable summary of the image contents.
- `objects` (list of VisionObjectMetadata, optional) — List of objects detected in the image (may be empty).

### InferenceOptions

InferenceOptions is a message that contains options for configuring the conversation. It includes the language code for the message and specifies which conversation processing service to use.

- `service` (integer, required) — Specifies which conversation processing service handles this dialogue.
- `model` (string, required) — Specifies the model to be used for processing the conversation.
- `languageTag` (InferenceLanguage, required) — InferenceLanguage specifies the language code for the message.

### VisionObjectMetadata

Describes a single object detected in an image.

- `object` (string, required) — object_name of the detected object, e.g., "person", "dog", "chair".
- `confidence` (double, required) — Confidence score (0.0 to 1.0) for this detection.
- `boundingBox` (VisionBoundingBox, required) — Bounding box around the detected object.

### VisionBoundingBox

Represents a rectangular region in an image.

- `x` (integer, required) — X coordinate of the top-left corner of the box (in pixels).
- `y` (integer, required) — Y coordinate of the top-left corner of the box (in pixels).
- `width` (integer, required) — Width of the box (in pixels).
- `height` (integer, required) — Height of the box (in pixels).

## Examples

**Request**

```json
{
  "audio": {
    "service": 2,
    "languageTag": {
      "countryTag": 840,
      "languageTag": 1033
    }
  }
}
```

**Response**

```json
{
  "audioState": 3,
  "audio": {
    "service": 2,
    "languageTag": {
      "countryTag": 840,
      "languageTag": 1033,
      "inputAudio": "audio/wav",
      "inputText": "Hello, how can I assist you today?",
      "inputSpeech": "Hello, how can I assist you today?",
      "inputNone": false,
      "outputAudio": "audio/wav",
      "outputText": "Hello, how can I assist you today?",
      "outputSpeech": "Hello, how can I assist you today?",
      "outputNone": false
    },
    "name": "meeting_recording_20240615",
    "audioData": "UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAIA+AAACABAAZGF0YQAAAAA=",
    "uploadPath": "s3://machani-audio-uploads/meeting_recording_20240615.wav",
    "livePipelineFilePath": "/tmp/transcribe.wav",
    "vadThreshold": 0.5,
    "sampleRate": 16000,
    "wordwiseTimestamps": [
      {
        "word": "Hello",
        "start": "0.00s",
        "end": "0.50s",
        "probability": 0.98
      },
      {
        "word": "how",
        "start": "0.51s",
        "end": "0.70s",
        "probability": 0.95
      },
      {
        "word": "can",
        "start": "0.71s",
        "end": "0.85s",
        "probability": 0.96
      },
      {
        "word": "I",
        "start": "0.86s",
        "end": "0.90s",
        "probability": 0.97
      },
      {
        "word": "assist",
        "start": "0.91s",
        "end": "1.20s",
        "probability": 0.99
      },
      {
        "word": "you",
        "start": "1.21s",
        "end": "1.40s",
        "probability": 0.98
      },
      {
        "word": "today",
        "start": "1.41s",
        "end": "1.80s",
        "probability": 0.97
      }
    ]
  },
  "message": {
    "id": "msg-20240615-001",
    "role": 2,
    "text": {
      "content": [
        "Hello, how can I assist you today?"
      ]
    },
    "image": {
      "id": "img-20240615-001",
      "uris": [
        "https://cdn.machanirobotics.com/images/assistant_response_20240615.png"
      ],
      "b64Json": [
        "iVBORw0KGgoAAAANSUhEUgAAAAUA"
      ],
      "savedPaths": [
        "/var/data/images/assistant_response_20240615.png"
      ]
    },
    "vision": {
      "id": "vision-20240615-001",
      "description": "Image contains a robot assistant icon and a speech bubble.",
      "objects": [
        {
          "object": "robot",
          "confidence": 0.92,
          "boundingBox": {
            "x": 15,
            "y": 20,
            "width": 100,
            "height": 150
          }
        },
        {
          "object": "speech bubble",
          "confidence": 0.88,
          "boundingBox": {
            "x": 120,
            "y": 30,
            "width": 200,
            "height": 100
          }
        }
      ]
    },
    "options": {
      "service": 2,
      "model": "whisper-large-v2",
      "languageTag": {
        "countryTag": 840,
        "languageTag": 1033,
        "inputAudio": "audio/wav",
        "inputText": "Hello, how can I assist you today?",
        "inputSpeech": "Hello, how can I assist you today?",
        "inputNone": false,
        "outputAudio": "audio/wav",
        "outputText": "Hello, how can I assist you today?",
        "outputSpeech": "Hello, how can I assist you today?",
        "outputNone": false
      }
    }
  }
}
```

**SDK Code**

```python
import requests

url = "https://api.machanirobotics.com/v1/conversation/audio/recognise:recogniseAudio"

payload = { "audio": {
        "service": 2,
        "languageTag": {
            "countryTag": 840,
            "languageTag": 1033
        }
    } }
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.machanirobotics.com/v1/conversation/audio/recognise:recogniseAudio';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"audio":{"service":2,"languageTag":{"countryTag":840,"languageTag":1033}}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.machanirobotics.com/v1/conversation/audio/recognise:recogniseAudio"

	payload := strings.NewReader("{\n  \"audio\": {\n    \"service\": 2,\n    \"languageTag\": {\n      \"countryTag\": 840,\n      \"languageTag\": 1033\n    }\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.machanirobotics.com/v1/conversation/audio/recognise:recogniseAudio")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"audio\": {\n    \"service\": 2,\n    \"languageTag\": {\n      \"countryTag\": 840,\n      \"languageTag\": 1033\n    }\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.machanirobotics.com/v1/conversation/audio/recognise:recogniseAudio")
  .header("Content-Type", "application/json")
  .body("{\n  \"audio\": {\n    \"service\": 2,\n    \"languageTag\": {\n      \"countryTag\": 840,\n      \"languageTag\": 1033\n    }\n  }\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.machanirobotics.com/v1/conversation/audio/recognise:recogniseAudio', [
  'body' => '{
  "audio": {
    "service": 2,
    "languageTag": {
      "countryTag": 840,
      "languageTag": 1033
    }
  }
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.machanirobotics.com/v1/conversation/audio/recognise:recogniseAudio");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"audio\": {\n    \"service\": 2,\n    \"languageTag\": {\n      \"countryTag\": 840,\n      \"languageTag\": 1033\n    }\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = ["audio": [
    "service": 2,
    "languageTag": [
      "countryTag": 840,
      "languageTag": 1033
    ]
  ]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.machanirobotics.com/v1/conversation/audio/recognise:recogniseAudio")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```