Audio

The audio routes cover text to speech with POST /v1/audio/speech, in a model's built-in voice or in a saved voice, and speech to text with POST /v1/audio/transcriptions. Both routes take OpenAI's request shape, so OpenAI SDKs work with the base URL changed.

Quick example

The example downloads the reference clip of Narrator A, a synthetic voice, and transcribes the clip with parakeet.

curl -o reference.mp3 \
  https://api.albastov.com/v1/media/samples/reference-848c3d555461736a.mp3

curl https://api.albastov.com/v1/audio/transcriptions \
  -H "Authorization: Bearer $ALBASTAR_API_KEY" \
  -F model=parakeet \
  -F [email protected]

import os

import httpx
from openai import OpenAI

CLIP = (
    "https://api.albastov.com/v1/media/samples/"
    "reference-848c3d555461736a.mp3"
)

client = OpenAI(
    base_url="https://api.albastov.com/v1",
    api_key=os.environ["ALBASTAR_API_KEY"],
)

clip = httpx.get(CLIP)
clip.raise_for_status()
transcript = client.audio.transcriptions.create(
    model="parakeet",
    file=("reference.mp3", clip.content),
)
print(transcript.text)

const base = "https://api.albastov.com/v1";

const clip = await fetch(
  `${base}/media/samples/reference-848c3d555461736a.mp3`,
);
if (!clip.ok) throw new Error(`${clip.status} ${await clip.text()}`);

const form = new FormData();
form.append("model", "parakeet");
form.append("file", await clip.blob(), "reference.mp3");
const res = await fetch(`${base}/audio/transcriptions`, {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.ALBASTAR_API_KEY}` },
  body: form,
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log((await res.json()).text);

The response is the transcript Parakeet returned for the clip:

{
  "text": "Okay, so here's the plan. We land just after sunset, …"
}

The text value above is shortened. The whole transcript, wrapped at 76 characters:

Okay, so here's the plan. We land just after sunset, grab the bags, and head
straight for the harbor. If the ferry's late again, and honestly, it usually
is, we'll get dinner by the water and wait it out. Sound good.

What you can build

Key concepts

Built-in voice

A voice that belongs to one model, named by its id: af_heart on kokoro. GET /v1/media/voices?model=kokoro lists a model's built-in voices.

Saved voice

A reference clip of one voice with an id vo_…. A cloning model speaks any text in a saved voice; without model, the request runs on the voice's default_model.

Reference voice

Narrator A, vo_tBeDCRb2byGFjB6HGyQq6a, a synthetic voice (Kokoro's built-in af_heart) that every key with media:generate may use. The docs examples clone it.

Scopes

media:generate opens speech, transcriptions, media jobs, uploads and voice writes. media:read opens the model list, job reads and voice reads; media:generate does not include media:read.

Media job

Every speech and transcription request runs as a media job. A job not done in time returns 503 with code queued and job_id; GET /v1/media/jobs/{job_id}?wait=30 returns the result once state is done.

Next steps