# Speechmatics Batch API Client
[](https://pypi.org/project/speechmatics-batch/)
Async Python client for Speechmatics Batch API.
## Features
- Async API client with comprehensive error handling
- Type hints throughout for better IDE support
- Environment variable support for credentials
- Easy-to-use interface for submitting, monitoring, and retrieving transcription jobs
- Full job configuration support with all Speechmatics features
- Intelligent transcript formatting with speaker diarization
- Support for multiple output formats (JSON, TXT, SRT)
## Installation
```bash
pip install speechmatics-batch
```
## Usage
### Quick Start
```python
import asyncio
from speechmatics.batch import AsyncClient
async def main():
# Create a client using environment variable SPEECHMATICS_API_KEY
async with AsyncClient() as client:
# Simple transcription
result = await client.transcribe("audio.wav")
print(result.transcript_text)
asyncio.run(main())
```
## JWT Authentication
For enhanced security, use temporary JWT tokens instead of static API keys.
JWTs are short-lived (60 seconds default) and automatically refreshed:
```python
from speechmatics.batch import AsyncClient, JWTAuth
auth = JWTAuth("your-api-key", ttl=60)
async with AsyncClient(auth=auth) as client:
# Tokens are cached and auto-refreshed automatically
result = await client.transcribe("audio.wav")
print(result.transcript_text)
```
Ideal for long-running applications or when minimizing API key exposure.
See the [authentication documentation](https://docs.speechmatics.com/introduction/authentication) for more details.
### Basic Job Workflow
```python
import asyncio
from speechmatics.batch import AsyncClient, JobConfig, JobType, TranscriptionConfig
async def main():
# Create client with explicit API key
async with AsyncClient(api_key="your-api-key") as client:
# Configure transcription
config = JobConfig(
type=JobType.TRANSCRIPTION,
transcription_config=TranscriptionConfig(
language="en",
enable_entities=True,
diarization="speaker"
)
)
# Submit job
job = await client.submit_job("audio.wav", config=config)
print(f"Job submitted: {job.id}")
# Wait for completion
result = await client.wait_for_completion(
job.id,
polling_interval=2.0,
timeout=300.0
)
# Access results
print(f"Transcript: {result.transcript_text}")
print(f"Confidence: {result.confidence}")
asyncio.run(main())
```
### Advanced Configuration
```python
import asyncio
from speechmatics.batch import (
AsyncClient,
JobConfig,
JobType,
OperatingPoint,
TranscriptionConfig,
TranslationConfig,
SummarizationConfig
)
async def main():
async with AsyncClient(api_key="your-api-key") as client:
# Advanced job configuration
config = JobConfig(
type=JobType.TRANSCRIPTION,
transcription_config=TranscriptionConfig(
language="en",
operating_point=OperatingPoint.ENHANCED,
enable_entities=True,
diarization="speaker",
),
translation_config=TranslationConfig(target_languages=["es", "fr"]),
summarization_config=SummarizationConfig(
content_type="conversational", summary_length="brief"
),
)
result = await client.transcribe("audio.wav", config=config)
# Access advanced features
if result.summary:
print(f"Summary: {result.summary}")
if result.translations:
print(f"Translations: {result.translations}")
asyncio.run(main())
```
### Manual Job Management
```python
import asyncio
from speechmatics.batch import AsyncClient, JobStatus
async def main():
async with AsyncClient() as client:
# Submit job
job = await client.submit_job("audio.wav")
# Check job status
job_details = await client.get_job_info(job.id)
print(f"Status: {job_details.status}")
# Wait for completion manually
while job_details.status == JobStatus.RUNNING:
await asyncio.sleep(5)
job_details = await client.get_job_info(job.id)
if job_details.status == JobStatus.DONE:
# Get transcript
transcript = await client.get_transcript(job.id)
print(transcript.transcript_text)
else:
print(f"Job failed with status: {job_details.status}")
asyncio.run(main())
```
### Different Output Formats
```python
import asyncio
from speechmatics.batch import AsyncClient, FormatType
async def main():
async with AsyncClient() as client:
job = await client.submit_job("audio.wav")
# Get JSON format (default)
json_result = await client.get_transcript(job.id, format_type=FormatType.JSON)
print(json_result.transcript_text)
# Get plain text
txt_result = await client.get_transcript(job.id, format_type=FormatType.TXT)
print(txt_result)
# Get SRT subtitles
srt_result = await client.get_transcript(job.id, format_type=FormatType.SRT)
print(srt_result)
asyncio.run(main())
```
### Error Handling
```python
import asyncio
from speechmatics.batch import (
AsyncClient,
BatchError,
AuthenticationError,
JobError,
TimeoutError
)
async def main():
try:
async with AsyncClient() as client:
result = await client.transcribe("audio.wav", timeout=120.0)
print(result.transcript_text)
except AuthenticationError:
print("Invalid API key")
except BatchError as e:
print(f"Job submission failed: {e}")
except JobError as e:
print(f"Job processing failed: {e}")
except TimeoutError as e:
print(f"Job timed out: {e}")
except FileNotFoundError:
print("Audio file not found")
asyncio.run(main())
```
### Connection Configuration
```python
import asyncio
from speechmatics.batch import AsyncClient, ConnectionConfig
async def main():
# Custom connection settings
config = ConnectionConfig(
url="https://asr.api.speechmatics.com/v2",
api_key="your-api-key",
connect_timeout=30.0,
operation_timeout=600.0
)
async with AsyncClient(conn_config=config) as client:
result = await client.transcribe("audio.wav")
print(result.transcript_text)
asyncio.run(main())
```
## Logging
The client supports logging with job id tracing for debugging. To increase logging verbosity, set `DEBUG` level in your example code:
```python
import logging
import sys
logging.basicConfig(
level=logging.DEBUG,
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
handlers=[
logging.StreamHandler(sys.stdout)
]
)
```
## Environment Variables
The client supports the following environment variables:
- `SPEECHMATICS_API_KEY`: Your Speechmatics API key
- `SPEECHMATICS_BATCH_URL`: Custom API endpoint URL (optional)
Raw data
{
"_id": null,
"home_page": null,
"name": "speechmatics-batch",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "speechmatics, speech-to-text, batch, transcription, api",
"author": null,
"author_email": "Speechmatics <support@speechmatics.com>",
"download_url": "https://files.pythonhosted.org/packages/55/ce/92562a4a967a9bc6961504a3efa2756862a51351c351c9399d7698b8e209/speechmatics_batch-0.4.1.tar.gz",
"platform": null,
"description": "# Speechmatics Batch API Client\n\n[](https://pypi.org/project/speechmatics-batch/)\n\n\nAsync Python client for Speechmatics Batch API.\n\n## Features\n\n- Async API client with comprehensive error handling\n- Type hints throughout for better IDE support\n- Environment variable support for credentials\n- Easy-to-use interface for submitting, monitoring, and retrieving transcription jobs\n- Full job configuration support with all Speechmatics features\n- Intelligent transcript formatting with speaker diarization\n- Support for multiple output formats (JSON, TXT, SRT)\n\n## Installation\n\n```bash\npip install speechmatics-batch\n```\n\n## Usage\n\n### Quick Start\n\n```python\nimport asyncio\nfrom speechmatics.batch import AsyncClient\n\nasync def main():\n # Create a client using environment variable SPEECHMATICS_API_KEY\n async with AsyncClient() as client:\n # Simple transcription\n result = await client.transcribe(\"audio.wav\")\n print(result.transcript_text)\n\nasyncio.run(main())\n```\n\n## JWT Authentication\n\nFor enhanced security, use temporary JWT tokens instead of static API keys.\nJWTs are short-lived (60 seconds default) and automatically refreshed:\n\n```python\nfrom speechmatics.batch import AsyncClient, JWTAuth\n\nauth = JWTAuth(\"your-api-key\", ttl=60)\n\nasync with AsyncClient(auth=auth) as client:\n # Tokens are cached and auto-refreshed automatically\n result = await client.transcribe(\"audio.wav\")\n print(result.transcript_text)\n```\n\nIdeal for long-running applications or when minimizing API key exposure.\nSee the [authentication documentation](https://docs.speechmatics.com/introduction/authentication) for more details.\n\n### Basic Job Workflow\n\n```python\nimport asyncio\nfrom speechmatics.batch import AsyncClient, JobConfig, JobType, TranscriptionConfig\n\nasync def main():\n # Create client with explicit API key\n async with AsyncClient(api_key=\"your-api-key\") as client:\n\n # Configure transcription\n config = JobConfig(\n type=JobType.TRANSCRIPTION,\n transcription_config=TranscriptionConfig(\n language=\"en\",\n enable_entities=True,\n diarization=\"speaker\"\n )\n )\n\n # Submit job\n job = await client.submit_job(\"audio.wav\", config=config)\n print(f\"Job submitted: {job.id}\")\n\n # Wait for completion\n result = await client.wait_for_completion(\n job.id,\n polling_interval=2.0,\n timeout=300.0\n )\n\n # Access results\n print(f\"Transcript: {result.transcript_text}\")\n print(f\"Confidence: {result.confidence}\")\n\nasyncio.run(main())\n```\n\n### Advanced Configuration\n\n```python\nimport asyncio\nfrom speechmatics.batch import (\n AsyncClient,\n JobConfig,\n JobType,\n OperatingPoint,\n TranscriptionConfig,\n TranslationConfig,\n SummarizationConfig\n)\n\nasync def main():\n async with AsyncClient(api_key=\"your-api-key\") as client:\n\n # Advanced job configuration\n config = JobConfig(\n type=JobType.TRANSCRIPTION,\n transcription_config=TranscriptionConfig(\n language=\"en\",\n operating_point=OperatingPoint.ENHANCED,\n enable_entities=True,\n diarization=\"speaker\",\n ),\n translation_config=TranslationConfig(target_languages=[\"es\", \"fr\"]),\n summarization_config=SummarizationConfig(\n content_type=\"conversational\", summary_length=\"brief\"\n ),\n )\n\n result = await client.transcribe(\"audio.wav\", config=config)\n\n # Access advanced features\n if result.summary:\n print(f\"Summary: {result.summary}\")\n if result.translations:\n print(f\"Translations: {result.translations}\")\n\nasyncio.run(main())\n```\n\n### Manual Job Management\n\n```python\nimport asyncio\nfrom speechmatics.batch import AsyncClient, JobStatus\n\nasync def main():\n async with AsyncClient() as client:\n\n # Submit job\n job = await client.submit_job(\"audio.wav\")\n\n # Check job status\n job_details = await client.get_job_info(job.id)\n print(f\"Status: {job_details.status}\")\n\n # Wait for completion manually\n while job_details.status == JobStatus.RUNNING:\n await asyncio.sleep(5)\n job_details = await client.get_job_info(job.id)\n\n if job_details.status == JobStatus.DONE:\n # Get transcript\n transcript = await client.get_transcript(job.id)\n print(transcript.transcript_text)\n else:\n print(f\"Job failed with status: {job_details.status}\")\n\nasyncio.run(main())\n```\n\n### Different Output Formats\n\n```python\nimport asyncio\nfrom speechmatics.batch import AsyncClient, FormatType\n\nasync def main():\n async with AsyncClient() as client:\n job = await client.submit_job(\"audio.wav\")\n\n # Get JSON format (default)\n json_result = await client.get_transcript(job.id, format_type=FormatType.JSON)\n print(json_result.transcript_text)\n\n # Get plain text\n txt_result = await client.get_transcript(job.id, format_type=FormatType.TXT)\n print(txt_result)\n\n # Get SRT subtitles\n srt_result = await client.get_transcript(job.id, format_type=FormatType.SRT)\n print(srt_result)\n\nasyncio.run(main())\n```\n\n### Error Handling\n\n```python\nimport asyncio\nfrom speechmatics.batch import (\n AsyncClient,\n BatchError,\n AuthenticationError,\n JobError,\n TimeoutError\n)\n\nasync def main():\n try:\n async with AsyncClient() as client:\n result = await client.transcribe(\"audio.wav\", timeout=120.0)\n print(result.transcript_text)\n\n except AuthenticationError:\n print(\"Invalid API key\")\n except BatchError as e:\n print(f\"Job submission failed: {e}\")\n except JobError as e:\n print(f\"Job processing failed: {e}\")\n except TimeoutError as e:\n print(f\"Job timed out: {e}\")\n except FileNotFoundError:\n print(\"Audio file not found\")\n\nasyncio.run(main())\n```\n\n### Connection Configuration\n\n```python\nimport asyncio\nfrom speechmatics.batch import AsyncClient, ConnectionConfig\n\nasync def main():\n # Custom connection settings\n config = ConnectionConfig(\n url=\"https://asr.api.speechmatics.com/v2\",\n api_key=\"your-api-key\",\n connect_timeout=30.0,\n operation_timeout=600.0\n )\n\n async with AsyncClient(conn_config=config) as client:\n result = await client.transcribe(\"audio.wav\")\n print(result.transcript_text)\n\nasyncio.run(main())\n```\n\n## Logging\n\nThe client supports logging with job id tracing for debugging. To increase logging verbosity, set `DEBUG` level in your example code:\n\n```python\nimport logging\nimport sys\n\nlogging.basicConfig(\n level=logging.DEBUG,\n format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',\n handlers=[\n logging.StreamHandler(sys.stdout)\n ]\n)\n```\n\n## Environment Variables\n\nThe client supports the following environment variables:\n\n- `SPEECHMATICS_API_KEY`: Your Speechmatics API key\n- `SPEECHMATICS_BATCH_URL`: Custom API endpoint URL (optional)\n",
"bugtrack_url": null,
"license": null,
"summary": "Speechmatics Batch API Client",
"version": "0.4.1",
"project_urls": {
"documentation": "https://docs.speechmatics.com/",
"homepage": "https://github.com/speechmatics/speechmatics-python-sdk",
"issues": "https://github.com/speechmatics/speechmatics-python-sdk/issues",
"repository": "https://github.com/speechmatics/speechmatics-python-sdk"
},
"split_keywords": [
"speechmatics",
" speech-to-text",
" batch",
" transcription",
" api"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6040a3620a3d451e54f7eebf4135559ca472583bc5fb212f2f865f8a738bf9a3",
"md5": "f9ce44cea851ee01ab18f77fda9ec704",
"sha256": "f79811b5aafef6cf02ca0c255862d931080dbceb12ad250ac5ed8d3bdacf5fd5"
},
"downloads": -1,
"filename": "speechmatics_batch-0.4.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f9ce44cea851ee01ab18f77fda9ec704",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 22550,
"upload_time": "2025-08-29T07:26:03",
"upload_time_iso_8601": "2025-08-29T07:26:03.301807Z",
"url": "https://files.pythonhosted.org/packages/60/40/a3620a3d451e54f7eebf4135559ca472583bc5fb212f2f865f8a738bf9a3/speechmatics_batch-0.4.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "55ce92562a4a967a9bc6961504a3efa2756862a51351c351c9399d7698b8e209",
"md5": "0fc81b838e267fe76a6be028b400e3e1",
"sha256": "1ee26d35f84615d48dcb1ec2d60d47d6b1f2642e05daa6e1bfc8dc6659105e2d"
},
"downloads": -1,
"filename": "speechmatics_batch-0.4.1.tar.gz",
"has_sig": false,
"md5_digest": "0fc81b838e267fe76a6be028b400e3e1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 21861,
"upload_time": "2025-08-29T07:26:04",
"upload_time_iso_8601": "2025-08-29T07:26:04.425829Z",
"url": "https://files.pythonhosted.org/packages/55/ce/92562a4a967a9bc6961504a3efa2756862a51351c351c9399d7698b8e209/speechmatics_batch-0.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-29 07:26:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "speechmatics",
"github_project": "speechmatics-python-sdk",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "speechmatics-batch"
}
JSON
