Skip to content

Beta: these docs are still being updated. The next full update is on 18 November at 8 PM UTC. Docs in beta. Full update 18 Nov, 8 PM UTC.

Hoody.com

The agent’s audio endpoints turn text into speech and speech into text, both as a single response and as a Server-Sent Events stream, list the available speech models and voices, and offer OpenAI-compatible routes that take the same shapes OpenAI’s audio API uses. All routes are reached through the agent’s URL. Who may call them is set by the agent’s proxy permission rules.

In the Hub, open Bots, select a Bot, and open Settings > Voice. Turn on Choose the models and voice myself to pick its listening model, speaking model and voice.

For each call, X-Hoody-Realm (or ?realm=) names the realm the call is billed to; omitted, the agent’s own realm. The model and voice listings are the same in every realm and are not billed. A malformed realm is 400 invalid_realm, a realm this login does not serve is 404 not_found, and on an agent pinned to one realm any other realm is 400 realm_scope_unsupported.

Speaks input with a speech model and returns the whole audio. A capability the model lacks (a format, instructions, a speed) returns 400 before any paid call. Each call takes one of the client IP’s completion slots.

pcm is 16-bit little-endian mono with no header (X-Hoody-Audio-Rate gives the rate). Omitted response_format: wav when the model gives pcm or wav, else mp3.

NameInTypeRequiredDescription
X-Hoody-RealmheaderstringNoPer-request realm selector: global or a 24-hex realm id (also accepted as ?realm=).
realmquerystringNoIn-query alias of X-Hoody-Realm, read when the header is absent or empty.
NameTypeRequiredDescription
modelstringNoA speech model spec (GET /api/v1/agent/audio/models?capability=tts). Omitted: settings audio.tts_model, else the Hoody AI relay model (hoody-ai/hoody-tts) unless settings audio.relay_default is false; with that off and no model set the call is 422 speech_not_configured.
inputstringYesThe text to speak (at most 4096 characters; less for some models).
voicestringNoA voice of the model (GET /api/v1/agent/audio/voices). Omitted, the model’s first voice.
instructionsstringNoHow to speak (tone, pace), for models that take it; a model that does not is 400.
response_formatstringNoThe audio format. Allowed values: mp3, wav, pcm. Omitted: wav when the model gives pcm or wav, else mp3.
speednumberNoSpeaking speed, for models that take it.
stream_formatstringNoNot read here. Only an empty string is accepted; any other value is 400 bad_request with details.field set to stream_format. For a stream, use POST /api/v1/agent/audio/speech/stream.
Terminal window
curl -X POST "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/audio/speech" \
-H "Content-Type: application/json" \
-d '{
"input": "Your build finished. Two tests failed.",
"response_format": "mp3"
}'

The audio.

Media type: audio/mpeg, audio/wav, or application/octet-stream. Not JSON; the body is the audio bytes. application/octet-stream here is pcm: 16-bit little-endian samples with no header.

Response headers:

  • X-Hoody-Audio-Format: the audio format (wav, mp3, or pcm).
  • X-Hoody-Audio-Rate: The sample rate in Hz. For mp3 it is present only when the model declares a rate.
  • X-Hoody-Audio-Channels: the channel count.
  • X-Hoody-Audio-Op: the id of the speech operation, as in the session usage rows.
<binary audio bytes>

The same call as createSpeech, answered as Server-Sent Events while the audio is made: speech.audio.delta frames (pcm or mp3), then speech.audio.done. Only for models that stream speech.

Nothing is written before the first frame: a failure before it is an ordinary JSON error with its status; after it, an error frame. A : ping comment is sent every 25 s. Every call is billed: do not replay a stream automatically. Each open stream holds one of the client IP’s stream slots.

NameInTypeRequiredDescription
X-Hoody-RealmheaderstringNoPer-request realm selector: global or a 24-hex realm id (also accepted as ?realm=).
realmquerystringNoIn-query alias of X-Hoody-Realm, read when the header is absent or empty.
NameTypeRequiredDescription
modelstringNoA speech model spec (GET /api/v1/agent/audio/models?capability=tts). Omitted: settings audio.tts_model, else the Hoody AI relay model (hoody-ai/hoody-tts) unless settings audio.relay_default is false; with that off and no model set the call is 422 speech_not_configured.
inputstringYesThe text to speak (at most 4096 characters; less for some models).
voicestringNoA voice of the model (GET /api/v1/agent/audio/voices). Omitted, the model’s first voice.
instructionsstringNoHow to speak (tone, pace), for models that take it; a model that does not is 400.
response_formatstringNoThe audio format of the stream: pcm or mp3 (wav is 400). pcm is 16-bit little-endian mono with no header (X-Hoody-Audio-Rate gives the rate). Omitted: pcm, else mp3 when the model gives no pcm.
speednumberNoSpeaking speed, for models that take it.
stream_formatstringNoNot read here because this route always streams. Only an empty string is accepted; any other value is 400 bad_request with details.field set to stream_format.
Terminal window
curl -N -X POST "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/audio/speech/stream" \
-H "Content-Type: application/json" \
-H "Accept: text/event-stream" \
-d '{
"input": "Your build finished. Two tests failed.",
"response_format": "mp3"
}'

SSE stream of the audio.

Media type: text/event-stream. Not JSON; the body is the event stream.

Events:

  • speech.audio.delta: emitted as the model produces audio.
  • speech.audio.done: emitted when the stream ends.
  • : ping: comment sent every 25 s to keep the connection alive.

The route names these events but does not define the fields in their data payloads. The example shows the event sequence only.

event: speech.audio.delta
: ping
event: speech.audio.delta
event: speech.audio.done

Transcribes one uploaded recording. wav and mp3 are decoded by Hoody first; an unreadable file is 400, an audio longer than 600 seconds is 413 audio_too_long. Each call takes one of the client IP’s completion slots.

NameInTypeRequiredDescription
X-Hoody-RealmheaderstringNoPer-request realm selector: global or a 24-hex realm id (also accepted as ?realm=).
realmquerystringNoIn-query alias of X-Hoody-Realm, read when the header is absent or empty.

The body is multipart/form-data with one file part. Every text field is at most 4 KiB.

NameTypeRequiredDescription
filebinaryYesThe audio: wav or mp3, at most 16 MiB and 600 seconds. Some models also take webm, ogg, m4a, or flac; for those the duration is not verified by Hoody and billing uses the provider’s reported duration, or the model’s maximum when none is reported.
modelstringNoA speech model spec (GET /api/v1/agent/audio/models?capability=stt). Omitted: settings audio.stt_model, else the Hoody AI relay model (hoody-ai/hoody-stt) unless settings audio.relay_default is false; with that off and no model set the call is 422 speech_not_configured.
languagestringNoThe spoken language (for example en), when known.
promptstringNoWords to expect (names, terms), for models that take it.
response_formatstringNojson (default, returns {text}), text (plain transcript), or verbose_json (with language, duration, and segments when the model gives them).
Terminal window
curl -X POST "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/audio/transcriptions" \
-F "file=@recording.mp3;type=audio/mpeg" \
-F "model=openrouter/openai/whisper-large-v3"

The transcript.

Media type: application/json (default and verbose_json) or text/plain (when response_format is text).

application/json response fields:

  • text (string, required): the transcript.
  • language (string, verbose_json only): the language heard, when the model says.
  • duration (number, verbose_json only): the audio’s length in seconds, when known.
  • segments (array, verbose_json only): timed segments, when the model gives them.
  • usage (object): what the call used.

text/plain body: the plain transcript.

Response headers:

  • X-Hoody-Audio-Op: the id of the speech operation, as in the session usage rows.
{
"text": "Deploy the staging build."
}

POST /api/v1/agent/audio/transcriptions/stream

Section titled “POST /api/v1/agent/audio/transcriptions/stream”

The same call as createTranscription for wav and mp3, answered as Server-Sent Events: transcript.text.delta frames as the model hears more, then transcript.text.done with the whole transcript. response_format is json.

A stream needs a model whose GET /api/v1/agent/audio/models row has partials true; with a stream, another model is refused 400 bad_request before any paid call. A non-streamed transcription with any speech-to-text model is accepted.

In the examples, replace <stt-model-with-partials> with the id of a GET /api/v1/agent/audio/models row whose available and partials are both true. If no row matches, streaming transcription is not available here.

Nothing is written before the first frame: a failure before it is an ordinary JSON error with its status; after it, an error frame. A : ping comment is sent every 25 s. Every call is billed: do not replay a stream automatically. Each open stream holds one of the client IP’s stream slots.

NameInTypeRequiredDescription
X-Hoody-RealmheaderstringNoPer-request realm selector: global or a 24-hex realm id (also accepted as ?realm=).
realmquerystringNoIn-query alias of X-Hoody-Realm, read when the header is absent or empty.

The body is multipart/form-data with one file part. Every text field is at most 4 KiB.

NameTypeRequiredDescription
filebinaryYesThe audio: wav or mp3, at most 16 MiB and 600 seconds. Some models also take webm, ogg, m4a, or flac on POST /api/v1/agent/audio/transcriptions (the opaque_formats in GET /api/v1/agent/audio/models); for those the duration is not verified by Hoody, and calls are billed on the provider’s reported duration, or the model’s maximum when none is reported.
modelstringNoA speech model spec (GET /api/v1/agent/audio/models?capability=stt). Omitted: settings audio.stt_model, else the Hoody AI relay model (hoody-ai/hoody-stt) unless settings audio.relay_default is false; with that off and no model set the call is 422 speech_not_configured.
languagestringNoThe spoken language (for example en), when known.
promptstringNoWords to expect (names, terms), for models that take it.
response_formatstringNojson (default, returns {text}). The streamed route answers json.
Terminal window
curl -N -X POST "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/audio/transcriptions/stream" \
-F "file=@recording.mp3;type=audio/mpeg" \
-F "model=<stt-model-with-partials>"

SSE stream of the transcript.

Media type: text/event-stream. Not JSON; the body is the event stream.

Events:

  • transcript.text.delta: emitted as the model hears more of the audio.
  • transcript.text.done: emitted when the stream ends.
  • : ping: comment sent every 25 s to keep the connection alive.

The route names these events but does not define the fields in their data payloads. The example shows the event sequence only.

event: transcript.text.delta
: ping
event: transcript.text.delta
event: transcript.text.done

Lists the text-to-speech and speech-to-text models, with their formats, rates, languages, and whether each provider has a key. opaque_formats are inputs Hoody passes on undecoded: their duration is not verified by Hoody; calls are billed on the provider’s reported duration, or the model’s maximum when none is reported.

NameInTypeRequiredDescription
capabilityquerystringNoOnly models with this capability. Allowed values: tts, stt.
X-Hoody-RealmheaderstringNoPer-request realm selector: global or a 24-hex realm id (also accepted as ?realm=).
realmquerystringNoIn-query alias of X-Hoody-Realm, read when the header is absent or empty.
Terminal window
curl -X GET "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/audio/models?capability=tts"

The models.

Media type: application/json

{
"items": [
{
"available": true,
"capabilities": ["tts"],
"formats": ["pcm", "mp3"],
"id": "openrouter/assemblyai/assemblyai-tts-1",
"languages": [],
"max_input_chars": 4096,
"pricing_basis": "per_mchars",
"rates": [24000]
}
]
}

Response fields:

  • items (array, required): the models.
  • items[].id (string, required): the model spec.
  • items[].capabilities (array, required): tts, stt, or both.
  • items[].formats (array): the audio formats it gives or takes.
  • items[].opaque_formats (array): inputs passed on undecoded.
  • items[].partials (boolean): speech-to-text models only, whether the model gives partial transcripts. Only these take POST /api/v1/agent/audio/transcriptions/stream and stream true.
  • items[].rates (array): sample rates in Hz.
  • items[].languages (array): languages; empty when not known.
  • items[].pricing_basis (string): what a call is billed on: per_mchars (per million characters), per_hour (per hour of audio), free, reported (the provider reports the cost), or unknown.
  • items[].max_input_chars (integer): text-to-speech models only, the most characters one call takes.
  • items[].available (boolean, required): whether the model is configured here: its provider has a stored key (for hoody-ai models, the Hoody AI relay is set up here). A call can still answer 503 speech_unavailable when the provider offers no such model here. hoody-ai models list empty formats and rates; they are resolved when a call is made.
  • items[].unavailable_reason (string): only when available is false, why: no_credentials (add a key with PUT /api/v1/agent/providers/{id}/auth/api-key), relay_not_configured, or a reason from the model catalogue.

Lists the voices a text-to-speech model offers. ?model= names one model; omitted, lists the voices of every available one except the Hoody AI relay models, whose voices are listed only when ?model= names one.

NameInTypeRequiredDescription
modelquerystringNoA speech model spec. Omitted, every available text-to-speech model except the Hoody AI relay models.
X-Hoody-RealmheaderstringNoPer-request realm selector: global or a 24-hex realm id (also accepted as ?realm=).
realmquerystringNoIn-query alias of X-Hoody-Realm, read when the header is absent or empty.
Terminal window
curl -X GET "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/audio/voices?model=minimax/speech-2.8-turbo"

The voices.

Media type: application/json

{
"items": [
{
"id": "English_expressive_narrator",
"languages": ["en"],
"model": "minimax/speech-2.8-turbo"
}
]
}

Response fields:

  • items (array, required): the voices.
  • items[].id (string, required): the voice id to pass as voice.
  • items[].languages (array): the languages it speaks; empty when not known.
  • items[].model (string, required): the model it belongs to.

These routes take the same request shapes OpenAI’s audio API uses. They are the OpenAI-compatible mount of the speech engine, not a Bot; errors use OpenAI’s error body.

POST /api/v1/agent/compat/openai/v1/audio/speech

Section titled “POST /api/v1/agent/compat/openai/v1/audio/speech”

createSpeech in OpenAI’s shape: unknown body members are ignored, response_format defaults to mp3, and stream_format sse answers the same Server-Sent Events as POST /api/v1/agent/audio/speech/stream: speech.audio.delta frames, then speech.audio.done.

A stream writes nothing before the first frame: a failure before it is an error body with its status; after it, an error frame {code, message, details?}. A : ping comment is sent every 25 s. Every call is billed: do not replay a stream automatically. Each call takes one of the client IP’s completion slots; an sse answer holds one of its stream slots instead.

NameInTypeRequiredDescription
X-Hoody-RealmheaderstringNoPer-request realm selector: global or a 24-hex realm id (also accepted as ?realm=).
realmquerystringNoIn-query alias of X-Hoody-Realm, read when the header is absent or empty.
NameTypeRequiredDescription
modelstringNoA speech model spec (GET /api/v1/agent/audio/models?capability=tts). Omitted: settings audio.tts_model, else the Hoody AI relay model (hoody-ai/hoody-tts) unless settings audio.relay_default is false; with that off and no model set the call is 422 speech_not_configured.
inputstringYesThe text to speak (at most 4096 characters; less for some models).
voicestringNoA voice of the model (GET /api/v1/agent/audio/voices). Omitted, the model’s first voice.
instructionsstringNoHow to speak (tone, pace), for models that take it; a model that does not is 400.
response_formatstringNoThe audio format. Allowed values: mp3, wav, pcm. Omitted: mp3.
speednumberNoSpeaking speed, for models that take it.
stream_formatstringNoaudio (default, returns audio bytes), sse (an event stream of speech.audio.delta frames, then speech.audio.done), or an empty string, which is treated as audio.
Terminal window
curl -X POST "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/compat/openai/v1/audio/speech" \
-H "Content-Type: application/json" \
-d '{
"model": "minimax/speech-2.8-turbo",
"input": "Your build finished. Two tests failed.",
"voice": "English_expressive_narrator",
"response_format": "mp3"
}'

The audio, or an event stream when stream_format is sse.

Media type: audio/mpeg, audio/wav, application/octet-stream (pcm), or text/event-stream (stream_format sse). Not JSON; the body is the audio bytes or the event stream.

Response headers:

  • X-Hoody-Audio-Format: the audio format (wav, mp3, or pcm).
  • X-Hoody-Audio-Rate: The sample rate in Hz. For mp3 it is present only when the model declares a rate.
  • X-Hoody-Audio-Channels: the channel count.
  • X-Hoody-Audio-Op: the id of the speech operation, as in the session usage rows.
<binary audio bytes>

With stream_format sse, the body is the event stream. Events:

  • speech.audio.delta: a piece of audio. Data: type, audio (base64), format, and rate when the model gives one.
  • speech.audio.done: the audio is complete. Data: type and usage. The route does not define the members of usage. It is always the last event on success.
  • error: the call failed after the first frame. Data: code, message, and details when there are details.
  • : ping: a comment line sent every 25 s; it carries no data.
event: speech.audio.delta
data: {"type":"speech.audio.delta","audio":"SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjYwLjMuMTAw","format":"mp3"}
: ping
event: speech.audio.delta
data: {"type":"speech.audio.delta","audio":"//uQxAAAAAAAAAAAAAAAAAAAAAAASW5mbwAAAA8AAAAC","format":"mp3"}
event: speech.audio.done
data: {"type":"speech.audio.done","usage":{}}

POST /api/v1/agent/compat/openai/v1/audio/transcriptions

Section titled “POST /api/v1/agent/compat/openai/v1/audio/transcriptions”

createTranscription in OpenAI’s shape: unknown fields are ignored, and stream true answers the same Server-Sent Events as POST /api/v1/agent/audio/transcriptions/stream: transcript.text.delta frames, then transcript.text.done.

A stream needs a model whose GET /api/v1/agent/audio/models row has partials true; with stream true, another model is refused 400 bad_request before any paid call. A non-streamed transcription with any speech-to-text model is accepted.

In the streamed example, replace <stt-model-with-partials> with the id of a GET /api/v1/agent/audio/models row whose available and partials are both true. If no row matches, streaming transcription is not available here.

A stream writes nothing before the first frame: a failure before it is an error body with its status; after it, an error frame {code, message, details?}. A : ping comment is sent every 25 s. Every call is billed: do not replay a stream automatically. Each call takes one of the client IP’s completion slots; a stream true answer holds one of its stream slots instead.

NameInTypeRequiredDescription
X-Hoody-RealmheaderstringNoPer-request realm selector: global or a 24-hex realm id (also accepted as ?realm=).
realmquerystringNoIn-query alias of X-Hoody-Realm, read when the header is absent or empty.

The body is multipart/form-data with one file part. Every text field is at most 4 KiB.

NameTypeRequiredDescription
filebinaryYesThe audio: wav or mp3, at most 16 MiB and 600 seconds. Some models also take webm, ogg, m4a, or flac; for those the duration is not verified by Hoody and billing uses the provider’s reported duration, or the model’s maximum when none is reported.
modelstringNoA speech model spec (GET /api/v1/agent/audio/models?capability=stt). Omitted: settings audio.stt_model, else the Hoody AI relay model (hoody-ai/hoody-stt) unless settings audio.relay_default is false; with that off and no model set the call is 422 speech_not_configured.
languagestringNoThe spoken language (for example en), when known.
promptstringNoWords to expect (names, terms), for models that take it.
response_formatstringNojson (default, returns {text}), text, or verbose_json.
streambooleanNotrue: an event stream of transcript.text.delta frames, then transcript.text.done. Only for a model whose GET /api/v1/agent/audio/models row has partials true; a model whose partials value is not true is refused with 400 bad_request before any paid call.
Terminal window
curl -X POST "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/compat/openai/v1/audio/transcriptions" \
-F "file=@recording.mp3;type=audio/mpeg" \
-F "model=openrouter/openai/whisper-large-v3"

For a streamed response:

Terminal window
curl -N -X POST "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/compat/openai/v1/audio/transcriptions" \
-F "file=@recording.mp3;type=audio/mpeg" \
-F "model=<stt-model-with-partials>" \
-F "stream=true"

The transcript, or an event stream when stream is true.

Media type: application/json (default and verbose_json), text/plain (when response_format is text), or text/event-stream (when stream is true).

application/json response fields:

  • text (string, required): the transcript.
  • language (string, verbose_json only): the language heard, when the model says.
  • duration (number, verbose_json only): the audio’s length in seconds, when known.
  • segments (array, verbose_json only): timed segments, when the model gives them.
  • usage (object): what the call used.

text/plain body: the plain transcript.

Response headers:

  • X-Hoody-Audio-Op: the id of the speech operation, as in the session usage rows.
{
"text": "Deploy the staging build."
}

With stream true, the body is the event stream. Events:

  • transcript.text.delta: new transcript text. Data: type and delta.
  • transcript.text.done: the whole transcript. Data: type, text, and usage. The route does not define the members of usage. It is always the last event on success.
  • error: the call failed after the first frame. Data: code, message, and details when there are details.
  • : ping: a comment line sent every 25 s; it carries no data.
event: transcript.text.delta
data: {"type":"transcript.text.delta","delta":"Deploy the"}
: ping
event: transcript.text.delta
data: {"type":"transcript.text.delta","delta":" staging build."}
event: transcript.text.done
data: {"type":"transcript.text.done","text":"Deploy the staging build.","usage":{}}