Document the sync API contract and fix onboarding gaps#9
Open
aurpsis-aai wants to merge 3 commits into
Open
Conversation
- Add sync/API.md — the request/response contract (config fields, error envelope, response shape) the README referenced but never shipped. - Correct the auth wording: a non-empty Authorization header is required (any value accepted); missing/empty returns 401. - State the accepted audio formats (16-bit PCM WAV or raw S16LE PCM); compressed formats return 415. - Note that unknown config fields are silently ignored. - Bundle example_audio_file.wav and make the example script default to it. - Rewrite the example docstring for a customer audience. - Add a troubleshooting note for the harmless deep_gemm warmup traceback.
The literal value in the curl -H 'Authorization: ...' examples pattern-matches security scanners' hardcoded-credential rules. Since the self-hosted service accepts any non-empty value, use 'any value works' — which also documents the semantics inline.
| @@ -0,0 +1,211 @@ | |||
| # Sync API reference (self-hosted) | |||
Contributor
There was a problem hiding this comment.
Do you think we should provide this vs reference the docs?
The README carries the quickstart contract (auth, formats, constraints, config field names) inline; the full option reference belongs in the AssemblyAI documentation rather than a second copy maintained here.
bgotthold-aai
approved these changes
Jul 7, 2026
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
2 participants
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.
Fills the documentation gaps a customer hits when standing up the sync stack for the first time. The README stays the single quickstart reference; the full option reference lives in the online AssemblyAI documentation.
What's changed
Authorizationheader (any value passes; missing or empty returns401). The README previously said the service "accepts all requests", which breaks for deployments whose proxy strips the header.audio/wav) or raw S16LE PCM (audio/pcm); compressed formats (MP3, Opus, …) return415. Previously the docs listed bit-depth/sample-rate constraints but never said which container formats are accepted.configfields and note that unknown fields are silently ignored, with a warning to check spelling — a typo'd option does nothing rather than erroring in the current release. Full option details are in the AssemblyAI documentation.sync/example/example_audio_file.wavand defaulttranscribe_file.pyto it, so the quickstart works with zero extra assets (the streaming stack already ships one; sync didn't).deep_gemmAssertionErrortraceback during warmup is harmless (optional-kernel probe with fallback).🤖 Generated with Claude Code