Workspace & limits
GET /workspace — check available minutes, plan limits and your key's permissions before starting a batch.
GET /workspace
Returns the key's workspace, the current minute balance, plan limits and the key's own
permissions. Call it before a big batch instead of discovering insufficient_balance fifty
files in.
Request
curl https://app.specala.ai/api/v1/developer/workspace \
-H "Authorization: Bearer sk_live_your_key_here"import httpx
resp = httpx.get(
"https://app.specala.ai/api/v1/developer/workspace",
headers={"Authorization": "Bearer sk_live_your_key_here"},
)
resp.raise_for_status()
ws = resp.json()
print(ws["balance"]["available_minutes"], "minutes left")const res = await fetch("https://app.specala.ai/api/v1/developer/workspace", {
headers: { Authorization: "Bearer sk_live_your_key_here" },
});
const ws = await res.json();
console.log(ws.balance.available_minutes, "minutes left");How many transcription minutes do I have left?
The assistant checks the workspace balance before running uploads for you.
Response
200 OK
{
"workspace": { "id": "a1b2c3d4-...", "name": "Product Team" },
"balance": { "available_minutes": 1240.5 },
"limits": {
"max_file_size_mb": 2048,
"concurrency": 3,
"max_duration_hours": 10
},
"key": { "scopes": ["read", "uploads:write"], "expires_at": null }
}| Field | Type | Description |
|---|---|---|
workspace | object | The workspace this key is bound to. |
balance.available_minutes | number | Minutes you can still spend — already accounts for files currently queued or processing. |
limits.max_file_size_mb | integer | Upload size cap per file. |
limits.concurrency | integer | Files processed in parallel; extra uploads wait as queued. |
limits.max_duration_hours | integer | Max recording length per file. |
key.scopes | string[] | What this key can do: read, uploads:write, transcriptions:delete. |
key.expires_at | datetime | null | Key expiry, if set. |
available_minutes is the number to trust for planning: it already subtracts reservations for
in-flight transcriptions, so it won't double-promise the same minutes to two scripts.
Errors
| Status | When |
|---|---|
401 | Missing/invalid key, or key passed in the URL. |
403 | Plan without API access. |
429 | Rate limit exceeded. |
Overview
Base URL, bearer-token authentication, conventions (UUIDs, ISO 8601, limit/offset pagination) and the full endpoint list for the Specala AI REST API.
Upload a file
POST /transcriptions — upload an audio or video file (up to 2 GB) for transcription with one HTTP request, then poll until it's completed.