Developer API

The AthanLab API turns Burmese text into speech with the same engine, voices and character balance as the AthanLab app. It works with asynchronous jobs, so no request waits for audio.

How it works

1. Create. POST /speech returns 202 Accepted with the job.
2. Poll. GET /speech/{id} until its status is no longer processing, as described in Polling.
3. Download. GET /speech/{id}/audio returns the MP3 or WAV file.

To listen on athanlab.com instead of downloading a file, send the text to AthanInbox with POST /deliveries.

At a glance

Access is currently by invitation. Do every step signed in with the email address we invited: the application form appears only for that account. Not invited? Email support@athanlab.com to ask about access.

1. Apply

   On the Developer API page of your dashboard, give your company or project, what you are building and your expected monthly volume. Then accept the API Terms.

2. Wait for review

   We review every application by hand and email you the decision. A rejection email says why and when you can apply again.

3. Subscribe to Max

   To pay with KBZPay instead of a card, see Billing.

4. Create a key

   Keys need an approved developer application and an active Max plan. You can hold up to 5 keys at a time, each valid for 30, 90, 180 or 365 days (default 365). A key is shown once, when you create it: see Authentication.

Send an API key with every request except GET /openapi.json.

X-API-Key: $ATHANLAB_API_KEY
# or
Authorization: Bearer $ATHANLAB_API_KEY

For example, this request returns your balance. It needs the usage:read scope (see Scopes).

curl -sS https://api.athanlab.com/api/v1/usage \
  -H "X-API-Key: $ATHANLAB_API_KEY"

A key is ak_live_ followed by 32 hex characters. It is shown once, when you create it, so store it in your secret manager.

A missing key returns 401 missing_api_key. An unknown, malformed, revoked or expired key returns 401 invalid_api_key. Unknown and malformed keys also count toward the per-network limit on failed key checks, which blocks a network for 10 minutes with 429 auth_blocked (see Rate limits).

Scopes

A key can call only the endpoints its scopes allow:

A request outside a key's scopes returns 403 scope_missing.

Rotate a key

Rotating gives a key a new secret. The 24-hour grace, which keeps the old secret working while you deploy the new one, is for planned rotations only. To end a running grace early, choose Stop old secret.

Three requests: create a job, poll it, download the audio.

1. Create a job

   curl -sS https://api.athanlab.com/api/v1/speech \
     -H "X-API-Key: $ATHANLAB_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"text": "မင်္ဂလာပါ။ အသံလက်ဘ်မှ ကြိုဆိုပါတယ်။", "output_format": "mp3",
       "metadata": {"order_id": "A-1042"}}'

   {
     "object": "speech",
     "id": "8f14e45fceea167a5a36dedd4bea2543",
     "status": "processing",
     "created_at": "2026-10-01T08:30:00.000Z",
     "completed_at": null,
     "progress": 0,
     "input": {
       "characters": 35,
       "voice_id": "athanlab-default-female-v1",
       "output_format": "mp3",
       "number_mode": "smart"
     },
     "usage": {
       "characters_charged": 35,
       "characters_refunded": 0
     },
     "audio": null,
     "error": null,
     "metadata": {
       "order_id": "A-1042"
     },
     "balance": {
       "spendable_chars": 1949965
     }
   }

   The response also carries Location, the path of the job, and Retry-After: 2. In production, send an Idempotency-Key with every create so a retry never charges twice (see Safe retries).

2. Poll the job

   Put the id from the response in JOB_ID, then fetch the job.

   curl -sS https://api.athanlab.com/api/v1/speech/$JOB_ID \
     -H "X-API-Key: $ATHANLAB_API_KEY"

   {
     "object": "speech",
     "id": "8f14e45fceea167a5a36dedd4bea2543",
     "status": "succeeded",
     "created_at": "2026-10-01T08:30:00.000Z",
     "completed_at": "2026-10-01T08:30:07.412Z",
     "progress": 1,
     "input": {
       "characters": 35,
       "voice_id": "athanlab-default-female-v1",
       "output_format": "mp3",
       "number_mode": "smart"
     },
     "usage": {
       "characters_charged": 35,
       "characters_refunded": 0
     },
     "audio": {
       "format": "mp3",
       "duration_seconds": 3.84,
       "url": "/api/v1/speech/8f14e45fceea167a5a36dedd4bea2543/audio",
       "expires_at": "2026-10-31T08:30:00.000Z"
     },
     "error": null,
     "metadata": {
       "order_id": "A-1042"
     }
   }

   Repeat until status is no longer processing, at the pace described in Polling.

3. Download the audio

   curl -sS --fail -o speech.mp3 \
     https://api.athanlab.com/api/v1/speech/$JOB_ID/audio \
     -H "X-API-Key: $ATHANLAB_API_KEY"

   With --fail, curl saves nothing when the request fails, so an error body never ends up in speech.mp3.

Complete script

The same three steps as one program, with an Idempotency-Key and back-off between polls:

# Set ATHANLAB_API_KEY to your key from the Developer API page first. Keep it server-side.

# 1. Create a job. The response is 202 Accepted with the job.
#    Keep its id for the next steps. If the API rejects the request, the error is printed instead.
JOB_ID=$(curl -sS https://api.athanlab.com/api/v1/speech \
  -H "X-API-Key: $ATHANLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(python3 -c 'import uuid; print(uuid.uuid4())')" \
  -d '{"text": "မင်္ဂလာပါ။ အသံလက်ဘ်မှ ကြိုဆိုပါတယ်။", "output_format": "mp3"}' \
  | python3 -c 'import json, sys; job = json.load(sys.stdin); print(job.get("id") or sys.exit(json.dumps(job)))')
echo "$JOB_ID"

# 2. Poll until the job is no longer processing.
#    Wait 2 seconds first, the Retry-After of the create response, then about 10 seconds between polls.
sleep 2
while :; do
  JOB=$(curl -sS https://api.athanlab.com/api/v1/speech/$JOB_ID -H "X-API-Key: $ATHANLAB_API_KEY")
  STATUS=$(printf '%s' "$JOB" | python3 -c 'import json, sys; print(json.load(sys.stdin).get("status", "error"))')
  echo "$STATUS"
  [ "$STATUS" = "processing" ] || break
  sleep 10
done
echo "$JOB"

# 3. Download the audio when the job succeeded.
#    With --fail, curl writes no file on an HTTP error, since an error body is not audio.
[ "$STATUS" = "succeeded" ] && curl -sS --fail -o speech.mp3 https://api.athanlab.com/api/v1/speech/$JOB_ID/audio \
  -H "X-API-Key: $ATHANLAB_API_KEY"

import os, time, uuid
import requests  # pip install requests

BASE = "https://api.athanlab.com/api/v1"
HEADERS = {"X-API-Key": os.environ["ATHANLAB_API_KEY"]}

# 1. Create the job. The Idempotency-Key makes retrying this POST safe:
#    a repeat returns the same job instead of charging twice.
res = requests.post(
    f"{BASE}/speech",
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json={"text": "မင်္ဂလာပါ။ အသံလက်ဘ်မှ ကြိုဆိုပါတယ်။", "output_format": "mp3"},
    timeout=30,
)
res.raise_for_status()
job = res.json()

# 2. Poll until the job finishes: first after the create response's Retry-After,
#    then backing off to 10 s (a successful poll sends no Retry-After).
delay = float(res.headers.get("Retry-After", 2))
while job["status"] == "processing":
    time.sleep(delay)
    res = requests.get(f"{BASE}/speech/{job['id']}", headers=HEADERS, timeout=30)
    if res.status_code == 429:
        delay = float(res.headers.get("Retry-After", delay))
        continue
    res.raise_for_status()
    job = res.json()
    delay = min(delay * 1.5, 10)

if job["status"] != "succeeded":
    raise RuntimeError(f"job {job['status']}: {job['error']}")

# 3. Download the audio.
audio = requests.get(f"{BASE}/speech/{job['id']}/audio", headers=HEADERS, timeout=120)
audio.raise_for_status()
with open("speech.mp3", "wb") as f:
    f.write(audio.content)

// Node.js 18+ — save as quickstart.mjs and run: node quickstart.mjs
import { randomUUID } from 'node:crypto'
import { writeFile } from 'node:fs/promises'

const BASE = 'https://api.athanlab.com/api/v1'
// An unset key would go out as the header "undefined": rejected, and counted
// toward the per-network limit on failed key checks.
const apiKey = process.env.ATHANLAB_API_KEY
if (!apiKey) throw new Error('Set ATHANLAB_API_KEY to your API key first.')
const headers = { 'X-API-Key': apiKey }
const sleep = (seconds) => new Promise((resolve) => setTimeout(resolve, seconds * 1000))

async function check(res) {
  if (!res.ok) throw new Error(JSON.stringify(await res.json()))
  return res
}

// 1. Create the job. The Idempotency-Key makes retrying this POST safe.
let res = await check(await fetch(`${BASE}/speech`, {
  method: 'POST',
  headers: { ...headers, 'Content-Type': 'application/json', 'Idempotency-Key': randomUUID() },
  body: JSON.stringify({ text: 'မင်္ဂလာပါ။ အသံလက်ဘ်မှ ကြိုဆိုပါတယ်။', output_format: 'mp3' }),
}))
let job = await res.json()

// 2. Poll until the job finishes: first after the create response's Retry-After,
//    then backing off to 10 s (a successful poll sends no Retry-After).
let delay = Number(res.headers.get('Retry-After') ?? 2)
while (job.status === 'processing') {
  await sleep(delay)
  res = await fetch(`${BASE}/speech/${job.id}`, { headers })
  if (res.status === 429) {
    delay = Number(res.headers.get('Retry-After') ?? delay)
    continue
  }
  job = await (await check(res)).json()
  delay = Math.min(delay * 1.5, 10)
}
if (job.status !== 'succeeded') throw new Error(`job ${job.status}: ${job.error?.code}`)

// 3. Download the audio.
res = await check(await fetch(`${BASE}/speech/${job.id}/audio`, { headers }))
await writeFile('speech.mp3', Buffer.from(await res.arrayBuffer()))

Sending your own text? Read Writing text for speech first: sentence punctuation, made-up names, and how numbers are read.

Next steps

• Writing text for speech
• Job lifecycle
• Voices
• Errors
• AI agents (MCP)

The API reads exactly the text you send. These rules make it sound natural and keep a request from being rejected.

Sentences and punctuation

End every sentence with ။, ! or ?, and keep sentences short. Text is spoken sentence by sentence, in pieces. A dry run's dispatches field counts the pieces your text becomes (see Quote first with dry_run).

A sentence too long for one piece is cut at a ၊, then at a space, and mid-word only as a last resort. So a long stretch without punctuation breaks in odd places. If a piece still cannot be made short enough, the request is rejected before any charge with 422 text_too_long: “Part of the text is too long to speak in one piece. Add sentence punctuation and retry.”

Burmese and English

Burmese, English, and Burmese with English words mixed in all work. Made-up names and brand names (for example AthanLab) can come out wrong. Spell them the way they sound in Burmese (အသံလက်ဘ်) and listen to a sample first.

Marks the voice skips

Quotation marks, brackets and … are not spoken well. Remove them, or put a ၊ where you want a short pause. Text that is only emoji, punctuation or whitespace has nothing to read. It is rejected before any charge with 422 unspeakable_text.

Numbers

number_mode sets how digits are read. Here is each mode reading ကျပ် ၁၂၃၄:

Numbers written out as words cost nothing extra, but the expanded text must stay within 10,000 characters, or the request returns 422 text_too_long.

Scripts and dialogue

Split long scripts into sentence-sized lines and create one job per line, each with its speaker's voice_id. Every line then has its own audio file to place on a timeline, retime or replace. Fixing one line regenerates, and charges, only that line.

Your account runs a limited number of jobs at once (see Rate limits and quotas), so queue the lines and submit the next as earlier ones finish. For AI agents, athanlab_speak_script creates one job per line, each in its speaker's voice, and saves the files on one timeline (see AI agents (MCP)).

A job starts as processing and ends in exactly one final status. It never moves back.

Statuses

Polling

Poll GET /speech/{id} while the job is processing: wait the Retry-After of the create response (2 seconds) before the first poll, then back off to about 10 seconds between polls. A successful poll carries no Retry-After of its own, so keep your own delay.

Polls count against the per-key read limit of 600 requests a minute, and against the per-network limit. A rate-limited poll returns 429 with its own Retry-After.

To follow many jobs, list the ones still processing in one request instead of polling each:

curl -sS "https://api.athanlab.com/api/v1/speech?status=processing&limit=50" \
  -H "X-API-Key: $ATHANLAB_API_KEY"

The same call with status=failed finds the jobs that failed.

Webhooks

The API does not send webhooks. Poll for the outcome as described above.

Safe retries

Send an Idempotency-Key header with a new UUID on every POST /speech and POST /deliveries, and reuse it when you retry that request. A network can fail after the server has accepted a job, and the key keeps the retry from creating and charging a second one.

Within 24 hours, the same key and body return the original job (or delivery) with Idempotent-Replayed: true and no new charge. The same key with a different body returns 409 idempotency_conflict. An Idempotency-Key used on POST /speech never conflicts with the same value on POST /deliveries.

Quote first with dry_run

Add "dry_run": true to check a request and see its price. Nothing is created or charged, and the response is a DryRunQuote, as in this example:

curl -sS https://api.athanlab.com/api/v1/speech \
  -H "X-API-Key: $ATHANLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "မင်္ဂလာပါ။ အသံလက်ဘ်မှ ကြိုဆိုပါတယ်။", "dry_run": true}'

{
  "object": "speech.quote",
  "characters": 35,
  "dispatches": 1,
  "spendable": 1950000,
  "sufficient": true
}

characters is what the job would cost, dispatches the number of pieces the text is spoken in, and sufficient whether your balance covers it.

Cancel

POST /speech/{id}/cancel stops a job that is still processing. The share already generated stays charged and the rest is refunded, as usage.characters_refunded shows. Cancel works while the API is in read-only mode and after your Max plan ends. A finished job returns 409 job_finished.

curl -sS -X POST https://api.athanlab.com/api/v1/speech/$JOB_ID/cancel \
  -H "X-API-Key: $ATHANLAB_API_KEY"

Retention

Audio and input text are kept for 30 days after the job is created (audio.expires_at), then deleted. Download what you need to keep. After that, a download returns 410 audio_expired, but the job record (status, characters, metadata) stays readable.

Audio and text sent to AthanInbox are the exception: they are kept until you delete them in AthanInbox or delete your account (see AthanInbox).

The API never returns your input text.

Job failure codes

A failed job reports one of these codes in error.code. They are not HTTP errors: the poll itself succeeds with status: "failed", and the characters are refunded in full.

GET /voices lists AthanLab's official voices (source: "athanlab") and the voices in your own AthanLab library (source: "user"). Pass a voice's id as voice_id. The official voices include athanlab-default-female-v1 and athanlab-default-male-v1.

If you leave voice_id out, the job uses default_voice_id from the same response. If that is null, the default is briefly unavailable, so send a voice_id.

GET /voices/{id}/preview returns a signed sample URL, valid for one hour, so your users can hear a voice before choosing it.

You add library voices in the AthanLab app, under its consent rules: only your own voice, or one you have the speaker's explicit permission to use (see the Acceptable Use Policy).

Full details: GET /voices and GET /voices/{id}/preview in the endpoint reference.

The API spends the same character balance as the AthanLab app: your Max plan's monthly allowance first, then any Athan Tokens (characters you buy in the AthanLab app). One character through the API is one character in the app. GET /usage shows both.

What is charged

Per-key budgets

You can give any key an optional monthly character budget on the Developer API page. It is counted per UTC calendar month. Past it, creating a job or a delivery with that key returns 429 key_budget_exceeded and nothing is charged. For agents, see A key for each agent.

Paying for Max

Pay with KBZPay rather than a card? Email support@athanlab.com and we set up a Max subscription for you. For what your keys can still do after your plan ends, see When your Max plan ends under Get access.

@athanlab/mcp is an MCP server that lets AI agents in Claude Code, Codex (the CLI and the desktop app), Claude Desktop, Cursor and other MCP clients that run local (stdio) servers create, poll and download speech through this API with your key. Ask for audio in plain words: the agent creates the job, waits for it and saves the file in a local folder. A script becomes one audio file per line plus a manifest.json timeline, ready for subtitles and video. Or the agent sends the audio to AthanInbox, to listen to on athanlab.com.

The server runs on your machine, calls the same endpoints as the Quickstart and spends the same balance.

Requirements

• Node.js 20 or later on the machine that runs the agent.
• An API key (see Get access), ideally one made for the agent.

Install

claude mcp add athanlab -e ATHANLAB_API_KEY=ak_live_your_key_here -- npx -y @athanlab/mcp

[mcp_servers.athanlab]
command = "npx"
args = ["-y", "@athanlab/mcp"]
env_vars = ["ATHANLAB_API_KEY"]
startup_timeout_sec = 30
tool_timeout_sec = 960

[mcp_servers.athanlab]
command = "npx"
args = ["-y", "@athanlab/mcp"]
startup_timeout_sec = 30
tool_timeout_sec = 960

[mcp_servers.athanlab.env]
ATHANLAB_API_KEY = "ak_live_your_key_here"
ATHANLAB_OUTPUT_DIR = "/Users/you/Documents/athanlab-audio"
PATH = "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"

{
  "mcpServers": {
    "athanlab": {
      "command": "npx",
      "args": ["-y", "@athanlab/mcp"],
      "env": {
        "ATHANLAB_API_KEY": "ak_live_your_key_here",
        "ATHANLAB_OUTPUT_DIR": "/Users/you/Documents/athanlab-audio"
      }
    }
  }
}

{
  "mcpServers": {
    "athanlab": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@athanlab/mcp"],
      "env": {
        "ATHANLAB_API_KEY": "${env:ATHANLAB_API_KEY}",
        "ATHANLAB_OUTPUT_DIR": "${userHome}/athanlab-audio"
      }
    }
  }
}

Agent skill

The package ships the athanlab-voice skill. It teaches an agent when to use these tools, how to write text for speech, cast voices, quote before spending and turn a manifest into subtitles. The skill needs the MCP server and adds no tools of its own.

mkdir -p ~/.claude/skills/athanlab-voice
curl -fsSL https://unpkg.com/@athanlab/mcp/skill/athanlab-voice/SKILL.md \
  -o ~/.claude/skills/athanlab-voice/SKILL.md

mkdir -p ~/.agents/skills/athanlab-voice
curl -fsSL https://unpkg.com/@athanlab/mcp/skill/athanlab-voice/SKILL.md \
  -o ~/.agents/skills/athanlab-voice/SKILL.md

The Codex desktop app uses the same skill folder as Codex CLI. For one project, put it in .claude/skills/athanlab-voice/ (Claude Code) or .agents/skills/athanlab-voice/ (Codex) inside that project instead. Start a new session to load it.

Tools

The server registers these tools. Those marked “no charge” spend no characters, but their API requests still count toward the rate limits.

It also serves the athanlab-writing-guide prompt (and the resource athanlab://guides/writing): the rules of Writing text for speech, for the agent to read before it writes text, or to rewrite a draft you give it.

AthanInbox

Send audio to your own AthanInbox, and listen on athanlab.com.

AthanInbox is the inbox of your AthanLab account, on the web at athanlab.com/dashboard/inbox. AthanInbox comes to the AthanLab mobile app in a later update. Instead of saving files, an agent with athanlab_send_to_inbox, or your own code with POST /deliveries, sends a title and its text there. You listen when it suits you, chapter by chapter, with a transcript that follows along and the source links that came with it. A delivery always goes to AthanInbox of the account that owns the key, never to anyone else.

1. Charged up front

   The whole delivery, every chapter, is charged when it is accepted, and the response is 202 Accepted at once. A chapter that cannot be made is refunded automatically, to the balance it was charged from (a monthly allowance that has reset since is not carried over), and the other chapters still arrive.

2. Made in the background

   The chapters are made one at a time, in order, after the response. A chapter still waiting after 7 days expires and is refunded.

3. Listen on athanlab.com

   Sign in to athanlab.com with the account that owns the key and open AthanInbox. Progress shows there while the chapters are made. app_url, https://athanlab.com/app/inbox/<id>, opens the delivery in AthanInbox for the signed-in owner only. Open it on a computer for now: on a phone with the AthanLab app installed, the link opens the app, which gets AthanInbox in a later update. On a phone, open athanlab.com/dashboard/inbox in the browser.

4. Kept until you delete it

   A job's audio is deleted after 30 days, but a delivery stays in AthanInbox until you delete it there or delete your account. Deleting one while it is being made refunds every chapter not yet made and the unmade share of the one in progress.

A delivery takes up to 50 chapters of at most 5,000 characters each, 100,000 in total, a title of up to 120 characters and up to 20 https source links, which AthanInbox shows and AthanLab never fetches. Each chapter is checked like the text of a job before anything is charged (see Writing text for speech). An account can have 3 deliveries unfinished at once.

Send an Idempotency-Key with every POST /deliveries (see Safe retries), and add "dry_run": true for a free DeliveryQuote (see Quote first with dry_run). GET /deliveries/{id} reports each chapter and what the delivery cost. Polling is optional, since AthanInbox shows the progress; if you poll, wait at least the Retry-After of the create response (30 seconds) between polls.

A failed chapter reports one of these codes in its error.code, and its characters are refunded:

From an agent. athanlab_send_to_inbox takes a title and the text, and splits long text into chapters of at most 5,000 characters at paragraph and sentence ends, or takes your own chapters. Above 2,000 characters or 20 chapters it returns a free quote and sends nothing until it is called again with confirm: true. It returns at once with the delivery's id, status and app_url, and athanlab_get_delivery checks on it. The same arguments within 24 hours return the first delivery and charge nothing, while send_again: true sends a second copy, charged again. Nothing is saved on your machine: you listen in AthanInbox on athanlab.com.

Sending needs a key with the speech:write scope (speech:read to read a delivery back) and the same access as creating a job: an approved application and the Max plan (see Get access). Full details: POST /deliveries and GET /deliveries/{id} in the endpoint reference.

Configuration

The server is configured with these environment variables. For its default output folder it also reads CLAUDE_PROJECT_DIR, which Claude Code sets itself.

A key for each agent

An agent spends real characters on its own, so give it a key you can cap and switch off. When you create it on the Developer API page:

• A separate key for each agent or machine, named for where it runs, so you can see what it spends and revoke it without touching your servers.
• Only the scopes it needs. All four for everything the server does. Without speech:write it can list voices, read jobs and deliveries, download audio and check usage, but not create or cancel jobs or send to AthanInbox.
• A low monthly character budget, for example 20,000. Past it, creating a job returns 429 key_budget_exceeded and nothing is charged, so a looping agent cannot drain your balance.
• A short expiry: 30 days, the shortest there is. Create a new key when it runs out.
• Keep it out of prompts and repositories. The key belongs in the server's environment. The model never needs to see it, so never paste it into a chat.
• Rotate or revoke. If a key leaks, revoke it at once, or rotate it and choose Stop the old secret immediately (see Authentication).

The server checks the key's format on your machine before any request, so a malformed key (a missing prefix, a truncated paste, the placeholder) never reaches the API or counts toward the per-network limit on failed key checks. A well-formed but wrong key is sent once. After one 401 invalid_api_key, the server sends nothing more until it restarts with a new key.

Spending brakes. athanlab_speak_script returns its quote and creates nothing above 2,000 characters or 20 lines until it is called again with confirm: true. athanlab_send_to_inbox asks the same way above 2,000 characters or 20 chapters. ATHANLAB_MAX_CHARS_PER_CALL caps any single call.

Example: a two-speaker scene

Ask the agent in plain words, with the script:

Voice this scene into scene01 with a female voice for Aye and a male voice for Min, combine it into one track, then write scene01.srt from the manifest.

Aye: မင်္ဂလာပါ။ နေကောင်းလား။ Min: နေကောင်းပါတယ်။ ကျေးဇူးတင်ပါတယ်။ Min: ဒီနေ့ ရာသီဥတု သာယာတယ်နော်။ Aye: ဟုတ်တယ်။ လမ်းလျှောက်ကြရအောင်။

It calls athanlab_speak_script with one entry per line and a voice for each speaker:

{
  "lines": [
    { "id": "l1", "speaker": "Aye", "text": "မင်္ဂလာပါ။ နေကောင်းလား။" },
    { "id": "l2", "speaker": "Min", "text": "နေကောင်းပါတယ်။ ကျေးဇူးတင်ပါတယ်။" },
    { "id": "l3", "speaker": "Min", "text": "ဒီနေ့ ရာသီဥတု သာယာတယ်နော်။" },
    { "id": "l4", "speaker": "Aye", "text": "ဟုတ်တယ်။ လမ်းလျှောက်ကြရအောင်။" }
  ],
  "voices": { "Aye": "athanlab-default-female-v1", "Min": "athanlab-default-male-v1" },
  "out_subdir": "scene01",
  "combine": true
}

In scene01/ inside the output folder (athanlab-audio by default) it writes one WAV file per line (001-l1.wav to 004-l4.wav), manifest.json and, with combine, combined.wav. The manifest puts every line on one timeline:

{
  "version": 1,
  "output_format": "wav",
  "gaps": { "sentence": 0.4, "turn": 0.55 },
  "timeline_complete": true,
  "total_duration_seconds": 10.8,
  "combined_file": "combined.wav",
  "lines": [
    {
      "index": 0, "id": "l1", "speaker": "Aye", "voice_id": "athanlab-default-female-v1",
      "text": "မင်္ဂလာပါ။ နေကောင်းလား။", "file": "001-l1.wav", "characters_charged": 23,
      "duration_seconds": 2.1, "start_seconds": 0, "end_seconds": 2.1
    },
    {
      "index": 1, "id": "l2", "speaker": "Min", "voice_id": "athanlab-default-male-v1",
      "text": "နေကောင်းပါတယ်။ ကျေးဇူးတင်ပါတယ်။", "file": "002-l2.wav", "characters_charged": 31,
      "duration_seconds": 2.4, "start_seconds": 2.65, "end_seconds": 5.05
    },
    {
      "index": 2, "id": "l3", "speaker": "Min", "voice_id": "athanlab-default-male-v1",
      "text": "ဒီနေ့ ရာသီဥတု သာယာတယ်နော်။", "file": "003-l3.wav", "characters_charged": 26,
      "duration_seconds": 2.2, "start_seconds": 5.45, "end_seconds": 7.65
    },
    {
      "index": 3, "id": "l4", "speaker": "Aye", "voice_id": "athanlab-default-female-v1",
      "text": "ဟုတ်တယ်။ လမ်းလျှောက်ကြရအောင်။", "file": "004-l4.wav", "characters_charged": 29,
      "duration_seconds": 2.6, "start_seconds": 8.2, "end_seconds": 10.8
    }
  ]
}

Each line starts gaps.turn seconds (0.55 by default) after the previous one ends when the speaker changes, and gaps.sentence seconds (0.4) when the same speaker goes on. combined.wav has exactly these gaps as silence, so the manifest's times are times in it. The real file also gives each line its job_id and status.

From the manifest the agent writes one subtitle cue per line, from start_seconds to end_seconds:

1
00:00:00,000 --> 00:00:02,100
မင်္ဂလာပါ။ နေကောင်းလား။

2
00:00:02,650 --> 00:00:05,050
နေကောင်းပါတယ်။ ကျေးဇူးတင်ပါတယ်။

3
00:00:05,450 --> 00:00:07,650
ဒီနေ့ ရာသီဥတု သာယာတယ်နော်။

4
00:00:08,200 --> 00:00:10,800
ဟုတ်တယ်။ လမ်းလျှောက်ကြရအောင်။

Use combined.wav as the voice track, or place each line's file at its start_seconds in your editor. This ffmpeg command puts the track under a video and keeps the video's full length:

ffmpeg -i video.mp4 -i combined.wav -map 0:v -map 1:a -c:v copy -af apad -c:a aac -shortest out.mp4

Burned-in subtitles need a font with Burmese glyphs.

This reference is generated from the API's own OpenAPI document: each endpoint lists its parameters, responses, errors and an example.

curl -sS https://api.athanlab.com/api/v1/speech \
  -H "X-API-Key: $ATHANLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(python3 -c 'import uuid; print(uuid.uuid4())')" \
  -d '{
    "text": "မင်္ဂလာပါ။ အသံလက်ဘ်မှ ကြိုဆိုပါတယ်။",
    "voice_id": "athanlab-default-female-v1",
    "output_format": "mp3",
    "metadata": {
      "order_id": "A-1042"
    }
  }'

{
  "object": "speech",
  "id": "8f14e45fceea167a5a36dedd4bea2543",
  "status": "processing",
  "created_at": "2026-10-01T08:30:00.000Z",
  "completed_at": null,
  "progress": 0,
  "input": {
    "characters": 35,
    "voice_id": "athanlab-default-female-v1",
    "output_format": "mp3",
    "number_mode": "smart"
  },
  "usage": {
    "characters_charged": 35,
    "characters_refunded": 0
  },
  "audio": null,
  "error": null,
  "metadata": {
    "order_id": "A-1042"
  },
  "balance": {
    "spendable_chars": 1949965
  }
}

{
  "object": "speech.quote",
  "characters": 35,
  "dispatches": 1,
  "spendable": 1950000,
  "sufficient": true
}

curl -sS https://api.athanlab.com/api/v1/speech \
  -H "X-API-Key: $ATHANLAB_API_KEY"

{
  "object": "list",
  "data": [
    {
      "object": "speech",
      "id": "8f14e45fceea167a5a36dedd4bea2543",
      "status": "succeeded",
      "created_at": "2026-10-01T08:30:00.000Z",
      "completed_at": "2026-10-01T08:30:07.412Z",
      "progress": 1,
      "input": {
        "characters": 35,
        "voice_id": "athanlab-default-female-v1",
        "output_format": "mp3",
        "number_mode": "smart"
      },
      "usage": {
        "characters_charged": 35,
        "characters_refunded": 0
      },
      "audio": {
        "format": "mp3",
        "duration_seconds": 3.84,
        "url": "/api/v1/speech/8f14e45fceea167a5a36dedd4bea2543/audio",
        "expires_at": "2026-10-31T08:30:00.000Z"
      },
      "error": null,
      "metadata": {
        "order_id": "A-1042"
      }
    }
  ],
  "has_more": false,
  "next_cursor": null
}

curl -sS https://api.athanlab.com/api/v1/speech/$JOB_ID \
  -H "X-API-Key: $ATHANLAB_API_KEY"

{
  "object": "speech",
  "id": "8f14e45fceea167a5a36dedd4bea2543",
  "status": "succeeded",
  "created_at": "2026-10-01T08:30:00.000Z",
  "completed_at": "2026-10-01T08:30:07.412Z",
  "progress": 1,
  "input": {
    "characters": 35,
    "voice_id": "athanlab-default-female-v1",
    "output_format": "mp3",
    "number_mode": "smart"
  },
  "usage": {
    "characters_charged": 35,
    "characters_refunded": 0
  },
  "audio": {
    "format": "mp3",
    "duration_seconds": 3.84,
    "url": "/api/v1/speech/8f14e45fceea167a5a36dedd4bea2543/audio",
    "expires_at": "2026-10-31T08:30:00.000Z"
  },
  "error": null,
  "metadata": {
    "order_id": "A-1042"
  }
}

curl -sS -X POST https://api.athanlab.com/api/v1/speech/$JOB_ID/cancel \
  -H "X-API-Key: $ATHANLAB_API_KEY"

{
  "object": "speech",
  "id": "8f14e45fceea167a5a36dedd4bea2543",
  "status": "cancelled",
  "created_at": "2026-10-01T08:30:00.000Z",
  "completed_at": "2026-10-01T08:30:03.000Z",
  "progress": null,
  "input": {
    "characters": 35,
    "voice_id": "athanlab-default-female-v1",
    "output_format": "mp3",
    "number_mode": "smart"
  },
  "usage": {
    "characters_charged": 35,
    "characters_refunded": 21
  },
  "audio": null,
  "error": null,
  "metadata": {
    "order_id": "A-1042"
  }
}

curl -sS --fail -o speech.mp3 \
  https://api.athanlab.com/api/v1/speech/$JOB_ID/audio \
  -H "X-API-Key: $ATHANLAB_API_KEY"

curl -sS https://api.athanlab.com/api/v1/deliveries \
  -H "X-API-Key: $ATHANLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(python3 -c 'import uuid; print(uuid.uuid4())')" \
  -d '{
    "title": "ယနေ့ သတင်းအကျဉ်း",
    "kind": "briefing",
    "chapters": [
      {
        "title": "ရာသီဥတု",
        "text": "ရန်ကုန်မြို့တွင် မိုးအနည်းငယ် ရွာနိုင်ပါသည်။ ထီးဆောင်ထားပါ။"
      },
      {
        "title": "ဈေးကွက်",
        "text": "ဈေးကွက်များ တည်ငြိမ်နေပါသည်။ အသေးစိတ်ကို မနက်ဖြန် ပြောပြပါမယ်။"
      }
    ],
    "sources": [
      {
        "title": "မိုးလေဝသ ခန့်မှန်းချက်",
        "url": "https://example.com/weather"
      }
    ],
    "voice_id": "athanlab-default-female-v1"
  }'

{
  "object": "delivery",
  "id": "1679091c5a880faf6fb5e6087eb1b2dc",
  "status": "queued",
  "title": "ယနေ့ သတင်းအကျဉ်း",
  "kind": "briefing",
  "created_at": "2026-10-06T00:30:00.000Z",
  "completed_at": null,
  "progress": 0,
  "input": {
    "characters": 121,
    "chapters": 2,
    "voice_id": "athanlab-default-female-v1",
    "number_mode": "smart"
  },
  "chapters": [
    {
      "index": 0,
      "title": "ရာသီဥတု",
      "characters": 59,
      "status": "queued",
      "duration_seconds": null,
      "error": null
    },
    {
      "index": 1,
      "title": "ဈေးကွက်",
      "characters": 62,
      "status": "queued",
      "duration_seconds": null,
      "error": null
    }
  ],
  "sources": [
    {
      "title": "မိုးလေဝသ ခန့်မှန်းချက်",
      "url": "https://example.com/weather"
    }
  ],
  "usage": {
    "characters_charged": 121,
    "characters_refunded": 0
  },
  "app_url": "https://athanlab.com/app/inbox/1679091c5a880faf6fb5e6087eb1b2dc",
  "notified": false,
  "metadata": {},
  "balance": {
    "spendable_chars": 1949879
  }
}

{
  "object": "delivery.quote",
  "characters": 121,
  "chapters": 2,
  "dispatches": 2,
  "spendable": 1950000,
  "sufficient": true
}

curl -sS https://api.athanlab.com/api/v1/deliveries/$DELIVERY_ID \
  -H "X-API-Key: $ATHANLAB_API_KEY"

{
  "object": "delivery",
  "id": "1679091c5a880faf6fb5e6087eb1b2dc",
  "status": "succeeded",
  "title": "ယနေ့ သတင်းအကျဉ်း",
  "kind": "briefing",
  "created_at": "2026-10-06T00:30:00.000Z",
  "completed_at": "2026-10-06T00:31:24.000Z",
  "progress": 1,
  "input": {
    "characters": 121,
    "chapters": 2,
    "voice_id": "athanlab-default-female-v1",
    "number_mode": "smart"
  },
  "chapters": [
    {
      "index": 0,
      "title": "ရာသီဥတု",
      "characters": 59,
      "status": "succeeded",
      "duration_seconds": 6.48,
      "error": null
    },
    {
      "index": 1,
      "title": "ဈေးကွက်",
      "characters": 62,
      "status": "succeeded",
      "duration_seconds": 6.91,
      "error": null
    }
  ],
  "sources": [
    {
      "title": "မိုးလေဝသ ခန့်မှန်းချက်",
      "url": "https://example.com/weather"
    }
  ],
  "usage": {
    "characters_charged": 121,
    "characters_refunded": 0
  },
  "app_url": "https://athanlab.com/app/inbox/1679091c5a880faf6fb5e6087eb1b2dc",
  "notified": true,
  "metadata": {}
}

curl -sS https://api.athanlab.com/api/v1/voices \
  -H "X-API-Key: $ATHANLAB_API_KEY"

{
  "data": [
    {
      "id": "athanlab-default-female-v1",
      "name": "AthanLab Female",
      "category": "default",
      "source": "athanlab",
      "is_default": true
    },
    {
      "id": "athanlab-default-male-v1",
      "name": "AthanLab Male",
      "category": "default",
      "source": "athanlab",
      "is_default": false
    },
    {
      "id": "3c59dc048e8850243be8079a5c74d079",
      "name": "My narrator",
      "category": "custom",
      "source": "user",
      "is_default": false
    }
  ],
  "default_voice_id": "athanlab-default-female-v1"
}

curl -sS https://api.athanlab.com/api/v1/voices/$VOICE_ID/preview \
  -H "X-API-Key: $ATHANLAB_API_KEY"

{
  "id": "athanlab-default-female-v1",
  "name": "AthanLab Female",
  "url": "https://storage.example/athanlab-default-female-v1.wav?X-Amz-Signature=…",
  "expires_in": 3600
}

curl -sS https://api.athanlab.com/api/v1/usage \
  -H "X-API-Key: $ATHANLAB_API_KEY"

{
  "plan": "max",
  "entitled": true,
  "upgrade_url": null,
  "monthly": {
    "limit": 2000000,
    "used": 50000,
    "remaining": 1950000,
    "resets_at": "2026-10-21T00:00:00.000Z"
  },
  "tokens": {
    "balance": 0
  },
  "spendable": 1950000,
  "active_jobs": 1,
  "max_concurrent_jobs": 2,
  "key": {
    "id": "c4ca4238a0b923820dcc509a6f75849b",
    "monthly_char_budget": 500000,
    "used_this_month": 120000,
    "remaining": 380000,
    "resets_at": "2026-11-01T00:00:00.000Z"
  }
}

curl -sS https://api.athanlab.com/api/v1/openapi.json

Every error the API sends has the same JSON shape and an X-Request-Id header. Handle errors by four rules:

1. Branch on error.code, never on the message.
2. Retry only when error.retryable is true.
3. If the response has a Retry-After header, wait that many seconds before you retry.
4. If error.retryable is false, change the request before you send it again.

{
  "error": {
    "type": "rate_limit_error",
    "code": "concurrency_limit",
    "message": "This account already has the maximum number of jobs running. Retry after one finishes (see Retry-After).",
    "param": null,
    "retryable": true,
    "request_id": "req_4f1c2a9e0b7d6c5a3e8f1b2c",
    "doc_url": "https://athanlab.com/docs#errors-concurrency_limit",
    "details": {
      "active_jobs": 2,
      "max_concurrent_jobs": 2
    }
  }
}

Error fields

error.type

"authentication_error" | "permission_error" | "billing_error" | "rate_limit_error" | "service_unavailable" | "invalid_request_error" | "api_error"

Broad category of the error.

error.code

string

Machine-readable error code. New codes may be added; handle an unknown one by its HTTP status and retryable.

error.message

string

A human-readable explanation. Do not parse it.

error.param

string | null

The request field or header at fault, when there is one.

error.retryable

boolean

True when the same request may succeed later without changes (honor Retry-After).

error.request_id

string

Also sent as the X-Request-Id header. Quote it when you contact support.

pattern ^req_[0-9a-f]{24}$

error.doc_url

string

This error's entry in the documentation.

error.details

objectmay be absent

Structured context some errors carry, such as notice (a maintenance message), replacement (a removed endpoint's successor), required_scope, job_id (idempotency_conflict), active_jobs / max_concurrent_jobs (concurrency_limit), required / spendable (insufficient_characters) or required / monthly_char_budget / used_this_month / resets_at (key_budget_exceeded). On a delivery: delivery_id (idempotency_conflict) and active_deliveries / max_active_deliveries (concurrency_limit). New keys may be added.

error.upgrade_url

stringmay be absent

Where to fix a billing error.

Request IDs

Every response carries an X-Request-Id header, and an error repeats it as error.request_id. Quote it when you contact support.

Error codes

The codes are grouped by error.type. For a code not listed here, see Versioning.

Each limit applies per key, per account or per network, and each row says which. Your account is your AthanLab account: all its keys share the account limits.

Rate limits

Rate-limit headers

Every authenticated response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix seconds). They describe the key's bucket that counted the request: reads and writes have separate buckets.

Every retryable 429 carries Retry-After. Wait that long, and add random jitter when several workers share a key or network. 429 key_budget_exceeded is not retryable: the key has spent its monthly budget (see Per-key budgets).

Size and retention

Need more? Email support@athanlab.com with your use case.

Within /api/v1, changes are additive only: new endpoints, optional request fields, response fields, error codes and job-failure codes. Build clients that ignore fields they do not know. Handle a code you do not know by its retryable flag and, for an HTTP error, its status.

Anything that could break a working integration ships as a new version. Every key owner hears about it by email at least 90 days before the old behavior is removed.

Changelog

• AthanInbox: POST /deliveries and GET /deliveries/{id} send audio to the key owner’s AthanInbox on athanlab.com (see AthanInbox). An additive change: the version stays 1.0.0.
• 1.0.0: asynchronous speech jobs (/speech), voices, usage and the OpenAPI document.

Retired endpoints

The earlier preview endpoints POST /generate and GET /balance are retired and return 410 endpoint_removed. Sign-in-token access has been removed too: send an API key. Any other credential returns 401 invalid_api_key and counts toward the per-network limit on failed key checks.

Email support@athanlab.com with the request_id of the request in question and, for a job, its id. Never send your API key.

Reference generated from API 1.0.0 · API Terms version 2026-10-06