docs: reconcile cookbook agent files + recipes with the v4 SDK [DRG-490] - #10
Merged
Conversation
The agents TTS reference labelled its TypeScript and Python snippets @speechify/api v3 / speechify-api v3, but the repo is already on v4 (catalog pins @speechify/api 4.0.1; Python recipes pin speechify-api>=4.0.0). The snippet code already uses the v4 snake_case surface, so this is a label-only fix. Keeps the ask-speechify knowledge engine from surfacing v3 as the current SDK.
…DRG-490] The v3->v4 SDK migration flipped request/response fields to snake_case, but two references were missed: - quickstart README described the call params as voiceId/audioFormat - speech-marks comment referenced speechMarks.chunks The recipe code was already correct (voice_id, audio_format, response.speech_marks); only the prose/comment lagged.
luke-speechify
changed the title
Adversarial review of agents/*.md against the v4 SDK type defs: - speechify-tts.md: input char limit was stated as ~20,000 for all requests, but audio.speech caps at 2,000; 20,000 is the stream limit. Split the limit per endpoint and link api-limits. - monorepo.md: products table said 'v2 SDKs'; the repo is on v4. - maintenance.md + CONTRIBUTING.md: dropped dangling references to agents/voice-agents.md, which does not exist.
luke-speechify
changed the title
luke-speechify
marked this pull request as ready for review
September 9, 2026 22:00
luke-speechify
deleted the
lukeoliff/drg-490-cookbook-fix-stale-v3-sdk-label-in-agentsspeechify-ttsmd
branch
September 9, 2026 22:05
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.
What
Adversarial review of the cookbook's
agents/*.md(and adjacent docs) against the actual v4 SDK type definitions — npm@speechify/api4.0.1, pypispeechify-api4.0.0 — plus the server's char-limit constants. Fixes every claim that contradicted reality. Docs-only; no recipe code changed.Stale version labels / references
agents/speechify-tts.md— snippets labelled@speechify/apiv3 /speechify-apiv3 → v4agents/monorepo.md— products table said "TypeScript + Python on v2 SDKs" → v4Wrong SDK field/param casing (v3-era camelCase the v4 migration missed)
recipes/audio/typescript/sdk/quickstart/README.md— described params asvoiceId,audioFormat→voice_id,audio_formatrecipes/audio/typescript/sdk/speech-marks/src/index.ts— commentspeechMarks.chunks→speech_marks.chunksCorrectness
agents/speechify-tts.md—inputwas documented as "~20,000 characters per request", butaudio.speechcaps at 2,000; 20,000 is the stream limit. Split per endpoint and linked api-limits.Dead references
agents/maintenance.md+CONTRIBUTING.md— dropped references toagents/voice-agents.md, which does not exist.Verified correct (no change)
Method names (
audio.speech/stream/streamWithTimestamps,voices.list/create/get/delete/downloadSample), snake_case fields in both SDKs,AsyncSpeechifyexport, package/import names, base URLhttps://api.speechify.ai, model defaults, and theconst voiceIdlocals (JS variable names, correctly passingvoice_id:). Generated docs examples (Fern / docs.speechify.ai) carry no version pin orv3.Follow-up to DRG-475. Linear: DRG-490