This reference describes capslane 0.2.0. Import CapslaneClient and CapslaneError from capslane. Python 3.10 or later is required. The base SDK uses the standard library; the optional LangChain integration is documented separately. The HTTP response contract defines response fields, HTTP statuses and accounting.
CapslaneClient(api_key: str, base_url: str = "https://capslane.com", timeout: float = 20.0)api_key is required and must contain a workspace key. An empty or whitespace-only value raises ValueError. base_url and timeout are optional. timeout is the timeout in seconds for each HTTP request. Construction performs no network call and does not validate the key remotely. Keep it in the server environment.
client.transcript(url, *, lang=None, text=None, chunk_size=None, mode=None)Only url is required. All other arguments are optional and keyword-only. mode=None means the SDK omits mode from the HTTP query; the API uses auto. Explicit values are native, auto and generate. text=None omits text, so the API uses false. chunk_size maps to the HTTP parameter chunkSize.
The return value is a dictionary. An immediate response contains content as a list of segment dictionaries, or a string when text=True. A generation response contains jobId and requires subsequent polling. The submission method does not wait for completion.
client.transcript_job(job_id: str)This method performs one GET /v1/transcript/{jobId} and returns its dictionary. Successful reads use HTTP 200 even for pending, failed or cancelled jobs. When content is available, it is always a list of segments and requestId is required. A completed result also has jobId; inspect content first.
A completed job whose stored result has expired can lack content. It is not a ready transcript. A valid unknown job ID, including one from another workspace, returns job_not_found. These cases differ from a failed generation and from a local wait timeout.
client.wait_for_transcript(job, *, interval=2.0, timeout=1200)job accepts a saved job ID string or an accepted-job dictionary containing jobId. interval and timeout are optional keyword-only numbers in seconds. The default timeout is 1200 seconds, or twenty minutes. timeout=None is not supported: the implementation adds timeout to the monotonic clock and therefore requires a number.
The helper sleeps for interval seconds before each status read. It returns a dictionary when content is present. failed or cancelled raises CapslaneError with status 422. Reaching the polling deadline raises status 504 and code processing_timeout. The helper does not cancel the server job or submit a replacement.
The constructor timeout applies to each network request. The wait timeout is a separate polling window checked between iterations; a sleep or request already in progress can extend beyond it. For a single shared deadline across HTTP operations, use the bounded HTTP example. Preserve the accepted job ID so a later call can resume.
CapslaneError has status, code, message and request_id. HTTP errors map the response error field to code and requestId to request_id. request_id may be absent on locally created exceptions. This does not make requestId optional in a successful HTTP job response.
URLError is converted to CapslaneError with status 0 and code network_error. Other transport and response decoding errors can surface separately. Read code before retrying; allowance errors and temporary failures require different handling. Current SDK exceptions do not expose Retry-After.
After a local timeout, check the saved ID with transcript_job. Starting transcript again creates a new submission that can reserve another unit. The package provides no cancel-job or account method. Closing a client process does not cancel a server job.