# Hoody AI Models & Pricing reference **Page:** foundation/hoody-ai/models/reference [Download Raw Markdown](./foundation/hoody-ai/models/reference.md) --- # Hoody AI Models & Pricing reference Lookup tables for [Hoody AI Models & Pricing](/foundation/hoody-ai/models/). The catalog route and its fields are on the [AI Models API page](/api/ai-models/). ## Catalog fields `GET https://api.hoody.com/api/v1/ai/models` returns the catalog in `data.models`, with `data.updated_at` for when it was refreshed. The SDK equivalent is `client.api.ai.listModels()`, which returns the same data from any supported language. | Field | What it holds | |---|---| | `id` | The model identifier. For catalog-listed models, treat it as opaque: copy it exactly as returned, never abbreviated or altered | | `pricing` | Present on every entry, in Hoody prices. `pricing.prompt` is the base prompt price | | `pricing_overrides` | Optional array. Each entry holds conditions and decimal-string prices, keyed like `pricing`, that replace the base prices: for example at `min_prompt_tokens` or during a UTC window (`utc_days`, `utc_start`, `utc_end`). Check applicable overrides before comparing request costs | | `context_length` | May be absent or null | | `input_modalities` | Optional. Models with image understanding advertise `"image"` here | | `output_modalities` | Optional. Models that can return images advertise `"image"` here | ## Catalog queries Each query reads the live catalog, which needs no sign-in, and uses `jq`. Pick an id from the result rather than hard-coding one from these pages. For code generation, analysis and long documents, sort by context window and take the largest that fits your budget: ```bash curl -s https://api.hoody.com/api/v1/ai/models \ | jq -r '.data.models | sort_by(-(.context_length // 0))[] | "\(.context_length)\t\(.id)"' | head ``` For image understanding, models that accept image input: ```bash curl -s https://api.hoody.com/api/v1/ai/models \ | jq -r '.data.models[] | select(.input_modalities | index("image")) | .id' ``` The price sort is on the guide, under [Compare model prices](/foundation/hoody-ai/models/#compare-model-prices), and the image-output query under [Can I generate images?](/foundation/hoody-ai/models/#can-i-generate-images). ## Model makers The catalog includes models from these makers, among others. Every catalog model is a text model (chat and completion models, for conversations, code generation, analysis and general-purpose tasks); the last column names some of them. | Maker | Models | Text models | |---|---|---| | MiniMax | MiniMax M-series models | MiniMax M3.1 Flash | | Qwen (Alibaba) | Qwen Max and the Qwen family | Qwen Max | | DeepSeek | DeepSeek V-series | DeepSeek V-series | | Meta | Llama 4, Llama 3.3, Llama 3.1 | Llama 4, Llama 3.3 70B | | Mistral AI | Mistral Large, Medium, Mixtral | Mistral Large, Mistral Medium, Mixtral | | xAI | Grok 4 | Grok 4 | | Microsoft | Phi models | Phi 4 | | Amazon | Nova models | | | NVIDIA | Nemotron models | | | Cohere | Command models | | | Perplexity AI | Sonar Pro, Sonar models | | | Fireworks AI | Ember-1 | | The catalog returns pricing as Hoody prices; provider details are intentionally not exposed. Your prompts and responses go through Hoody AI to the model's provider. ## Model names outside the catalog Each name below works from a computer even though it is not a catalog entry, so `/api/v1/ai/models` never returns it. | Name | Where it works | |---|---| | `hoody-free`, `hoody/hoody-free`, `hoody-ai/hoody-free` | Chat requests, where Hoody Free is available | | `hoody-ai/hoody-decide`, `hoody/hoody-decide`, `hoody-decide` | The [decision endpoints](/foundation/hoody-ai/decisions/), `POST /api/v1/systemone` and `POST /api/v1/decisions` | | `hoody-ai/hoody-tts` | `POST /api/v1/audio/speech` | | `hoody-ai/hoody-stt` | `POST /api/v1/audio/transcriptions` | The voice names match in any letter case, with or without the `hoody-ai/` or `hoody/` prefix. Web search takes no model: it has its own endpoint, `POST /api/v1/coding_plan/search`. ## Hoody Free requests A Hoody Free request is an ordinary chat completion, and the response names `hoody-free` as its model. | Case | Behaviour | |---|---| | `"stream": true` | The reply arrives as Server-Sent Events and normally ends with `data: [DONE]` | | Token usage | Forwarded when the model supplies it. In a streamed reply, setting `stream_options.include_usage` to `false` leaves it out; a non-streamed reply keeps it | | A stream without usage or without `[DONE]` | Missing usage or `[DONE]` alone is acceptable when another completion signal exists: a terminal usage chunk, or a terminal finish reason for every requested choice. Treat a stream error as a failed or incomplete reply | | An `input_audio` part, `modalities` containing `"audio"`, or a root `audio` object | `400 free_audio_unsupported`, refused before anything is sent | | A `video_url` part | `400 invalid_body`, refused before anything is sent | | A body or prompt over the size limit | `413` (`body_too_large` or `input_tokens_exceed_cap`) | | A limit ran out | `429` with a `Retry-After` header and code `hoody_free_throttled` ([body](/foundation/hoody-ai/models/#chat-free-of-charge-with-hoody-free)) | | A Hoody Free request using a key other than a `computer-…` token | `400 hoody_free_requires_computer` | | A request naming Hoody Free on an unsupported endpoint | `400 free_model_endpoint_unsupported`; use chat completions | The `429` body's `limit` names the limit you reached: | `limit` | Limit | |---|---| | `per_minute`, `per_hour`, `per_day` | Tokens | | `per_minute_cached_tokens`, `per_hour_cached_tokens`, `per_day_cached_tokens` | Prompt tokens served from cache | | `concurrent` | Requests in flight | | `input_tps`, `output_tps` | Tokens per second | ## Hoody Voice Hoody Voice is the free speech pair next to Hoody Free. Hoody chooses the model behind each. | | `hoody-ai/hoody-tts` | `hoody-ai/hoody-stt` | |---|---|---| | Endpoint | `POST /api/v1/audio/speech` | `POST /api/v1/audio/transcriptions` | | Input | `input`: up to 4,096 characters of text | Audio up to 25 MB (25,000,000 bytes) and 600 seconds, as `wav`, `mp3`, `webm`, `ogg`, `m4a` or `flac` | | Options | `voice` (required): `af_alloy`, `af_aoede`, `af_bella` or `af_heart`. `response_format`: `pcm` (the default) or `mp3` | `response_format`: `json` (the default) or `verbose_json`. `language` (optional) | | Output | The audio itself: `audio/mpeg` for `mp3`; for `pcm`, 16-bit little-endian samples (`s16le`) at 24,000 Hz, one channel (`audio/pcm;rate=24000;channels=1`) | JSON with `text`. `verbose_json` can add `duration`, `language` and `segments` (`id`, `start`, `end`, `text`); any of them can be missing, and a segment's `id`, `start` or `end` can be `null` | - **Speech:** comes back as raw audio in the response body. Add `"stream_format": "audio"` to ask for streaming, where streamed speech is available. Where it is not, the request answers `503 voice_routing_unavailable`, and retrying without `stream_format` may help. Event streams (`"stream_format": "sse"`) are not offered. - **Transcription input:** send JSON with the base64 audio and its format in `input_audio`, `{"model": "hoody-ai/hoody-stt", "input_audio": {"data": "", "format": "wav"}}`, or upload it as `multipart/form-data` with a `file` part, whose format comes from the file name's extension, else from the part's `Content-Type`. Audio URLs are refused. - **Long audio:** a WAV file whose header shows more than 600 seconds is refused with `400 invalid_request` before it is sent. Other formats, and a WAV whose length cannot be read from its header, can still be refused later. - **Seconds counted:** the response's `usage.seconds` is the duration the request counted against your daily seconds, which may be rounded or estimated. - **Listing:** both models are listed only on request. Listing does not guarantee availability: a listed model can still return `503 voice_routing_unavailable`. `GET https://ai.hoody.com/api/v1/models?output_modalities=speech` requests the speech listing, including `hoody-tts` when listed; `output_modalities=transcription` requests the transcription listing, including `hoody-stt` when listed. Each listed alias carries its formats and size limits, plus voices for speech, under `hoody.capabilities`. Examples and error codes: [Speech with Hoody Voice](/foundation/hoody-ai/usage/#speech-with-hoody-voice). ## Hoody AI Search Free web search for code running in a computer, where search is available, within the search limits of the computer's server. Example: [Web search with Hoody AI Search](/foundation/hoody-ai/usage/#web-search-with-hoody-ai-search). | Item | Value | |---|---| | Request | `POST https://ai.hoody.com/api/v1/coding_plan/search` with a JSON body holding one non-empty string, `{"q": "tokio select with timeout"}`. There is no `model` | | Response | A JSON object whose results are in the `organic` array. An entry usually has `title`, `link` and `snippet`, sometimes more. A missing or empty `organic` means no results. Read the fields you use and ignore the rest | | Credential | The computer's own `computer-…` token. Any other key gets `400 hoody_search_requires_computer` | | Query too long | `400 invalid_body`; the message gives the limit in bytes | | Limit ran out | `429` with a `Retry-After` header and `retry_after_seconds` | The `429` body's `limit` names the limit: | `limit` | Code | Counts | |---|---|---| | `search_per_day` | `hoody_free_search_daily_limit` | Searches per day | | `per_minute_searches` | `hoody_free_search_minute_limit` | Searches per minute | | `search_attempts_per_day` | `hoody_free_search_daily_limit` | Each search actually sent on, retries included, up to three times the daily limit. A request refused before sending counts nothing, and one request can use more than one attempt | | `concurrent` | | A search in flight also counts toward your chat requests at once (`limit: "concurrent"`) | ## Free limits Hoody Free, Hoody Voice, Hoody AI Search and Hoody Decide cost nothing and are limited per server, by that server's plan. | Model | Limits | |---|---| | Hoody Free | Tokens per minute, hour and day; prompt tokens served from cache, per minute, hour and day; requests at once; tokens per second | | Hoody AI Search | Searches per day and search attempts per day; on some servers also searches per minute | | Hoody Voice | Speech characters per day and speech requests per minute; transcription seconds per day and transcription requests per minute; requests at once, speech and transcription together | | Hoody Decide | Requests per minute and per day, questions per day, input tokens per day, requests at once: [Hoody Decide limits](/foundation/hoody-ai/decisions/#limits-and-cost) | - **Plans:** the Free plan's limits are the base, and a higher plan raises them. A plan's AI allowance is shown as a multiple of Free: ×1 is the Free level, and ×2 or more is a higher allowance. A paid plan reports it as `resources.ai_multiplier` in `GET /api/v1/subserver-plans`. - **Per model:** the allowance describes the plan as a whole. Each free model's limits are set separately and need not rise by exactly that factor. Rented machines also get a raised allowance. - **Numbers:** not listed here, because they can change. To see where a server stands, [read how much is used](/foundation/hoody-ai/models/#see-how-much-you-have-used); a refused request names the limit it reached. - **Windows:** minute, hour and day limits are rolling windows; nothing resets at midnight. - **Servers:** limits of different servers never add up. Each server has only its own plan's limits, and what one server leaves unused does not move to another. - **Refusals:** every quota refusal is a `429` whose `error.limit` names the exact limit that applied. When waiting can help, it also carries `retry_after_seconds` and a `Retry-After` header for when to try again. Other refusals use other statuses (for example `400`, `413`, `422`, `502` or `503`). - **Too large to wait for:** a voice request larger than a whole day's allowance (text to speak or audio to transcribe) gets neither `retry_after_seconds` nor `Retry-After`, because waiting does not help. ## Free usage reading `GET https://api.hoody.com/api/v1/users/me/free-ai-usage`, or `hoody ai freeusage get` from the CLI. `-o wide` adds `speech`, `transcription` and when the reading was taken, `-o json` prints the `data` object of the response below, and `--watch` redraws the list on a terminal. ```json { "statusCode": 200, "message": "Free AI usage retrieved", "data": { "servers": [ { "server": { "id": "6612aa0b0c0d0e0f10111213", "name": "node-example-1" }, "status": "ok", "as_of": "2026-10-21T03:14:00Z", "lanes": { "chat": { "status": "ok", "percent_used": 40, "resets_at": "2026-10-21T04:05:00Z" }, "decisions": { "status": "ok", "percent_used": 0, "resets_at": null }, "search": { "status": "ok", "percent_used": 100, "resets_at": "2026-10-21T03:25:00Z" }, "speech": { "status": "off" }, "transcription": { "status": "off" } } }, { "server": { "id": "6612aa0b0c0d0e0f10111299", "name": "node-example-2" }, "status": "unavailable" } ], "truncated": false } } ``` | Field | Meaning | |---|---| | `data.servers[].server` | The server's `id` and `name`, as your server list shows them | | `status` | `ok` when a reading was taken; `unavailable` when none could be taken right now. An `unavailable` entry has no reading, so try again later | | `as_of` | When the reading was taken, in UTC to the minute. Calls close together can return the same reading | | `lanes` | One entry per free model ([lanes](#lanes)). A lane reads `{"status": "off"}` when that model is not available on the server right now, with no reading; otherwise it reads `"status": "ok"` with the two fields below | | `percent_used` | How much of the lane's most-used hourly or daily limit is used, rounded down to a multiple of 10 from `0` to `100`. `100` means a limit is reached. Per-minute limits and requests at once are not part of it, so a request can still get `429` while the reading is below `100` | | `resets_at` | `null` at `0`, or when no reset time is known. Otherwise, below `100`, about when the use counted now will have left that limit's rolling window; at `100`, about when the lane accepts requests again. Rounded up to the next 5 minutes, and an estimate, not a promise: further use moves it | | `truncated` | `true` when you own more servers than one response lists; the list is then incomplete | | Lane | Model | |---|---| | `chat` | Hoody Free (`hoody-ai/hoody-free`) | | `decisions` | Hoody Decide (`hoody-ai/hoody-decide`) | | `search` | Hoody AI Search | | `speech` | Hoody Voice text to speech (`hoody-ai/hoody-tts`) | | `transcription` | Hoody Voice speech to text (`hoody-ai/hoody-stt`) | - **Whose use counts:** the reading is one number per lane for the whole server. Computers that other people run on your server use the same limits and count toward it, and it never shows who used what. Computers you run on a server someone else owns count toward that owner's reading, and that server is not listed for you. A rented machine is listed once: smaller servers divided from it share its limits and its reading. - **What it shows:** steps and rounded times only. The `429` body of a refused AI request is what names the limit that applied. | Status | Meaning | |---|---| | `200` | Success. Server entries that read `unavailable` have no reading for those servers | | `401` | No valid sign-in | | `403` | An auth token that lacks `computers.read` or is limited to realms | | `429` | Called too often. Wait for `Retry-After` before calling again | | `500` | The request itself failed; worth retrying later | ## Model features - **Streaming:** all text models support streaming responses. The endpoint returns Server-Sent Events (SSE) for real-time token streaming. - **Function calling:** the gateway forwards `tools` unchanged, so function calling works with any catalog model whose provider supports it. Check the model's own capabilities before relying on it. The example below names Hoody Free, which needs a free model that supports tools to be available when you send it. Run it from inside a computer with AI enabled, with `Authorization: Bearer computer-1`. - **Vision:** models with image understanding advertise `"image"` in `input_modalities` ([query](#catalog-queries)). The following body is a template: replace `` with a current catalog `id` whose `input_modalities` contains `"image"`, and `` with a reachable image URL before sending it. ```json { "model": "", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "What is in this image?" }, { "type": "image_url", "image_url": { "url": "" } } ] } ] } ``` ## Route requests by task Match the model to task complexity: simple tasks to fast, cheap models; complex reasoning to premium models; bulk operations to batched requests with economical models. For example, classify with a cheap model, then pick the model by category: ```typescript // Replace these placeholders with three ids selected from the live catalog after sorting on pricing.prompt const CHEAP = ''; const MID = ''; const PREMIUM = ''; // Classification: Use cheap model const category = await classifyWithModel(CHEAP, text); // Based on category, use appropriate model const modelMap = { 'simple': CHEAP, 'moderate': MID, 'complex': PREMIUM }; const response = await processWithModel(modelMap[category], text); ``` ## Control cost per computer Hoody AI allows up to 16 simultaneous requests per computer; additional requests return `429` with `too many concurrent requests`. You control access by enabling or disabling [AI access per computer](/foundation/hoody-ai/security/#per-computer-permissions): ```bash # Check which computers on the first page have AI enabled # Returns one page (50 per page, 100 max with ?limit=); loop ?page= for a full audit curl "https://api.hoody.com/api/v1/computers/?page=1&limit=100" \ -H "Authorization: Bearer $HOODY_TOKEN" \ | jq '.data.computers[] | select(.ai == true) | {id, name, ai}' # Enable/disable AI per computer to control access curl -X PUT "https://api.hoody.com/api/v1/computers/$COMPUTER_ID" \ -H "Authorization: Bearer $HOODY_TOKEN" \ -H "Content-Type: application/json" \ -d '{"ai": false}' # Disable AI to prevent usage ``` The free models (Hoody Free, Hoody Voice, Hoody AI Search and Hoody Decide) also have per-server limits, shared by all computers on the same server: see [free limits](#free-limits), and the [free usage reading](#free-usage-reading) for a reading per server. ## Troubleshooting | Symptom | Cause | What to do | |---|---|---| | "Model not found" error | Invalid model identifier | Verify the exact model string: `"model": "minimax/minimax-m3.1-flash"`, not `"model": "minimax-m3.1-flash"` | | `429 Too Many Requests` | A rate limit | Implement [exponential backoff](/foundation/hoody-ai/usage/#rate-limiting-and-retries). For the free models, more computers on the same server do not help, because they share that server's limits; [check how much of them is used](/foundation/hoody-ai/models/#see-how-much-you-have-used). For a `concurrent` limit, send fewer requests at once; for a token limit, use fewer tokens. Wait for `Retry-After` before retrying | | `402`, code `hoody_budget_exceeded` | The model needs Hoody AI credits | Use `hoody-ai/hoody-free` or another free model. Adding Hoody AI credits is coming soon | | Slow responses | Long wait times for responses | Use streaming (`"stream": true`) for immediate feedback. Switch to a faster, smaller model from the catalog. Reduce the `max_tokens` parameter. Simplify prompts |