Uploads

POST /v1/media/uploads stores an audio or image file on the key's account and returns an upload id up_…. The key needs the media:generate scope. An upload is a voice reference in voice (speech), audio (transcription jobs) and from (POST /v1/media/voices), for the account that uploaded the file only.

Parameters

The file is the raw request body, or the part named file of a multipart/form-data body.

Name	Type	Description
body required	file	WAV, MP3, M4A, Ogg, WebM or FLAC audio, or a PNG, JPEG or WebP image, 20 MB at most. The type is read from the file's bytes

Request

curl

curl https://api.albastov.com/v1/media/uploads \
  -H "Authorization: Bearer $ALBASTOV_API_KEY" \
  -H "Content-Type: audio/wav" \
  --data-binary @clip.wav

Python

import json
import os
import urllib.request

with open("clip.wav", "rb") as f:
    req = urllib.request.Request(
        "https://api.albastov.com/v1/media/uploads",
        data=f.read(),
        headers={"User-Agent": "my-app/1.0", "Authorization": f"Bearer {os.environ['ALBASTOV_API_KEY']}", "Content-Type": "audio/wav"},
    )
with urllib.request.urlopen(req, timeout=60) as res:
    print(json.load(res)["id"])

JavaScript

import { readFile } from "node:fs/promises";

const res = await fetch("https://api.albastov.com/v1/media/uploads", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.ALBASTOV_API_KEY}`, "Content-Type": "audio/wav" },
  body: await readFile("clip.wav"),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log((await res.json()).id);

Response

201 with the upload.

Response

{
  "id": "up_Q8mZr3kPwD5nTb7yXc2hLf",
  "content_type": "audio/wav",
  "bytes": 412844,
  "sha256": "9f2c1e7d4b6a8f0e3c5d7b9a1e2f4c6d8b0a2e4f6c8d0b2a4e6f8c0d2b4a6e8f",
  "created_at": "2026-11-03T04:02:58.117Z",
  "source": null
}

Field	Value
`id`	`up_` and 22 random characters
`content_type`	The type read from the file's bytes, such as `audio/wav` or `image/png`
`bytes`	The file's size
`sha256`	The file's SHA-256, hex
`created_at`	RFC 3339 time
`source`	`job:<id>/<i>` when the file was copied from a job result; else `null`

Errors

Errors have the shape {"ok": false, "error": "too-large", "code": "too-large", "message": "..."}.

Status	Code	Meaning
400	`bad-upload`	The file did not arrive whole, or a multipart body has no part named `file`
413	`too-large`	The file is over 20 MB
415	`not-an-image`	The file is neither WAV, MP3, M4A, Ogg, WebM or FLAC audio nor a PNG, JPEG or WebP image

Key, scope and rate-limit errors: Errors.