Voices

curl

curl -sS --fail-with-body https://citadel.albastov.com/v1/audio/speech \
  -H "Authorization: Bearer $CITADEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "kokoro", "voice": "bf_emma", "response_format": "wav",
       "input": "The harbour lights came on one by one as the ferry crossed the bay. A clean recording of ten to twenty seconds makes the best voice."}' \
  --output reference.wav

VOICE=$(curl -sS --fail-with-body https://citadel.albastov.com/v1/media/voices \
  -H "Authorization: Bearer $CITADEL_API_KEY" \
  -F [email protected] -F name="Harbour narrator" -F language=en \
  -F consent="Synthesized by kokoro, not a person's voice." \
  | python3 -c 'import json, sys; print(json.load(sys.stdin)["id"])')

curl -sS --fail-with-body https://citadel.albastov.com/v1/audio/speech \
  -H "Authorization: Bearer $CITADEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"voice\": \"$VOICE\", \"input\": \"Any text, spoken in the saved voice.\"}" \
  --output spoken.mp3

curl -sS --fail-with-body -X DELETE "https://citadel.albastov.com/v1/media/voices/$VOICE" \
  -H "Authorization: Bearer $CITADEL_API_KEY"

Python

import json
import os
import time
import urllib.request

BASE = "https://citadel.albastov.com/v1"
KEY = os.environ["CITADEL_API_KEY"]


def call(method, path, body=None, content_type="application/json"):
    """One API call; JSON in and out, raw bytes for audio. An HTTP error raises."""
    data = json.dumps(body).encode() if content_type == "application/json" and body is not None else body
    req = urllib.request.Request(BASE + path, data=data, method=method,
                                 headers={"Authorization": f"Bearer {KEY}", "Content-Type": content_type})
    with urllib.request.urlopen(req, timeout=120) as res:
        raw = res.read()
        return json.loads(raw) if res.headers.get_content_type() == "application/json" else raw


clip = call("POST", "/audio/speech", {
    "model": "kokoro", "voice": "bf_emma", "response_format": "wav",
    "input": "The harbour lights came on one by one as the ferry crossed the bay. "
             "A clean recording of ten to twenty seconds makes the best voice.",
})

# Upload the clip as a raw body, then save the upload as a voice.
upload = call("POST", "/media/uploads", clip, content_type="audio/wav")
voice = call("POST", "/media/voices", {"from": upload["id"], "name": "Harbour narrator", "language": "en",
                                       "consent": "Synthesized by kokoro, not a person's voice."})
print(voice["id"], voice["status"], voice["default_model"])

# The preview is made in the background; preview_url is null until then.
for _ in range(30):
    voice = call("GET", f"/media/voices/{voice['id']}")
    if voice["preview_url"]:
        break
    time.sleep(2)
print("preview:", voice["preview_url"])

spoken = call("POST", "/audio/speech", {"voice": voice["id"], "input": "Any text, spoken in the saved voice."})
open("spoken.mp3", "wb").write(spoken)

call("DELETE", f"/media/voices/{voice['id']}")

JavaScript

const base = "https://citadel.albastov.com/v1";
const auth = { Authorization: `Bearer ${process.env.CITADEL_API_KEY}` };
const ok = async (res) => {
  if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
  return res;
};

const clip = await ok(await fetch(`${base}/audio/speech`, {
  method: "POST",
  headers: { ...auth, "Content-Type": "application/json" },
  body: JSON.stringify({
    model: "kokoro", voice: "bf_emma", response_format: "wav",
    input: "The harbour lights came on one by one as the ferry crossed the bay. A clean recording of ten to twenty seconds makes the best voice.",
  }),
}));

const form = new FormData();
form.append("file", await clip.blob(), "reference.wav");
form.append("name", "Harbour narrator");
form.append("consent", "Synthesized by kokoro, not a person's voice.");
const voice = await (await ok(await fetch(`${base}/media/voices`, { method: "POST", headers: auth, body: form }))).json();
console.log(voice.id, voice.status, voice.default_model);

const speech = await ok(await fetch(`${base}/audio/speech`, {
  method: "POST",
  headers: { ...auth, "Content-Type": "application/json" },
  body: JSON.stringify({ voice: voice.id, input: "Any text, spoken in the saved voice." }),
}));
console.log((await speech.arrayBuffer()).byteLength, "bytes of", speech.headers.get("content-type"));

await ok(await fetch(`${base}/media/voices/${voice.id}`, { method: "DELETE", headers: auth }));

curl

JOB=$(curl -sS --fail-with-body "https://citadel.albastov.com/v1/media/jobs?wait=60" \
  -H "Authorization: Bearer $CITADEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind": "speech", "model": "kokoro", "params": {"voice": "am_michael", "format": "wav",
       "text": "Every station on the line has a clock, a bench and a map of the city in faded blue."}}' \
  | python3 -c 'import json, sys; print(json.load(sys.stdin)["id"])')

VOICE=$(curl -sS --fail-with-body https://citadel.albastov.com/v1/media/voices \
  -H "Authorization: Bearer $CITADEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"from\": \"job:$JOB/0\", \"name\": \"Station announcer\", \"labels\": {\"use\": \"announcements\"}}" \
  | python3 -c 'import json, sys; v = json.load(sys.stdin); print(v["id"])')

curl -sS --fail-with-body -X DELETE "https://citadel.albastov.com/v1/media/voices/$VOICE" \
  -H "Authorization: Bearer $CITADEL_API_KEY"

curl

VOICE=$(curl -sS --fail-with-body https://citadel.albastov.com/v1/media/voices/design \
  -H "Authorization: Bearer $CITADEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Night radio", "description": "male, middle-aged, low pitch, slow and warm"}' \
  | python3 -c 'import json, sys; print(json.load(sys.stdin)["id"])')

for i in $(seq 60); do
  STATUS=$(curl -sS --fail-with-body "https://citadel.albastov.com/v1/media/voices/$VOICE" \
    -H "Authorization: Bearer $CITADEL_API_KEY" | python3 -c 'import json, sys; print(json.load(sys.stdin)["status"])')
  [ "$STATUS" != pending ] && break
  sleep 2
done
echo "$VOICE $STATUS"

curl -sS --fail-with-body -X DELETE "https://citadel.albastov.com/v1/media/voices/$VOICE" \
  -H "Authorization: Bearer $CITADEL_API_KEY"

curl

curl -sS --fail-with-body "https://citadel.albastov.com/v1/media/voices?model=kokoro&language=en-gb&limit=5" \
  -H "Authorization: Bearer $CITADEL_API_KEY"

Python

import json
import os
import urllib.parse
import urllib.request

BASE = "https://citadel.albastov.com/v1"
KEY = os.environ["CITADEL_API_KEY"]

params = {"scope": "all", "limit": 100}
while True:
    req = urllib.request.Request(f"{BASE}/media/voices?{urllib.parse.urlencode(params)}",
                                 headers={"Authorization": f"Bearer {KEY}"})
    with urllib.request.urlopen(req, timeout=30) as res:
        page = json.load(res)
    for v in page["data"]:
        print(v["id"], v["category"], v["owner"], v["visibility"], v["default_model"])
    if not page["has_more"]:
        break
    params["cursor"] = page["next_cursor"]

curl

VOICE=$(curl -sS --fail-with-body "https://citadel.albastov.com/v1/media/voices?category=designed&limit=1" \
  -H "Authorization: Bearer $CITADEL_API_KEY" | python3 -c 'import json, sys; print(json.load(sys.stdin)["data"][0]["id"])')

curl -sS --fail-with-body "https://citadel.albastov.com/v1/media/jobs?wait=60" \
  -H "Authorization: Bearer $CITADEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"kind\": \"speech\", \"model\": \"higgs3\", \"params\": {\"text\": \"The same voice on another model.\", \"voice\": \"$VOICE\"}}"

curl

curl -sS --fail-with-body -X PATCH "https://citadel.albastov.com/v1/media/voices/$VOICE" \
  -H "Authorization: Bearer $CITADEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"visibility": "members", "consent": "Recorded by the speaker for albastov.com members, 2026-11-02."}'

curl

SOURCE=$(curl -sS --fail-with-body "https://citadel.albastov.com/v1/media/voices?category=designed&limit=1" \
  -H "Authorization: Bearer $CITADEL_API_KEY" | python3 -c 'import json, sys; print(json.load(sys.stdin)["data"][0]["id"])')

COPY=$(curl -sS --fail-with-body -X POST "https://citadel.albastov.com/v1/media/voices/$SOURCE/copy" \
  -H "Authorization: Bearer $CITADEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My copy"}' | python3 -c 'import json, sys; v = json.load(sys.stdin); print(v["id"])')

curl -sS --fail-with-body -X PATCH "https://citadel.albastov.com/v1/media/voices/$COPY" \
  -H "Authorization: Bearer $CITADEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "Renamed copy for chapter readings", "labels": {"book": "harbour"}}'

curl -sS --fail-with-body -X DELETE "https://citadel.albastov.com/v1/media/voices/$COPY" \
  -H "Authorization: Bearer $CITADEL_API_KEY"

curl

VOICE=$(curl -sS --fail-with-body "https://citadel.albastov.com/v1/media/voices?category=designed&limit=1" \
  -H "Authorization: Bearer $CITADEL_API_KEY" | python3 -c 'import json, sys; print(json.load(sys.stdin)["data"][0]["id"])')

curl -sS --fail-with-body https://citadel.albastov.com/v1/media/jobs \
  -H "Authorization: Bearer $CITADEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"kind\": \"speech\", \"model\": \"kokoro\", \"params\": {\"text\": \"Hello.\", \"voice\": \"$VOICE\"}}"