Files

Upload audio once and reuse it across requests with a Spitch file ID.

Spitch file storage lets you upload an audio file once and reuse it by file_id across many requests — instead of re-sending the bytes or hosting the file at a public URL every time. It is especially handy for transcription, where the same recording is often processed more than once.

Reach for file storage when you:

• Transcribe the same audio repeatedly, for example re-running with different special_words or timestamp settings.
• Want to avoid exposing audio at a public URL.
• Process large files and prefer to upload them a single time.

Upload a file

Uploading returns a file object whose file_id you reference in later calls.

Python

from spitch import Spitch

client = Spitch()  # reads SPITCH_API_KEY

with open("meeting.wav", "rb") as f:
    file_meta = client.files.upload(file=f.read())

print(file_meta.file_id)

Use a file in transcription

Pass the file_id as content to reuse an uploaded recording without sending the bytes again.

Python

from spitch import Spitch

client = Spitch()

response = client.speech.transcribe(
    content="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",  # file_id from upload
    language="en",
    timestamp="sentence",
)
print(response.text)

content accepts file bytes, a public audio URL, or a Spitch file_id. See Transcription for the full request shape.

List files

Listing returns your files with a next_cursor you can use to page through results.

Python

from spitch import Spitch

client = Spitch()

page = client.files.list(limit=50)
for file_meta in page.items:
    print(file_meta.file_id, file_meta.original_name)

# Fetch the next page when there are more results
if page.next_cursor:
    next_page = client.files.list(cursor=page.next_cursor)

limit · integer · default: "50"

Maximum number of files to return per page (up to 99).

cursor · string

Pagination cursor taken from a previous response’s next_cursor.

Retrieve file details

Fetch the metadata for a single file by its file_id.

Python

from spitch import Spitch

client = Spitch()

file_meta = client.files.retrieve("182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e")
print(file_meta.status, file_meta.size_bytes)

Download a file

Generate a temporary signed URL to download the stored audio. The link expires after ttl seconds.

Python

from spitch import Spitch

client = Spitch()

url = client.files.download(
    file_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    ttl=300,  # seconds the link stays valid
)
print(url)

ttl · integer · default: "60"

How long the signed URL stays valid, in seconds. Minimum 60, maximum 3600.

Delete a file

Remove a file from storage. This cannot be undone.

Python

from spitch import Spitch

client = Spitch()

result = client.files.delete("182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e")
print(result.status)

Check storage usage

See how much storage you are using and how many files you have.

Python

from spitch import Spitch

client = Spitch()

usage = client.files.usage()
print(f"{usage.num_files} files — {usage.used} of {usage.total}")

File object

Upload, retrieve, and list return file metadata with these fields:

Field	Type	Description
file_id	string (uuid)	Unique identifier. Pass this as content to reuse the file.
status	string	Processing status of the file.
original_name	string | null	The filename supplied at upload, when available.
size_bytes	integer | null	File size in bytes.
uploaded_by	string | null	Identifier of the uploader.
created_at	string (date-time)	When the file was uploaded.

Checking usage returns:

Field	Type	Description
num_files	integer	Number of files in your storage.
used_bytes	integer	Storage used, in bytes.
total_bytes	integer	Total storage available, in bytes.
used	string	Storage used, human-readable (for example 12.4 MB).
total	string	Total storage available, human-readable.

Limits

• Supported audio formats are mp3, wav, m4a, and ogg.
• The maximum file size is 25MB, matching the transcription limit.
• Download links are signed and expire after their ttl (60–3600 seconds).

Ready to put a stored file to work? Head to Transcription, or set up the clients on the SDKs & Libraries page.