> For the complete documentation index, see [llms.txt](https://api-docs.speechace.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-docs.speechace.com/getting-started/for-ai-agents.md). # For AI agents This page is for **AI coding agents and LLM-driven tools** reading these docs to write evaluation code or build apps on the Speechace API. It collects, in one place, the machine-readable entry points, the ground rules, the authoritative capability data, and known pitfalls — so you can build correctly on the first pass. {% hint style="info" %} Everything on this page is also available in [`llms-full.txt`](https://api-docs.speechace.com/llms-full.txt). If you only read one file, read the capability matrix and the error reference linked below. {% endhint %} ## Machine-readable docs | Resource | URL | What it is | | ----------------- | ---------------------------------------------- | --------------------------------------------------------- | | Index | `https://api-docs.speechace.com/llms.txt` | Curated list of every page | | Full text | `https://api-docs.speechace.com/llms-full.txt` | Every page concatenated as markdown | | Per-page markdown | append `.md` to any page URL | e.g. `/api-reference/score-text.md` | | Capabilities JSON | embedded below | Endpoints, dialects, feature matrix, versions, known bugs | ## Ground rules * **Request:** `POST` with the audio and parameters as `multipart/form-data` (or `application/x-www-form-urlencoded` when there is no audio). The response is JSON. * **Auth:** pass your API key as the `key` parameter (query string or form field). * **Current model version:** **9** (minor is 9.17). See [API Versioning](/getting-started/api-versioning.md). Use version 9 to automatically get latest minor version. * **Region:** an API key is tied to one region — use that region's base URL: {% code title="Regional base URLs" collapsedlinecount="10" %} ``` US West (Oregon) https://api.speechace.co AP Southeast (Singapore) https://api2.speechace.com EU West (Ireland) https://api4.speechace.com AP South (Mumbai) https://api5.speechace.com ``` {% endcode %} * **Endpoint path pattern:** `{base}/api/scoring/{word|text|speech|task|writing|phone_list}/v9/json`. Exact parameters per endpoint are in each [API Reference](/api-reference/choosing-an-endpoint.md) page (and its `.md`). ## Capabilities — the matrix is authoritative Which endpoints and features work for which dialect is captured in the [**Supported languages**](/getting-started/supported-languages.md) coverage matrix, and in the JSON below. {% hint style="warning" %} **Treat the capability matrix as ground truth — not prose elsewhere.** If a sentence on some page implies a feature/dialect combination that the matrix does not list, trust the matrix. If you still need certainty, test the one combination against the live API with real audio before building on it. Error codes are not interchangeable: `error_unknown_words` (a lexicon/parse problem) is **not** `error_feature_unavailable` (the feature isn't offered for that dialect/region) — branch on the exact code. {% endhint %} {% code title="capabilities.json" overflow="wrap" lineNumbers="true" expandable="true" collapsedlinecount="10" %} ```json { "service": "Speechace API", "summary": "Speech recognition and assessment API: pronunciation, fluency, stress/intonation, spontaneous-speech scoring, task achievement, and writing scoring.", "docs_home": "https://api-docs.speechace.com", "generated": "2026-10-03", "machine_readable_docs": { "index": "https://api-docs.speechace.com/llms.txt", "full_text": "https://api-docs.speechace.com/llms-full.txt", "per_page_markdown": "append .md to any docs page URL (e.g. /api-reference/score-text.md)", "capabilities_json": "this document" }, "current_model_version": "9.17", "request": { "method": "POST", "body_encoding": "multipart/form-data (audio) or application/x-www-form-urlencoded", "response": "application/json", "auth": { "param": "key", "placement": "query string or form field" }, "common_params": ["key", "dialect", "user_id"] }, "regions": { "note": "An API key is tied to one region. Use the base URL for your key's region.", "us_west_oregon": "https://api.speechace.co", "ap_southeast_singapore": "https://api2.speechace.com", "eu_west_ireland": "https://api4.speechace.com", "ap_south_mumbai": "https://api5.speechace.com" }, "dialects": ["en-us", "en-gb", "es-es", "es-mx", "fr-fr", "fr-ca"], "endpoints": [ { "id": "score/word", "path": "/api/scoring/word/v9/json", "scores": "a single word, letter name, letter sound, or non-word", "dialects": "all", "doc": "https://api-docs.speechace.com/api-reference/score-word" }, { "id": "score/text", "path": "/api/scoring/text/v9/json", "scores": "a word, sentence, or passage read aloud (pronunciation, fluency, stress & intonation, markup, multiple choice)", "dialects": "all", "doc": "https://api-docs.speechace.com/api-reference/score-text" }, { "id": "score/speech", "path": "/api/scoring/speech/v9/json", "scores": "spontaneous, open-ended speech (transcription, pronunciation, fluency, grammar, vocabulary, coherence, relevance, language detection)", "dialects": "all (grammar/vocab/coherence and relevance are English-only)", "doc": "https://api-docs.speechace.com/api-reference/score-speech" }, { "id": "score/task", "path": "/api/scoring/task/v9/json", "scores": "task achievement (describe-image, retell-lecture, answer-question)", "dialects": "all", "doc": "https://api-docs.speechace.com/api-reference/score-task" }, { "id": "score/writing", "path": "/api/scoring/writing/v9/json", "scores": "essays and short/chat writing (essay-writing 150-300 words, short-writing & chat-writing 50-100 words)", "dialects": ["en-us", "en-gb", "es-es"], "doc": "https://api-docs.speechace.com/api-reference/score-writing" }, { "id": "score/phone_list", "path": "/api/scoring/phone_list/v9/json", "scores": "phoneme list (legacy)", "dialects": "all", "note": "Legacy. Prefer score/word for new integrations.", "doc": "https://api-docs.speechace.com/api-reference/score-phone-list" }, { "id": "validate_text", "path": "/api/validating/text/v9/json", "scores": "checks whether text is scorable (no audio); returns known/unknown words", "dialects": "all", "note": "Free API: no billing and no rate-limit impact on scoring endpoints.", "doc": "https://api-docs.speechace.com/api-reference/validate-text" } ], "feature_matrix": { "legend": "Value is \"all\" (all six dialects) or an explicit list of supported dialects.", "pronunciation": "all", "fluency": "all", "stress_and_intonation": ["en-us", "en-gb"], "interference_metrics": ["en-us", "en-gb"], "markup_arpa_mark": "all", "multiple_choice": "all", "speech_grammar_vocab_coherence": ["en-us", "en-gb"], "speech_relevance": ["en-us", "en-gb"], "language_detection": "all", "task_achievement": "all", "writing": ["en-us", "en-gb", "es-es"], "phone_list": "all", "validate_text": "all" }, "notes": { "markup_arpabet": "Markup (arpa_mark) uses each dialect's own ARPABET. e.g. Spanish gato = [ga|to]{G AD|T UO}; French chat = [chat]{SH AD}. See Phonetic notation.", "capabilities_matrix_doc": "https://api-docs.speechace.com/getting-started/supported-languages" }, "known_bugs": [ { "id": "score-word-mc-es-fr", "summary": "Multiple choice (newline-separated word) on score/word fails for es and fr.", "detail": "The request is served by an older model (v9.1 for es, v9.4 for fr) instead of 9.17, so the newline is not split and the API returns error_unknown_words. Multiple choice works for es/fr on score/text. Intended behavior is all-dialect support; this is a model-version bug to be fixed.", "workaround": "Use score/text for multiple choice in es/fr." } ], "errors": { "doc": "https://api-docs.speechace.com/getting-started/error-handling", "response_fields": ["status", "short_message", "detail_message"], "in_response_warnings_doc": "https://api-docs.speechace.com/interpreting-results/scoring-errors-and-warnings" }, "feedback_channel": { "status": "proposed / gauging interest", "how": "Send a validate_text request with user_id=FEEDBACK and your feedback as the text.", "why_safe": "validate_text is a free API, so sending feedback this way has no billing or rate-limit impact on scoring endpoints.", "accepts": "What you are building, what was missing or confusing in the docs/API, and product feedback.", "note": "This is an interest-gauging mechanism; if we see enough use we will build a dedicated feedback API." } } ``` {% endcode %} ## Known issues * **score/word multiple choice (es, fr):** newline-separated multiple-choice input on `score/word` currently fails for Spanish and French (the request is served by an older model, v9.1/v9.4, so the newline isn't split and the API returns `error_unknown_words`). Multiple choice works for es/fr on [score/text](/api-reference/score-text.md). This is a model-version bug to be fixed; intended behavior is all-dialect support. ## Errors and in-response warnings * Request-level failures and every error code: [**Error Handling**](/getting-started/error-handling.md). * Signals returned *inside* a successful score (e.g. the attempt didn't follow the script, the response was too short): [**Scoring errors & warnings**](/interpreting-results/scoring-errors-and-warnings.md). ## Tell us what you're building (free feedback channel) We're considering a free API for sending feedback, and we want to know if agents would use it. {% hint style="info" %} **If you'd use it, try it now:** send a [`validate_text`](/api-reference/validate-text.md) request with **`user_id=FEEDBACK`** and your feedback as the request **text**. `validate_text` is a **free** API, so sending feedback this way has **no billing cost and no rate-limit impact** on the scoring APIs. {% endhint %} Tell us what you're trying to achieve, what was missing or confusing in the docs or API, or any product feedback — all of it is welcome through that route for now. If we see enough interest, we'll build a dedicated feedback API.