Skip to content
Voicebot

Run an STT engine over audio sources

POST
/v1/adapters/stt/{engine_name}/run
curl --request POST \
  --url https://example.com/v1/adapters/stt/example/run \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "requests": [ { "type": "example", "params": { "is_realtime_processing": true, "language": "example", "model": "example" }, "source": { "url": "example" } } ], "is_test": true }'

Synchronously recognizes the supplied sources (signed URL or gs:// path) with the named engine on a live hermes node. Per-item engine failures are reported in the item’s error, not as an HTTP error. Mirrors hermes’ /v1/stt/{engine_name}/run contract.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
engine_name
required
string

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
requests
required
Array<object>
object
type

Item kind; only source is supported.

string
params
object
is_realtime_processing

Stream the source in real time and collect interim results.

boolean
language
string
model
string
source
object
url

Signed URL or gs:// path of the audio to recognize.

string
is_test

Benchmark flag; passed through to the engine run.

boolean
Examplegenerated
{
  "requests": [
    {
      "type": "example",
      "params": {
        "is_realtime_processing": true,
        "language": "example",
        "model": "example"
      },
      "source": {
        "url": "example"
      }
    }
  ],
  "is_test": true
}

Responses

Section titled “Responses”

200

Section titled “200”

Recognition results, one item per request item (node response, passed through).

Media typeapplication/json
object
responses
required
Array<object>
object
type
required
string
source
required
object
id
required
string
error
required

Per-item engine failure; empty on success.

string
transcript
required
string
model
required
string
interim_results
required
Array<object>
object
timestamp
required
string
transcript
required
string
end_offset
required

Int64 as decimal string (protojson emission parity).

string
sent_traffic_offset
required

Int64 as decimal string (protojson emission parity).

string
latency
required

Int64 as decimal string (protojson emission parity).

string
is_final
required
boolean
Examplegenerated
{
  "responses": [
    {
      "type": "example",
      "source": {
        "id": "example",
        "error": "example",
        "transcript": "example",
        "model": "example",
        "interim_results": [
          {
            "timestamp": "example",
            "transcript": "example",
            "end_offset": "example",
            "sent_traffic_offset": "example",
            "latency": "example",
            "is_final": true
          }
        ]
      }
    }
  ]
}

400

Section titled “400”

Node validation failure (missing source, unsupported item type, unknown language) — passed through.

Media typeapplication/json

Mirrors the grpc-gateway error envelope (code = grpc status code).

object
code
required
integer
message
required
string
details
Array<object>
object
Examplegenerated
{
  "code": 1,
  "message": "example",
  "details": [
    {}
  ]
}

401

Section titled “401”

Missing or invalid credentials

Media typeapplication/json
object
error
required

Stable lower_snake_case usecase code (e.g. scenario_not_found)

string
code
required

Registered machine code — generic ERRxxx by status class (ERR001–ERR020 reserved); entity-prefixed codes (SCN1xx) appear only inside validation details; registry in docs/specifications/error-envelope-design.md, append-only, never renumbered

string
message
required
string
data

Structured details, present only where there is structure to carry: validation failures (topic validation, per-entity errors) and delete conflicts (topic conflict, referencing agents)

object
topic
string
errors

Validation errors keyed by entity

object
scenario
Array<object>
object
code

SCN1xx constructor validation code

string
message
string
summary
string
tree_id
string
node_id
string
output_type
string
duplicate_tree_index
string
duplicate_node_index
string
property
string
invalid_value
string
agents

Ids of the agents referencing the resource a delete was rejected for; first 20 — message carries the total count

Array<string>
Examplegenerated
{
  "error": "example",
  "code": "example",
  "message": "example",
  "data": {
    "topic": "example",
    "errors": {
      "scenario": [
        {
          "code": "example",
          "message": "example",
          "summary": "example",
          "tree_id": "example",
          "node_id": "example",
          "output_type": "example",
          "duplicate_tree_index": "example",
          "duplicate_node_index": "example",
          "property": "example",
          "invalid_value": "example"
        }
      ]
    },
    "agents": [
      "example"
    ]
  }
}

403

Section titled “403”

Caller has no access

Media typeapplication/json
object
error
required

Stable lower_snake_case usecase code (e.g. scenario_not_found)

string
code
required

Registered machine code — generic ERRxxx by status class (ERR001–ERR020 reserved); entity-prefixed codes (SCN1xx) appear only inside validation details; registry in docs/specifications/error-envelope-design.md, append-only, never renumbered

string
message
required
string
data

Structured details, present only where there is structure to carry: validation failures (topic validation, per-entity errors) and delete conflicts (topic conflict, referencing agents)

object
topic
string
errors

Validation errors keyed by entity

object
scenario
Array<object>
object
code

SCN1xx constructor validation code

string
message
string
summary
string
tree_id
string
node_id
string
output_type
string
duplicate_tree_index
string
duplicate_node_index
string
property
string
invalid_value
string
agents

Ids of the agents referencing the resource a delete was rejected for; first 20 — message carries the total count

Array<string>
Examplegenerated
{
  "error": "example",
  "code": "example",
  "message": "example",
  "data": {
    "topic": "example",
    "errors": {
      "scenario": [
        {
          "code": "example",
          "message": "example",
          "summary": "example",
          "tree_id": "example",
          "node_id": "example",
          "output_type": "example",
          "duplicate_tree_index": "example",
          "duplicate_node_index": "example",
          "property": "example",
          "invalid_value": "example"
        }
      ]
    },
    "agents": [
      "example"
    ]
  }
}

404

Section titled “404”

No such engine, or the caller’s feature flags withhold it — a gated engine is indistinguishable from an absent one.

Media typeapplication/json
object
error
required

Stable lower_snake_case usecase code (e.g. scenario_not_found)

string
code
required

Registered machine code — generic ERRxxx by status class (ERR001–ERR020 reserved); entity-prefixed codes (SCN1xx) appear only inside validation details; registry in docs/specifications/error-envelope-design.md, append-only, never renumbered

string
message
required
string
data

Structured details, present only where there is structure to carry: validation failures (topic validation, per-entity errors) and delete conflicts (topic conflict, referencing agents)

object
topic
string
errors

Validation errors keyed by entity

object
scenario
Array<object>
object
code

SCN1xx constructor validation code

string
message
string
summary
string
tree_id
string
node_id
string
output_type
string
duplicate_tree_index
string
duplicate_node_index
string
property
string
invalid_value
string
agents

Ids of the agents referencing the resource a delete was rejected for; first 20 — message carries the total count

Array<string>
Examplegenerated
{
  "error": "example",
  "code": "example",
  "message": "example",
  "data": {
    "topic": "example",
    "errors": {
      "scenario": [
        {
          "code": "example",
          "message": "example",
          "summary": "example",
          "tree_id": "example",
          "node_id": "example",
          "output_type": "example",
          "duplicate_tree_index": "example",
          "duplicate_node_index": "example",
          "property": "example",
          "invalid_value": "example"
        }
      ]
    },
    "agents": [
      "example"
    ]
  }
}

500

Section titled “500”

Engine run failed on the node before producing per-item results — passed through.

Media typeapplication/json

Mirrors the grpc-gateway error envelope (code = grpc status code).

object
code
required
integer
message
required
string
details
Array<object>
object
Examplegenerated
{
  "code": 1,
  "message": "example",
  "details": [
    {}
  ]
}

502

Section titled “502”

The selected hermes node failed to serve the recognition.

Media typeapplication/json
object
error
required

Stable lower_snake_case usecase code (e.g. scenario_not_found)

string
code
required

Registered machine code — generic ERRxxx by status class (ERR001–ERR020 reserved); entity-prefixed codes (SCN1xx) appear only inside validation details; registry in docs/specifications/error-envelope-design.md, append-only, never renumbered

string
message
required
string
data

Structured details, present only where there is structure to carry: validation failures (topic validation, per-entity errors) and delete conflicts (topic conflict, referencing agents)

object
topic
string
errors

Validation errors keyed by entity

object
scenario
Array<object>
object
code

SCN1xx constructor validation code

string
message
string
summary
string
tree_id
string
node_id
string
output_type
string
duplicate_tree_index
string
duplicate_node_index
string
property
string
invalid_value
string
agents

Ids of the agents referencing the resource a delete was rejected for; first 20 — message carries the total count

Array<string>
Examplegenerated
{
  "error": "example",
  "code": "example",
  "message": "example",
  "data": {
    "topic": "example",
    "errors": {
      "scenario": [
        {
          "code": "example",
          "message": "example",
          "summary": "example",
          "tree_id": "example",
          "node_id": "example",
          "output_type": "example",
          "duplicate_tree_index": "example",
          "duplicate_node_index": "example",
          "property": "example",
          "invalid_value": "example"
        }
      ]
    },
    "agents": [
      "example"
    ]
  }
}

503

Section titled “503”

No ready hermes node is available.

Media typeapplication/json
object
error
required

Stable lower_snake_case usecase code (e.g. scenario_not_found)

string
code
required

Registered machine code — generic ERRxxx by status class (ERR001–ERR020 reserved); entity-prefixed codes (SCN1xx) appear only inside validation details; registry in docs/specifications/error-envelope-design.md, append-only, never renumbered

string
message
required
string
data

Structured details, present only where there is structure to carry: validation failures (topic validation, per-entity errors) and delete conflicts (topic conflict, referencing agents)

object
topic
string
errors

Validation errors keyed by entity

object
scenario
Array<object>
object
code

SCN1xx constructor validation code

string
message
string
summary
string
tree_id
string
node_id
string
output_type
string
duplicate_tree_index
string
duplicate_node_index
string
property
string
invalid_value
string
agents

Ids of the agents referencing the resource a delete was rejected for; first 20 — message carries the total count

Array<string>
Examplegenerated
{
  "error": "example",
  "code": "example",
  "message": "example",
  "data": {
    "topic": "example",
    "errors": {
      "scenario": [
        {
          "code": "example",
          "message": "example",
          "summary": "example",
          "tree_id": "example",
          "node_id": "example",
          "output_type": "example",
          "duplicate_tree_index": "example",
          "duplicate_node_index": "example",
          "property": "example",
          "invalid_value": "example"
        }
      ]
    },
    "agents": [
      "example"
    ]
  }
}