Agent: Audio
Section titled “Agent: Audio”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.
Speech
Section titled “Speech”POST /api/v1/agent/audio/speech
Section titled “POST /api/v1/agent/audio/speech”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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
X-Hoody-Realm | header | string | No | Per-request realm selector: global or a 24-hex realm id (also accepted as ?realm=). |
realm | query | string | No | In-query alias of X-Hoody-Realm, read when the header is absent or empty. |
Request body
Section titled “Request body”| Name | Type | Required | Description |
|---|---|---|---|
model | string | No | A 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. |
input | string | Yes | The text to speak (at most 4096 characters; less for some models). |
voice | string | No | A voice of the model (GET /api/v1/agent/audio/voices). Omitted, the model’s first voice. |
instructions | string | No | How to speak (tone, pace), for models that take it; a model that does not is 400. |
response_format | string | No | The audio format. Allowed values: mp3, wav, pcm. Omitted: wav when the model gives pcm or wav, else mp3. |
speed | number | No | Speaking speed, for models that take it. |
stream_format | string | No | Not 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. |
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" }'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
await client.agent.audio.createSpeech({ input: 'Your build finished. Two tests failed.', response_format: 'mp3'});Responses
Section titled “Responses”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, orpcm).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>Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters, or the model lacks the capability (a speech model for a transcription, or the reverse). | Correct the request body or query parameters, or pick a model with the capability (GET /api/v1/agent/audio/models?capability=tts or stt). |
realm_scope_unsupported | Realm scope unsupported | A per-request scope header this route does not take, or, on an agent pinned to one realm, a different realm. | Omit the header, or name the realm the agent is pinned to. |
invalid_realm | Invalid realm selector | The realm selector is malformed (not ""/"global"/a 24-hex id). | Pass a valid realm selector. |
input_too_long | Input too long | The text is longer than the model takes (at most 4096 characters, less for some models). details.limit is the bound the text broke and details.unit its unit (characters or bytes); either is absent when the provider refused without saying. | Split the text into calls of at most details.limit characters (or bytes). |
Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only.
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
The requested resource does not exist.
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
The requested realm is blocked or corrupt; the request fails closed before dispatch.
Media type: application/json
{ "code": "realm_blocked", "message": "realm is blocked"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
realm_blocked | Realm blocked | The requested realm is blocked or corrupt; the request fails closed before dispatch. | Select a valid, reachable realm. |
The JSON body is larger than 64 KiB.
Media type: application/json
{ "code": "payload_too_large", "message": "request body exceeds the configured size limit"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
payload_too_large | Payload too large | The JSON body is larger than 64 KiB. | Send a body of at most 64 KiB; split a long text into several calls. |
The speech model is not available, not configured, or the provider refused the input.
Media type: application/json
{ "code": "speech_not_configured", "message": "no speech model is set"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
model_unavailable | Model unavailable | The speech model is not known or not offered. | Pick a model from GET /api/v1/agent/audio/models. |
speech_not_configured | Speech not configured | No speech model is set for this capability and none was named. | Name a model, or set a default speech model. |
provider_refused | Provider refused | The speech provider refused the input (its content rules or its own limits). | Change the input; details.reason says why when the provider said. |
The per-client request rate limit was exceeded, or the speech budget is spent.
Media type: application/json
{ "code": "speech_quota_exceeded", "message": "the speech budget is spent"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded; the gateway throttled the request before dispatch. | Honor the Retry-After header and retry; reduce the request rate. |
speech_quota_exceeded | Speech quota exceeded | The speech budget of this realm, Bot, or agent is spent for now. | Honor Retry-After, or raise the budget. |
Response headers:
Retry-After: seconds to wait before retrying.
An unexpected error occurred while handling the request.
Media type: application/json
{ "code": "internal_error", "message": "internal server error"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry; if persistent, inspect the daemon logs. |
The speech provider refused the stored key, or failed, or answered something unusable.
Media type: application/json
{ "code": "provider_error", "message": "the speech provider failed", "details": { "diag_id": "3f9a1c0b7e2d4a65" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
provider_auth | Provider key refused | The speech provider refused the stored key. | Check the provider’s key (PUT /api/v1/agent/providers/{id}/auth/api-key). |
provider_error | Provider error | The speech provider failed, or answered something unusable. details.diag_id names the failure in the agent’s log. | Retry; if it persists, try another model. |
Speech is unavailable, busy, or the call could not be recorded.
Media type: application/json
{ "code": "speech_busy", "message": "speech is busy"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit). | Honor Retry-After and retry. |
restriction_unknown | Login restriction unknown | The agent cannot read yet which realms its login may serve, so it refuses realm-scoped requests until it can. Nothing was read or changed. | Retry after the restriction is readable. |
speech_unavailable | Speech unavailable | Speech is not available here: the provider of the selected speech model has no API key (details.reason no_credentials), or the Hoody AI voice relay cannot serve it (a details.reason starting relay_, for example not set up or not reachable). | Set a provider key for a speech model. |
speech_busy | Speech busy | Too many speech calls are running on the agent. | Honor Retry-After and retry. |
admission_write_failed | Not recorded | The speech call could not be recorded for usage, so it was not made; nothing was billed. | Honor Retry-After and retry. |
Response headers:
Retry-After: seconds to wait before retrying (busy, or the call cap).
The speech provider did not answer in time.
Media type: application/json
{ "code": "provider_timeout", "message": "the speech provider did not answer in time"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
provider_timeout | Provider timeout | The speech provider did not answer in time. | Retry, or send a shorter input. |
POST /api/v1/agent/audio/speech/stream
Section titled “POST /api/v1/agent/audio/speech/stream”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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
X-Hoody-Realm | header | string | No | Per-request realm selector: global or a 24-hex realm id (also accepted as ?realm=). |
realm | query | string | No | In-query alias of X-Hoody-Realm, read when the header is absent or empty. |
Request body
Section titled “Request body”| Name | Type | Required | Description |
|---|---|---|---|
model | string | No | A 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. |
input | string | Yes | The text to speak (at most 4096 characters; less for some models). |
voice | string | No | A voice of the model (GET /api/v1/agent/audio/voices). Omitted, the model’s first voice. |
instructions | string | No | How to speak (tone, pace), for models that take it; a model that does not is 400. |
response_format | string | No | The 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. |
speed | number | No | Speaking speed, for models that take it. |
stream_format | string | No | Not 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. |
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" }'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
await client.agent.audio.createSpeech({ input: 'Your build finished. Two tests failed.', response_format: 'mp3'}, { stream: true });Responses
Section titled “Responses”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.doneMedia type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters, or the model lacks the capability (a speech model for a transcription, or the reverse). | Correct the request body or query parameters, or pick a model with the capability (GET /api/v1/agent/audio/models?capability=tts or stt). |
realm_scope_unsupported | Realm scope unsupported | A per-request scope header this route does not take, or, on an agent pinned to one realm, a different realm. | Omit the header, or name the realm the agent is pinned to. |
invalid_realm | Invalid realm selector | The realm selector is malformed (not ""/"global"/a 24-hex id). | Pass a valid realm selector. |
input_too_long | Input too long | The text is longer than the model takes (at most 4096 characters, less for some models). details.limit is the bound the text broke and details.unit its unit (characters or bytes); either is absent when the provider refused without saying. | Split the text into calls of at most details.limit characters (or bytes). |
Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only.
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
The requested resource does not exist.
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
The requested realm is blocked or corrupt; the request fails closed before dispatch.
Media type: application/json
{ "code": "realm_blocked", "message": "realm is blocked"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
realm_blocked | Realm blocked | The requested realm is blocked or corrupt; the request fails closed before dispatch. | Select a valid, reachable realm. |
The JSON body is larger than 64 KiB.
Media type: application/json
{ "code": "payload_too_large", "message": "request body exceeds the configured size limit"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
payload_too_large | Payload too large | The JSON body is larger than 64 KiB. | Send a body of at most 64 KiB; split a long text into several calls. |
The speech model is not available, not configured, or the provider refused the input.
Media type: application/json
{ "code": "speech_not_configured", "message": "no speech model is set"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
model_unavailable | Model unavailable | The speech model is not known or not offered. | Pick a model from GET /api/v1/agent/audio/models. |
speech_not_configured | Speech not configured | No speech model is set for this capability and none was named. | Name a model, or set a default speech model. |
provider_refused | Provider refused | The speech provider refused the input (its content rules or its own limits). | Change the input; details.reason says why when the provider said. |
The per-client request rate limit was exceeded, or the speech budget is spent.
Media type: application/json
{ "code": "speech_quota_exceeded", "message": "the speech budget is spent"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded; the gateway throttled the request before dispatch. | Honor the Retry-After header and retry; reduce the request rate. |
speech_quota_exceeded | Speech quota exceeded | The speech budget of this realm, Bot, or agent is spent for now. | Honor Retry-After, or raise the budget. |
Response headers:
Retry-After: seconds to wait before retrying.
An unexpected error occurred while handling the request.
Media type: application/json
{ "code": "internal_error", "message": "internal server error"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry; if persistent, inspect the daemon logs. |
The speech provider refused the stored key, or failed, or answered something unusable.
Media type: application/json
{ "code": "provider_error", "message": "the speech provider failed", "details": { "diag_id": "3f9a1c0b7e2d4a65" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
provider_auth | Provider key refused | The speech provider refused the stored key. | Check the provider’s key (PUT /api/v1/agent/providers/{id}/auth/api-key). |
provider_error | Provider error | The speech provider failed, or answered something unusable. details.diag_id names the failure in the agent’s log. | Retry; if it persists, try another model. |
Speech is unavailable, busy, or the call could not be recorded.
Media type: application/json
{ "code": "speech_busy", "message": "speech is busy"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit). | Honor Retry-After and retry. |
restriction_unknown | Login restriction unknown | The agent cannot read yet which realms its login may serve, so it refuses realm-scoped requests until it can. Nothing was read or changed. | Retry after the restriction is readable. |
speech_unavailable | Speech unavailable | Speech is not available here: the provider of the selected speech model has no API key (details.reason no_credentials), or the Hoody AI voice relay cannot serve it (a details.reason starting relay_, for example not set up or not reachable). | Set a provider key for a speech model. |
speech_busy | Speech busy | Too many speech calls are running on the agent. | Honor Retry-After and retry. |
admission_write_failed | Not recorded | The speech call could not be recorded for usage, so it was not made; nothing was billed. | Honor Retry-After and retry. |
Response headers:
Retry-After: seconds to wait before retrying (busy, or the call cap).
The speech provider did not answer in time.
Media type: application/json
{ "code": "provider_timeout", "message": "the speech provider did not answer in time"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
provider_timeout | Provider timeout | The speech provider did not answer in time. | Retry, or send a shorter input. |
Transcription
Section titled “Transcription”POST /api/v1/agent/audio/transcriptions
Section titled “POST /api/v1/agent/audio/transcriptions”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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
X-Hoody-Realm | header | string | No | Per-request realm selector: global or a 24-hex realm id (also accepted as ?realm=). |
realm | query | string | No | In-query alias of X-Hoody-Realm, read when the header is absent or empty. |
Request body
Section titled “Request body”The body is multipart/form-data with one file part. Every text field is at most 4 KiB.
| Name | Type | Required | Description |
|---|---|---|---|
file | binary | Yes | The 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. |
model | string | No | A 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. |
language | string | No | The spoken language (for example en), when known. |
prompt | string | No | Words to expect (names, terms), for models that take it. |
response_format | string | No | json (default, returns {text}), text (plain transcript), or verbose_json (with language, duration, and segments when the model gives them). |
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"import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
const form = new FormData();form.append('file', audioFile, 'recording.mp3');form.append('model', 'openrouter/openai/whisper-large-v3');
await client.agent.audio.createTranscription(form);Responses
Section titled “Responses”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_jsononly): the language heard, when the model says.duration(number,verbose_jsononly): the audio’s length in seconds, when known.segments(array,verbose_jsononly): 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."}Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters, or the model lacks the capability (a speech model for a transcription, or the reverse). | Correct the request body or query parameters, or pick a model with the capability (GET /api/v1/agent/audio/models?capability=tts or stt). |
realm_scope_unsupported | Realm scope unsupported | A per-request scope header this route does not take, or, on an agent pinned to one realm, a different realm. | Omit the header, or name the realm the agent is pinned to. |
invalid_realm | Invalid realm selector | The realm selector is malformed (not ""/"global"/a 24-hex id). | Pass a valid realm selector. |
Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only.
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
The requested resource does not exist.
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
The requested realm is blocked or corrupt; the request fails closed before dispatch.
Media type: application/json
{ "code": "realm_blocked", "message": "realm is blocked"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
realm_blocked | Realm blocked | The requested realm is blocked or corrupt; the request fails closed before dispatch. | Select a valid, reachable realm. |
The upload is larger than 16 MiB, or the audio is longer than the route or the model takes.
Media type: application/json
{ "code": "payload_too_large", "message": "The upload is larger than 16 MiB."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
payload_too_large | Payload too large | The upload is larger than 16 MiB. | Send a recording of at most 16 MiB. |
audio_too_long | Audio too long | The audio is longer than the route or the model takes (at most 600 seconds). | Send a shorter recording. |
The upload is not an audio file this route takes.
Media type: application/json
{ "code": "unsupported_audio", "message": "this audio format is not accepted here"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
unsupported_audio | Unsupported audio | The upload is not an audio file this route takes (wav or mp3; some models also take webm, ogg, m4a, or flac). | Send wav or mp3. |
The model is not available, not configured, the provider refused the input, or the transcript does not fit the audio.
Media type: application/json
{ "code": "stt_suspect", "message": "the transcript does not fit the audio"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
model_unavailable | Model unavailable | The speech model is not known or not offered. | Pick a model from GET /api/v1/agent/audio/models. |
speech_not_configured | Speech not configured | No speech model is set for this capability and none was named. | Name a model, or set a default transcription model. |
provider_refused | Provider refused | The speech provider refused the input (its content rules or its own limits). | Change the input; details.reason says why when the provider said. |
stt_suspect | Transcript not trusted | The provider answered a transcript that is too short for the speech in the audio (empty though speech was heard, or only a few words for at least 8 seconds of speech), so it is not used. | Send the audio again, or use another model. |
The per-client request rate limit was exceeded, or the speech budget is spent.
Media type: application/json
{ "code": "speech_quota_exceeded", "message": "the speech budget is spent"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded; the gateway throttled the request before dispatch. | Honor the Retry-After header and retry; reduce the request rate. |
speech_quota_exceeded | Speech quota exceeded | The speech budget of this realm, Bot, or agent is spent for now. | Honor Retry-After, or raise the budget. |
Response headers:
Retry-After: seconds to wait before retrying.
An unexpected error occurred while handling the request.
Media type: application/json
{ "code": "internal_error", "message": "internal server error"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry; if persistent, inspect the daemon logs. |
The speech provider refused the stored key, or failed, or answered something unusable.
Media type: application/json
{ "code": "provider_error", "message": "the speech provider failed", "details": { "diag_id": "3f9a1c0b7e2d4a65" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
provider_auth | Provider key refused | The speech provider refused the stored key. | Check the provider’s key (PUT /api/v1/agent/providers/{id}/auth/api-key). |
provider_error | Provider error | The speech provider failed, or answered something unusable. details.diag_id names the failure in the agent’s log. | Retry; if it persists, try another model. |
Speech is unavailable, busy, or the call could not be recorded.
Media type: application/json
{ "code": "speech_busy", "message": "speech is busy"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit). | Honor Retry-After and retry. |
restriction_unknown | Login restriction unknown | The agent cannot read yet which realms its login may serve, so it refuses realm-scoped requests until it can. Nothing was read or changed. | Retry after the restriction is readable. |
speech_unavailable | Speech unavailable | Speech is not available here: the provider of the selected speech model has no API key (details.reason no_credentials), or the Hoody AI voice relay cannot serve it (a details.reason starting relay_, for example not set up or not reachable). | Set a provider key for a speech model. |
speech_busy | Speech busy | Too many speech calls are running on the agent. | Honor Retry-After and retry. |
admission_write_failed | Not recorded | The speech call could not be recorded for usage, so it was not made; nothing was billed. | Honor Retry-After and retry. |
Response headers:
Retry-After: seconds to wait before retrying (busy, or the call cap).
The speech provider did not answer in time.
Media type: application/json
{ "code": "provider_timeout", "message": "the speech provider did not answer in time"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
provider_timeout | Provider timeout | The speech provider did not answer in time. | Retry, or send a shorter input. |
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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
X-Hoody-Realm | header | string | No | Per-request realm selector: global or a 24-hex realm id (also accepted as ?realm=). |
realm | query | string | No | In-query alias of X-Hoody-Realm, read when the header is absent or empty. |
Request body
Section titled “Request body”The body is multipart/form-data with one file part. Every text field is at most 4 KiB.
| Name | Type | Required | Description |
|---|---|---|---|
file | binary | Yes | The 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. |
model | string | No | A 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. |
language | string | No | The spoken language (for example en), when known. |
prompt | string | No | Words to expect (names, terms), for models that take it. |
response_format | string | No | json (default, returns {text}). The streamed route answers json. |
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>"import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
const form = new FormData();form.append('file', audioFile, 'recording.mp3');form.append('model', '<stt-model-with-partials>');
await client.agent.audio.createTranscription(form, { stream: true });Responses
Section titled “Responses”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.doneMedia type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters, or the model lacks the capability (a speech model for a transcription, or the reverse). | Correct the request body or query parameters, or pick a model with the capability (GET /api/v1/agent/audio/models?capability=tts or stt). |
realm_scope_unsupported | Realm scope unsupported | A per-request scope header this route does not take, or, on an agent pinned to one realm, a different realm. | Omit the header, or name the realm the agent is pinned to. |
invalid_realm | Invalid realm selector | The realm selector is malformed (not ""/"global"/a 24-hex id). | Pass a valid realm selector. |
Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only.
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
The requested resource does not exist.
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
The requested realm is blocked or corrupt; the request fails closed before dispatch.
Media type: application/json
{ "code": "realm_blocked", "message": "realm is blocked"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
realm_blocked | Realm blocked | The requested realm is blocked or corrupt; the request fails closed before dispatch. | Select a valid, reachable realm. |
The upload is larger than 16 MiB, or the audio is longer than the route or the model takes.
Media type: application/json
{ "code": "payload_too_large", "message": "The upload is larger than 16 MiB."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
payload_too_large | Payload too large | The upload is larger than 16 MiB. | Send a recording of at most 16 MiB. |
audio_too_long | Audio too long | The audio is longer than the route or the model takes (at most 600 seconds). | Send a shorter recording. |
The upload is not an audio file this route takes.
Media type: application/json
{ "code": "unsupported_audio", "message": "this audio format is not accepted here"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
unsupported_audio | Unsupported audio | The upload is not an audio file this route takes (wav or mp3; some models also take webm, ogg, m4a, or flac on POST /api/v1/agent/audio/transcriptions). | Send wav or mp3. |
The model is not available, not configured, the provider refused the input, or the transcript does not fit the audio.
Media type: application/json
{ "code": "stt_suspect", "message": "the transcript does not fit the audio"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
model_unavailable | Model unavailable | The speech model is not known or not offered. | Pick a model from GET /api/v1/agent/audio/models. |
speech_not_configured | Speech not configured | No speech model is set for this capability and none was named. | Name a model, or set a default transcription model. |
provider_refused | Provider refused | The speech provider refused the input (its content rules or its own limits). | Change the input; details.reason says why when the provider said. |
stt_suspect | Transcript not trusted | The provider answered a transcript that is too short for the speech in the audio (empty though speech was heard, or only a few words for at least 8 seconds of speech), so it is not used. | Send the audio again, or use another model. |
The per-client request rate limit was exceeded, or the speech budget is spent.
Media type: application/json
{ "code": "speech_quota_exceeded", "message": "the speech budget is spent"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded; the gateway throttled the request before dispatch. | Honor the Retry-After header and retry; reduce the request rate. |
speech_quota_exceeded | Speech quota exceeded | The speech budget of this realm, Bot, or agent is spent for now. | Honor Retry-After, or raise the budget. |
Response headers:
Retry-After: seconds to wait before retrying.
An unexpected error occurred while handling the request.
Media type: application/json
{ "code": "internal_error", "message": "internal server error"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry; if persistent, inspect the daemon logs. |
The speech provider refused the stored key, or failed, or answered something unusable.
Media type: application/json
{ "code": "provider_error", "message": "the speech provider failed", "details": { "diag_id": "3f9a1c0b7e2d4a65" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
provider_auth | Provider key refused | The speech provider refused the stored key. | Check the provider’s key (PUT /api/v1/agent/providers/{id}/auth/api-key). |
provider_error | Provider error | The speech provider failed, or answered something unusable. details.diag_id names the failure in the agent’s log. | Retry; if it persists, try another model. |
Speech is unavailable, busy, or the call could not be recorded.
Media type: application/json
{ "code": "speech_busy", "message": "speech is busy"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit). | Honor Retry-After and retry. |
restriction_unknown | Login restriction unknown | The agent cannot read yet which realms its login may serve, so it refuses realm-scoped requests until it can. Nothing was read or changed. | Retry after the restriction is readable. |
speech_unavailable | Speech unavailable | Speech is not available here: the provider of the selected speech model has no API key (details.reason no_credentials), or the Hoody AI voice relay cannot serve it (a details.reason starting relay_, for example not set up or not reachable). | Set a provider key for a speech model. |
speech_busy | Speech busy | Too many speech calls are running on the agent. | Honor Retry-After and retry. |
admission_write_failed | Not recorded | The speech call could not be recorded for usage, so it was not made; nothing was billed. | Honor Retry-After and retry. |
Response headers:
Retry-After: seconds to wait before retrying (busy, or the call cap).
The speech provider did not answer in time.
Media type: application/json
{ "code": "provider_timeout", "message": "the speech provider did not answer in time"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
provider_timeout | Provider timeout | The speech provider did not answer in time. | Retry, or send a shorter input. |
Discovery
Section titled “Discovery”GET /api/v1/agent/audio/models
Section titled “GET /api/v1/agent/audio/models”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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
capability | query | string | No | Only models with this capability. Allowed values: tts, stt. |
X-Hoody-Realm | header | string | No | Per-request realm selector: global or a 24-hex realm id (also accepted as ?realm=). |
realm | query | string | No | In-query alias of X-Hoody-Realm, read when the header is absent or empty. |
curl -X GET "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/audio/models?capability=tts"import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
await client.agent.audio.listModels({ capability: 'tts' });Responses
Section titled “Responses”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 takePOST /api/v1/agent/audio/transcriptions/streamandstreamtrue.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), orunknown.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 (forhoody-aimodels, the Hoody AI relay is set up here). A call can still answer503 speech_unavailablewhen the provider offers no such model here.hoody-aimodels list emptyformatsandrates; they are resolved when a call is made.items[].unavailable_reason(string): only whenavailableisfalse, why:no_credentials(add a key withPUT /api/v1/agent/providers/{id}/auth/api-key),relay_not_configured, or a reason from the model catalogue.
Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
realm_scope_unsupported | Realm scope unsupported | A per-request scope header this route does not take, or, on an agent pinned to one realm, a different realm. | Omit the header, or name the realm the agent is pinned to. |
invalid_realm | Invalid realm selector | The realm selector is malformed (not ""/"global"/a 24-hex id). | Pass a valid realm selector. |
Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only.
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
The requested resource does not exist.
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
The requested realm is blocked or corrupt; the request fails closed before dispatch.
Media type: application/json
{ "code": "realm_blocked", "message": "realm is blocked"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
realm_blocked | Realm blocked | The requested realm is blocked or corrupt; the request fails closed before dispatch. | Select a valid, reachable realm. |
The speech model is not known or not offered.
Media type: application/json
{ "code": "model_unavailable", "message": "this speech model is not available"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
model_unavailable | Model unavailable | The speech model is not known or not offered. | Pick a model from GET /api/v1/agent/audio/models. |
The per-client request rate limit was exceeded; the gateway throttled the request before dispatch.
Media type: application/json
{ "code": "rate_limited", "message": "request rate limit exceeded"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded; the gateway throttled the request before dispatch. | Honor the Retry-After header and retry; reduce the request rate. |
An unexpected error occurred while handling the request.
Media type: application/json
{ "code": "internal_error", "message": "internal server error"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry; if persistent, inspect the daemon logs. |
The daemon could not service the request.
Media type: application/json
{ "code": "service_unavailable", "message": "service unavailable"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit). | Honor Retry-After and retry. |
restriction_unknown | Login restriction unknown | The agent cannot read yet which realms its login may serve, so it refuses realm-scoped requests until it can. Nothing was read or changed. | Retry after the restriction is readable. |
GET /api/v1/agent/audio/voices
Section titled “GET /api/v1/agent/audio/voices”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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
model | query | string | No | A speech model spec. Omitted, every available text-to-speech model except the Hoody AI relay models. |
X-Hoody-Realm | header | string | No | Per-request realm selector: global or a 24-hex realm id (also accepted as ?realm=). |
realm | query | string | No | In-query alias of X-Hoody-Realm, read when the header is absent or empty. |
curl -X GET "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/audio/voices?model=minimax/speech-2.8-turbo"import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
await client.agent.audio.listVoices({ model: 'minimax/speech-2.8-turbo' });Responses
Section titled “Responses”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 asvoice.items[].languages(array): the languages it speaks; empty when not known.items[].model(string, required): the model it belongs to.
Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
realm_scope_unsupported | Realm scope unsupported | A per-request scope header this route does not take, or, on an agent pinned to one realm, a different realm. | Omit the header, or name the realm the agent is pinned to. |
invalid_realm | Invalid realm selector | The realm selector is malformed (not ""/"global"/a 24-hex id). | Pass a valid realm selector. |
Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only.
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
The requested resource does not exist.
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
The requested realm is blocked or corrupt; the request fails closed before dispatch.
Media type: application/json
{ "code": "realm_blocked", "message": "realm is blocked"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
realm_blocked | Realm blocked | The requested realm is blocked or corrupt; the request fails closed before dispatch. | Select a valid, reachable realm. |
The speech model is not known or not offered.
Media type: application/json
{ "code": "model_unavailable", "message": "this speech model is not available"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
model_unavailable | Model unavailable | The speech model is not known or not offered. | Pick a model from GET /api/v1/agent/audio/models. |
The per-client request rate limit was exceeded; the gateway throttled the request before dispatch.
Media type: application/json
{ "code": "rate_limited", "message": "request rate limit exceeded"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded; the gateway throttled the request before dispatch. | Honor the Retry-After header and retry; reduce the request rate. |
An unexpected error occurred while handling the request.
Media type: application/json
{ "code": "internal_error", "message": "internal server error"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry; if persistent, inspect the daemon logs. |
The daemon could not service the request.
Media type: application/json
{ "code": "service_unavailable", "message": "service unavailable"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit). | Honor Retry-After and retry. |
restriction_unknown | Login restriction unknown | The agent cannot read yet which realms its login may serve, so it refuses realm-scoped requests until it can. Nothing was read or changed. | Retry after the restriction is readable. |
OpenAI-compatible routes
Section titled “OpenAI-compatible routes”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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
X-Hoody-Realm | header | string | No | Per-request realm selector: global or a 24-hex realm id (also accepted as ?realm=). |
realm | query | string | No | In-query alias of X-Hoody-Realm, read when the header is absent or empty. |
Request body
Section titled “Request body”| Name | Type | Required | Description |
|---|---|---|---|
model | string | No | A 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. |
input | string | Yes | The text to speak (at most 4096 characters; less for some models). |
voice | string | No | A voice of the model (GET /api/v1/agent/audio/voices). Omitted, the model’s first voice. |
instructions | string | No | How to speak (tone, pace), for models that take it; a model that does not is 400. |
response_format | string | No | The audio format. Allowed values: mp3, wav, pcm. Omitted: mp3. |
speed | number | No | Speaking speed, for models that take it. |
stream_format | string | No | audio (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. |
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" }'Responses
Section titled “Responses”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, orpcm).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, andratewhen the model gives one.speech.audio.done: the audio is complete. Data:typeandusage. The route does not define the members ofusage. It is always the last event on success.error: the call failed after the first frame. Data:code,message, anddetailswhen there are details.: ping: a comment line sent every 25 s; it carries no data.
event: speech.audio.deltadata: {"type":"speech.audio.delta","audio":"SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjYwLjMuMTAw","format":"mp3"}
: ping
event: speech.audio.deltadata: {"type":"speech.audio.delta","audio":"//uQxAAAAAAAAAAAAAAAAAAAAAAASW5mbwAAAA8AAAAC","format":"mp3"}
event: speech.audio.donedata: {"type":"speech.audio.done","usage":{}}Media type: application/json
{ "error": { "message": "invalid request", "type": "invalid_request_error", "param": null, "code": "bad_request" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters, or the model lacks the capability (a speech model for a transcription, or the reverse). | Correct the request body or query parameters, or pick a model with the capability (GET /api/v1/agent/audio/models?capability=tts or stt). |
realm_scope_unsupported | Realm scope unsupported | A per-request scope header this route does not take, or, on an agent pinned to one realm, a different realm. | Omit the header, or name the realm the agent is pinned to. |
invalid_realm | Invalid realm selector | The realm selector is malformed (not ""/"global"/a 24-hex id). | Pass a valid realm selector. |
input_too_long | Input too long | The text is longer than the model takes (at most 4096 characters, less for some models). details.limit is the bound the text broke and details.unit its unit (characters or bytes); either is absent when the provider refused without saying. | Split the text into calls of at most details.limit characters (or bytes). |
Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only.
Media type: application/json
{ "error": { "message": "Hoody Kit programs are reached through their URLs only", "type": "api_error", "param": null, "code": "forbidden" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL. |
The requested resource does not exist.
Media type: application/json
{ "error": { "message": "resource not found", "type": "not_found_error", "param": null, "code": "not_found" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
The requested realm is blocked or corrupt; the request fails closed before dispatch.
Media type: application/json
{ "error": { "message": "realm is blocked", "type": "api_error", "param": null, "code": "realm_blocked" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
realm_blocked | Realm blocked | The requested realm is blocked or corrupt; the request fails closed before dispatch. | Select a valid, reachable realm. |
The JSON body is larger than 64 KiB.
Media type: application/json
{ "error": { "message": "request body exceeds the configured size limit", "type": "invalid_request_error", "param": null, "code": "payload_too_large" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
payload_too_large | Payload too large | The JSON body is larger than 64 KiB. | Send a body of at most 64 KiB; split a long text into several calls. |
The speech model is not available, not configured, or the provider refused the input.
Media type: application/json
{ "error": { "message": "this speech model is not available", "type": "invalid_request_error", "param": null, "code": "model_unavailable" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
model_unavailable | Model unavailable | The speech model is not known or not offered. | Pick a model from GET /api/v1/agent/audio/models. |
speech_not_configured | Speech not configured | No speech model is set for this capability and none was named. | Name a model, or set a default speech model. |
provider_refused | Provider refused | The speech provider refused the input (its content rules or its own limits). | Change the input; details.reason says why when the provider said. |
The per-client request rate limit was exceeded, or the speech budget is spent.
Media type: application/json
{ "error": { "message": "the speech budget is spent", "type": "rate_limit_error", "param": null, "code": "speech_quota_exceeded" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded; the gateway throttled the request before dispatch. | Honor the Retry-After header and retry; reduce the request rate. |
speech_quota_exceeded | Speech quota exceeded | The speech budget of this realm, Bot, or agent is spent for now. | Honor Retry-After, or raise the budget. |
Response headers:
Retry-After: seconds to wait before retrying.
An unexpected error occurred while handling the request.
Media type: application/json
{ "error": { "message": "internal server error", "type": "api_error", "param": null, "code": "internal_error" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry; if persistent, inspect the daemon logs. |
The speech provider refused the stored key, or failed, or answered something unusable.
Media type: application/json
{ "error": { "message": "the speech provider failed", "type": "api_error", "param": null, "code": "provider_error" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
provider_auth | Provider key refused | The speech provider refused the stored key. | Check the provider’s key (PUT /api/v1/agent/providers/{id}/auth/api-key). |
provider_error | Provider error | The speech provider failed, or answered something unusable. details.diag_id names the failure in the agent’s log. | Retry; if it persists, try another model. |
Speech is unavailable, busy, or the call could not be recorded.
Media type: application/json
{ "error": { "message": "speech is busy", "type": "api_error", "param": null, "code": "speech_busy" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit). | Honor Retry-After and retry. |
restriction_unknown | Login restriction unknown | The agent cannot read yet which realms its login may serve, so it refuses realm-scoped requests until it can. Nothing was read or changed. | Retry after the restriction is readable. |
speech_unavailable | Speech unavailable | Speech is not available here: the provider of the selected speech model has no API key (details.reason no_credentials), or the Hoody AI voice relay cannot serve it (a details.reason starting relay_, for example not set up or not reachable). | Set a provider key for a speech model. |
speech_busy | Speech busy | Too many speech calls are running on the agent. | Honor Retry-After and retry. |
admission_write_failed | Not recorded | The speech call could not be recorded for usage, so it was not made; nothing was billed. | Honor Retry-After and retry. |
Response headers:
Retry-After: seconds to wait before retrying (busy, or the call cap).
The speech provider did not answer in time.
Media type: application/json
{ "error": { "message": "the speech provider did not answer in time", "type": "api_error", "param": null, "code": "provider_timeout" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
provider_timeout | Provider timeout | The speech provider did not answer in time. | Retry, or send a shorter input. |
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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
X-Hoody-Realm | header | string | No | Per-request realm selector: global or a 24-hex realm id (also accepted as ?realm=). |
realm | query | string | No | In-query alias of X-Hoody-Realm, read when the header is absent or empty. |
Request body
Section titled “Request body”The body is multipart/form-data with one file part. Every text field is at most 4 KiB.
| Name | Type | Required | Description |
|---|---|---|---|
file | binary | Yes | The 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. |
model | string | No | A 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. |
language | string | No | The spoken language (for example en), when known. |
prompt | string | No | Words to expect (names, terms), for models that take it. |
response_format | string | No | json (default, returns {text}), text, or verbose_json. |
stream | boolean | No | true: 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. |
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:
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"Responses
Section titled “Responses”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_jsononly): the language heard, when the model says.duration(number,verbose_jsononly): the audio’s length in seconds, when known.segments(array,verbose_jsononly): 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:typeanddelta.transcript.text.done: the whole transcript. Data:type,text, andusage. The route does not define the members ofusage. It is always the last event on success.error: the call failed after the first frame. Data:code,message, anddetailswhen there are details.: ping: a comment line sent every 25 s; it carries no data.
event: transcript.text.deltadata: {"type":"transcript.text.delta","delta":"Deploy the"}
: ping
event: transcript.text.deltadata: {"type":"transcript.text.delta","delta":" staging build."}
event: transcript.text.donedata: {"type":"transcript.text.done","text":"Deploy the staging build.","usage":{}}Media type: application/json
{ "error": { "message": "invalid request", "type": "invalid_request_error", "param": null, "code": "bad_request" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters, or the model lacks the capability (a speech model for a transcription, or the reverse). | Correct the request body or query parameters, or pick a model with the capability (GET /api/v1/agent/audio/models?capability=tts or stt). |
realm_scope_unsupported | Realm scope unsupported | A per-request scope header this route does not take, or, on an agent pinned to one realm, a different realm. | Omit the header, or name the realm the agent is pinned to. |
invalid_realm | Invalid realm selector | The realm selector is malformed (not ""/"global"/a 24-hex id). | Pass a valid realm selector. |
Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only.
Media type: application/json
{ "error": { "message": "Hoody Kit programs are reached through their URLs only", "type": "api_error", "param": null, "code": "forbidden" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL. |
The requested resource does not exist.
Media type: application/json
{ "error": { "message": "resource not found", "type": "not_found_error", "param": null, "code": "not_found" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
The requested realm is blocked or corrupt; the request fails closed before dispatch.
Media type: application/json
{ "error": { "message": "realm is blocked", "type": "api_error", "param": null, "code": "realm_blocked" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
realm_blocked | Realm blocked | The requested realm is blocked or corrupt; the request fails closed before dispatch. | Select a valid, reachable realm. |
The upload is larger than 16 MiB, or the audio is longer than the route or the model takes.
Media type: application/json
{ "error": { "message": "The upload is larger than 16 MiB.", "type": "invalid_request_error", "param": null, "code": "payload_too_large" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
payload_too_large | Payload too large | The upload is larger than 16 MiB. | Send a recording of at most 16 MiB. |
audio_too_long | Audio too long | The audio is longer than the route or the model takes (at most 600 seconds). | Send a shorter recording. |
The upload is not an audio file this route takes.
Media type: application/json
{ "error": { "message": "this audio format is not accepted here", "type": "invalid_request_error", "param": null, "code": "unsupported_audio" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
unsupported_audio | Unsupported audio | The upload is not an audio file this route takes (wav or mp3; some models also take webm, ogg, m4a, or flac). | Send wav or mp3. |
The model is not available, not configured, the provider refused the input, or the transcript does not fit the audio.
Media type: application/json
{ "error": { "message": "the transcript does not fit the audio", "type": "invalid_request_error", "param": null, "code": "stt_suspect" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
model_unavailable | Model unavailable | The speech model is not known or not offered. | Pick a model from GET /api/v1/agent/audio/models. |
speech_not_configured | Speech not configured | No speech model is set for this capability and none was named. | Name a model, or set a default transcription model. |
provider_refused | Provider refused | The speech provider refused the input (its content rules or its own limits). | Change the input; details.reason says why when the provider said. |
stt_suspect | Transcript not trusted | The provider answered a transcript that is too short for the speech in the audio (empty though speech was heard, or only a few words for at least 8 seconds of speech), so it is not used. | Send the audio again, or use another model. |
The per-client request rate limit was exceeded, or the speech budget is spent.
Media type: application/json
{ "error": { "message": "the speech budget is spent", "type": "rate_limit_error", "param": null, "code": "speech_quota_exceeded" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded; the gateway throttled the request before dispatch. | Honor the Retry-After header and retry; reduce the request rate. |
speech_quota_exceeded | Speech quota exceeded | The speech budget of this realm, Bot, or agent is spent for now. | Honor Retry-After, or raise the budget. |
Response headers:
Retry-After: seconds to wait before retrying.
An unexpected error occurred while handling the request.
Media type: application/json
{ "error": { "message": "internal server error", "type": "api_error", "param": null, "code": "internal_error" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry; if persistent, inspect the daemon logs. |
The speech provider refused the stored key, or failed, or answered something unusable.
Media type: application/json
{ "error": { "message": "the speech provider failed", "type": "api_error", "param": null, "code": "provider_error" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
provider_auth | Provider key refused | The speech provider refused the stored key. | Check the provider’s key (PUT /api/v1/agent/providers/{id}/auth/api-key). |
provider_error | Provider error | The speech provider failed, or answered something unusable. details.diag_id names the failure in the agent’s log. | Retry; if it persists, try another model. |
Speech is unavailable, busy, or the call could not be recorded.
Media type: application/json
{ "error": { "message": "speech is busy", "type": "api_error", "param": null, "code": "speech_busy" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit). | Honor Retry-After and retry. |
restriction_unknown | Login restriction unknown | The agent cannot read yet which realms its login may serve, so it refuses realm-scoped requests until it can. Nothing was read or changed. | Retry after the restriction is readable. |
speech_unavailable | Speech unavailable | Speech is not available here: the provider of the selected speech model has no API key (details.reason no_credentials), or the Hoody AI voice relay cannot serve it (a details.reason starting relay_, for example not set up or not reachable). | Set a provider key for a speech model. |
speech_busy | Speech busy | Too many speech calls are running on the agent. | Honor Retry-After and retry. |
admission_write_failed | Not recorded | The speech call could not be recorded for usage, so it was not made; nothing was billed. | Honor Retry-After and retry. |
Response headers:
Retry-After: seconds to wait before retrying (busy, or the call cap).
The speech provider did not answer in time.
Media type: application/json
{ "error": { "message": "the speech provider did not answer in time", "type": "api_error", "param": null, "code": "provider_timeout" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
provider_timeout | Provider timeout | The speech provider did not answer in time. | Retry, or send a shorter input. |