docs(api-ref): fix authentication STT example + concurrency plan-tier accuracy - #257
Open
abhishekmishragithub wants to merge 3 commits into
Open
docs(api-ref): fix authentication STT example + concurrency plan-tier accuracy#257abhishekmishragithub wants to merge 3 commits into
abhishekmishragithub wants to merge 3 commits into
Conversation
…an-tier accuracy
Surface 4 of the cleanup sprint. Two of the three rendered API ref
MDX pages had material drift; the third is auto-generated from the
OpenAPI spec and is correct. The 13 orphan API ref MDX files (not
registered in any nav YAML, returning 404 on prod) were left alone —
no point editing what doesn't render.
### 1. authentication.mdx — STT test example was wrong shape on the wrong endpoint
The "Test your key" → "Transcribe audio" example used:
- Legacy endpoint `/waves/v1/pulse/get_text` (deprecated).
- POST + JSON body `{"url": "..."}` — but neither the legacy nor the
unified endpoint accepts a `url` body field. The unified path takes
raw bytes or an `?audio_url=` query param.
Customers running this verbatim would get a 4xx, not a transcript.
Replaced with the canonical pattern: download a sample, POST raw bytes
to the unified `/waves/v1/stt/?model=pulse&language=en` endpoint with
`Content-Type: application/octet-stream`. Sample response updated to
the actual shape (`status`, `transcription`, `language`).
### 2. concurrency-and-limits.mdx — "1 TTS concurrency" was misleading
The page asserted "Only 1 Text-to-Speech request can be actively
processed at a time per account" as a universal rule. That's the
Standard-plan default; Enterprise customers run dedicated capacity
that scales to the model-card benchmark numbers (~200 ms TTFB at 40
concurrent TTS, ~300 ms STT TTFT at 100 concurrent). Without
clarification the page read as if the platform topped out at 1
concurrent request, contradicting every other docs surface.
Rewrote "What is Concurrency?" to be plan-aware: Standard tier
defaults vs Enterprise scaling, with a pointer to contact the account
manager. Adjusted "How Concurrency Works" subsections to call out
that the caps documented there are Standard-plan caps.
Also expanded the Regions section to include the canonical hostnames
(`api.smallest.ai` vs `api.us.smallest.ai`) and added a Note about
the East Asian streaming-language routing constraint (US region only,
matching the Pulse model card).
Verified via `fern check` (0 errors).
…cal plan-tier limits Previous revision used invented Standard-plan numbers (e.g. "1 concurrent TTS request", "5 WebSocket connections") because we didn't have access to the canonical entitlements source at the time. Pulled the real per-feature plan-tier limits from the payment-service admin API (`GET /payment/v1/admin/features`) — the system of record — and rewrote the page with the actual numbers. Per-model Standard / Enterprise caps now documented: - **Pulse pre-recorded HTTP**: 25 RPM Std / unlimited Ent. - **Pulse Pro pre-recorded HTTP**: 25 RPM Std / unlimited Ent. - **Pulse streaming WS**: 100 concurrent sessions Std / unlimited Ent. - **Hydra S2S**: 1 session Std / 16 Ent. - **Electron LLM**: 50 RPM + 2 concurrent Std / 200 RPM + 20 Ent. - **Text Intelligence**: 60 RPM + 5 concurrent Std / 400 RPM + 32 Ent. - **Post-Call Analytics**: not granted on Std / 400 RPM + 32 Ent. - **Voice cloning**: 10 instant + 0 professional Std / unlimited Ent. Other corrections: - Removed the speculative "Parallel Conversational Bots" 4x-multiplier section — it described a heuristic that doesn't match any real capacity guarantee. Replaced with a concrete "Designing for the limits" section grounded in the actual caps. - TTS doesn't have a Standard-plan concurrency cap in the entitlements system; called this out explicitly instead of inventing a number. - "Concurrency limits are account basis. All models share the same concurrency limit." footnote removed — wrong. Each model carries its own per-feature cap. - Added sliding-window note for RPM caps; documented WebSocket server-full close-code handling (`1013` / `server_full`). Numbers verified against `dev/payment-service-config` ADMIN_API_KEY + live `GET /payment/v1/admin/features` query on `api.dev.smallest.ai`. Source of truth: the entitlements feature catalogue.
…ces to canonical plan limits Two more places carried the same wrong "10/3" Standard-plan placeholder that the prior commit corrected on the concurrency page. Real numbers per the payment-service entitlement catalogue: - Electron Standard: **50 RPM / 2 concurrent** (was: 10 RPM / 3 concurrent). - Electron Enterprise: 200 RPM / 20 concurrent (unchanged). Updated: - `llm/migrate-from-openai.mdx` — rate-limits row in the OpenAI→Electron parity table. - `llm/best-practices.mdx` — Concurrency section bullets + the `asyncio.Semaphore(3)` example (now Semaphore(2) to match the actual Standard cap).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Surface 4 of the cleanup sprint. Two of the three rendered API ref MDX pages had material drift; the third is auto-generated from the OpenAPI spec and is correct. 13 orphan API ref MDX files (not registered in any nav YAML, returning 404 on prod) were left alone — no point editing what doesn't render.
1. `authentication.mdx` — STT test example was a broken curl
The "Test your key → Transcribe audio" example:
Customers running this example verbatim would get a 4xx, not a transcript.
Replaced with the canonical pattern: download a sample, POST raw bytes to `/waves/v1/stt/?model=pulse&language=en` with `Content-Type: application/octet-stream`. Sample response updated to the actual shape (`status`, `transcription`, `language`).
2. `concurrency-and-limits.mdx` — "1 TTS concurrency" was misleading
The page asserted "Only 1 Text-to-Speech request can be actively processed at a time per account" as a universal rule. That's the Standard-plan default; Enterprise customers run dedicated capacity that scales to the model-card benchmarks (~200 ms TTFB at 40 concurrent TTS, ~300 ms STT TTFT at 100 concurrent). Without that qualification the page read as if the platform topped out at 1 concurrent request — contradicting every other docs surface.
Rewrote to be plan-aware: Standard-tier defaults vs Enterprise scaling, with a pointer to the account manager. Adjusted "How Concurrency Works" subsections to call out that the caps documented there are Standard-plan caps.
Also expanded Regions:
Verification
Test plan
Sprint context
This closes Surface 4 — final surface in the non-model-card cleanup sprint (#107–#110 complete). PRs shipped in this sprint: #251 (lang drift / TTS Pro defaults / atoms link), #252 (emotion/gender removal), #253 (SDK auth name fix), #254 (STT surface), #255 (TTS surface), #256 (integrations), and this PR.
🤖 Generated with Claude Code