File uploads
For a local audio file, request an upload, upload the file using the returned URL and headers when needed, then use uploadId to create a transcription job.
Currently, only audio is accepted, up to 1 GiB (1,073,741,824 bytes). For a local video, extract its audio first. An audio or video file URL can instead be submitted directly in fileUrl.
1. Request an upload
POST/uploadsThe request is free, but your API credit balance must be greater than zero. Use the same API key as for transcription.
curl -X POST https://api.snapany.com/openapi/v1/uploads \
-H "Authorization: Bearer sk_snapany_xxx" \
-H "Content-Type: application/json" \
-d '{"mediaType":"audio","sizeBytes":12345678,"sha256":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"}'
| Parameter | Required | Description |
|---|---|---|
mediaType | Yes | Must be "audio" |
sizeBytes | Yes | Exact original file size in bytes, from 1 to 1,073,741,824 |
sha256 | Yes | SHA-256 of the complete raw file: 64 hexadecimal characters; either case is accepted |
Compute the digest from the file bytes, not from its filename or a base64 representation. Do not change the file after computing its size and digest. Unknown request fields are rejected.
When a PUT is needed, the response is:
{
"uploadId": "abcdefghijklmnopqrstuvwx",
"upload": {
"method": "PUT",
"url": "https://storage.example.com/signed-upload-url",
"headers": {
"Content-Type": "application/octet-stream"
},
"expiresAt": "2026-11-09T12:00:00.000Z"
}
}
The headers shown are illustrative: always use all actual upload.headers returned, including a checksum header when present. expiresAt is a UTC ISO timestamp; the signed URL lasts at most one hour.
If this account already has access to reusable identical content, the response is { "uploadId": "...", "upload": null }. Only upload: null means skip the PUT; a matching local digest alone does not prove that the content is available.
2. PUT the raw audio bytes
When upload is not null, PUT the complete raw file to upload.url, with the exact returned headers. Do not include your SnapAny API key in the PUT request. Send the file itself as the request body, without form fields or base64 encoding.
Keep the signed URL unchanged, including its hostname, path and query parameters. Do not replace it with api.snapany.com or api-cn.snapany.com, and do not follow redirects when uploading. A successful PUT returns a 2xx status. There is no separate completion request to make.
A single PUT cannot resume partway through a file. If it fails, resend the complete file while the URL remains valid. After it expires, request another upload; the response will say whether the PUT can be skipped. Upload URL expiry does not immediately delete an already uploaded file. An uploadId is temporary access to that upload, not a permanent file identifier; request another upload if it is no longer usable.
3. Submit the upload for transcription
curl -X POST https://api.snapany.com/openapi/v1/transcriptions \
-H "Authorization: Bearer sk_snapany_xxx" \
-H "Content-Type: application/json" \
-d '{"uploadId":"abcdefghijklmnopqrstuvwx","speakerLabels":false}'
The response contains the transcription job's own id; poll that job every 3–5 seconds. File verification continues in the background. A failed upload check or insufficient credits for the confirmed duration makes the job fail without a paid transcription. Direct upload itself does not charge credits; transcription costs 3 API credits per minute without speaker diarization, or 4 with it.
uploadId is account-owned and may be used by another API key for the same account. It can be used for multiple separately billed jobs, for example with different languages or speaker settings. It is not an idempotency key for job creation. Do not send fileUrl or fileHeaders with it.
Python example
Set SNAPANY_API_KEY in your environment and install requests. This example hashes and uploads meeting.mp3, then submits one transcription job:
import hashlib
import os
from pathlib import Path
import requests
base_url = "https://api.snapany.com/openapi/v1"
api_headers = {"Authorization": f"Bearer {os.environ['SNAPANY_API_KEY']}"}
file_path = Path("meeting.mp3")
sha256 = hashlib.sha256()
with file_path.open("rb") as audio:
for chunk in iter(lambda: audio.read(1024 * 1024), b""):
sha256.update(chunk)
response = requests.post(
f"{base_url}/uploads",
headers=api_headers,
json={
"mediaType": "audio",
"sizeBytes": file_path.stat().st_size,
"sha256": sha256.hexdigest(),
},
timeout=60,
)
response.raise_for_status()
application = response.json()
upload = application["upload"]
if upload is not None:
with file_path.open("rb") as audio:
response = requests.put(
upload["url"],
headers=upload["headers"],
data=audio,
timeout=600,
allow_redirects=False,
)
if not 200 <= response.status_code < 300:
raise RuntimeError(f"Upload failed: HTTP {response.status_code}")
response = requests.post(
f"{base_url}/transcriptions",
headers=api_headers,
json={"uploadId": application["uploadId"], "speakerLabels": False},
timeout=60,
)
response.raise_for_status()
print(response.json())
The creation POST is sent once; the script does not automatically retry it. Use the returned job id with GET /transcriptions/{id} to read the result.
For browser uploads, the browser must be able to PUT to the signed upload URL with every returned header. For AI agents, MCP provides request_file_upload; the client performs the PUT and then calls transcribe.
Upload errors
| Code | Meaning |
|---|---|
insufficient_credits | API credit balance is not positive (HTTP 402) |
upload_not_found | The upload ID does not exist or is unavailable to this account (HTTP 404) |
upload_unavailable | The upload could not currently be confirmed (HTTP 503 for a request error) |
invalid_file | The file is invalid or is not audio |
file_too_large | The file exceeds 1 GiB |
hash_mismatch | The uploaded raw bytes do not match the declared SHA-256 |
Validation may finish after the transcription job is accepted. For failed jobs, read error.code and error.message when polling; otherwise, error is null. Preparation failures can include upload_unavailable or hash_mismatch, and do not charge transcription credits. For a digest mismatch, recompute the digest from the unchanged original file before requesting another upload. If a job ID was returned, query it before considering another creation request. See Error codes.