# Agent: Audio **Page:** api/agent/audio [Download Raw Markdown](./api/agent/audio.md) --- # 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`. All cURL examples below use the host `https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com`. Replace `{projectId}`, `{computerId}`, and `{server}` with real values when you call the agent. ## Speech ### `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 | 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 | 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`. | ```bash 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" }' ``` ```ts 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 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. ```audio ``` Media type: `application/json` ```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` ```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` ```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` ```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` ```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` ```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` ```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` ```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` ```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` ```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` ```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` 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 | 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 | 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`. | ```bash 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" }' ``` ```ts 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 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. ```text event: speech.audio.delta : ping event: speech.audio.delta event: speech.audio.done ``` Media type: `application/json` ```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` ```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` ```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` ```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` ```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` ```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` ```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` ```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` ```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` ```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` ```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 ### `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 | 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 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). | ```bash 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" ``` ```ts 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 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. ```json { "text": "Deploy the staging build." } ``` Media type: `application/json` ```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` ```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` ```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` ```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` ```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` ```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` ```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` ```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` ```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` ```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` ```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` ```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` 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 `` 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 | 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 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`. | ```bash 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=" ``` ```ts 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', ''); await client.agent.audio.createTranscription(form, { stream: true }); ``` #### 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. ```text event: transcript.text.delta : ping event: transcript.text.delta event: transcript.text.done ``` Media type: `application/json` ```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` ```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` ```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` ```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` ```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` ```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` ```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` ```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` ```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` ```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` ```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` ```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 ### `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 | 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. | ```bash curl -X GET "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/audio/models?capability=tts" ``` ```ts 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 The models. Media type: `application/json` ```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. Media type: `application/json` ```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` ```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` ```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` ```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` ```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` ```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` ```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` ```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` 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 | 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. | ```bash curl -X GET "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/audio/voices?model=minimax/speech-2.8-turbo" ``` ```ts 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 The voices. Media type: `application/json` ```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. Media type: `application/json` ```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` ```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` ```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` ```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` ```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` ```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` ```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` ```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 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. There is no TypeScript SDK method for these routes; call them with HTTP (cURL, fetch, your HTTP client of choice). ### `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 | 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 | 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`. | ```bash 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 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. ```audio ``` 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. ```text 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":{}} ``` Media type: `application/json` ```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` ```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` ```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` ```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` ```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` ```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` ```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` ```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` ```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` ```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` ```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` `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 `` 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 | 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 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. | ```bash 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: ```bash 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=" \ -F "stream=true" ``` #### 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_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. ```json { "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. ```text 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":{}} ``` Media type: `application/json` ```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` ```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` ```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` ```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` ```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` ```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` ```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` ```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` ```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` ```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` ```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` ```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. |