Speech

Upload a file to MediaCatch Speech API and get the results

Uploads a file to MediaCatch Speech API.

Completing an upload is safe to repeat for the same file ID, so the SDK retries it: a 409 saying the upload was already completed counts as success, and a 409 saying it is being completed, busy or taken over is retried for up to 10 minutes. Any other failure cancels the upload; see Raises.

Parameters:

Name	Type	Description	Default
fpath	str | Path	Path to the file to upload.	required
api_key	str	API key for the vision API. Defaults to None.	None
quota	str | None	The quota to bill transcription hours from. Can be None if the user only has one quota. Defaults to None.	None
fallback_language	str | None	Overrides the language to transcribe in if language identification fails. If None, uses the default language of the quota. Defaults to None.	None
output_languages	str | None	Which languages to translate transcript to. Defaults to None.	None
topics	list[str] | None	List of speaker topics to predict for each utterance. Defaults to None.	None
summary	bool | None	Whether to summarize the transcript. Defaults to None.	None
max_threads	int	Number of maximum threads. Defaults to 5.	5
max_request_retries	int	Number of maximum retries for chunks, complete and cancel (not the start). Defaults to 3.	3
request_delay	float	Delay between request retries. Defaults to 0.5.	0.5
chunk_size	_type_	Size of each chunk to upload. Defaults to 10010241024.	100 * 1024 * 1024
chunk_upload_timeout	tuple[float, float]	(connect, read) timeout in seconds for uploading a single chunk to storage. Defaults to (10, 300).	(10, 300)
request_timeout	tuple[float, float]	(connect, read) timeout in seconds for every API call except complete (fixed (10, 1800)) and cancel (fixed 30 s). Chunk uploads use chunk_upload_timeout. Defaults to (10, 300).	DEFAULT_REQUEST_TIMEOUT
url	str	URL of the MediaCatch Speech API. Defaults to 'https://api.mediacatch.io/speech'.	'https://api.mediacatch.io/speech'
compress_input	bool	Compress the input file to OGG format (Requires FFMPEG >= 6.1). Defaults to False.	False
sample_rate	int	Sample rate of the audio file. Defaults to 16000.	16000
verbose	bool	Show verbose output. Defaults to True.	True

Returns:

Name	Type	Description
str	str	File ID of the uploaded file.

Raises:

Type

Description

MediacatchAPIError

If the API rejects a request, e.g. when completing the upload fails. An error with a file_id attribute means the upload is not confirmed gone: repeat DELETE /upload/{file_id} on the speech API. 204 or 404: it is gone, upload again. 409 'Upload already completed': it succeeded, use file_id. 409 'Upload is being completed': wait and try again. Any other answer: wait and repeat the DELETE. Without file_id, no upload you can reach was created, so uploading again is safe (if the start's response was lost, the server may keep an orphan nobody can cancel).

Wait for result from a URL.

Parameters:

Name	Type	Description	Default
file_id	str	The file ID to get the result from.	required
url	str	The URL to get the result from.	'https://api.mediacatch.io/speech'
timeout	int	Timeout for waiting in seconds. Defaults to 3600.	3600
delay	int	Delay between each request. Defaults to 10.	10
request_timeout	tuple[float, float]	(connect, read) timeout in seconds for each poll of the result URL. Defaults to (10, 300).	DEFAULT_REQUEST_TIMEOUT
verbose	bool	Show verbose output. Defaults to True.	True

Returns:

Type	Description
dict[str, Any] | None	dict[str, Any] | None: Dictionary with the result from the URL or None if failed.