Audiobook

create project → add manuscript → parse into chapters → narrate → export ACX package → download
                                                              └──── completion webhook ────┘

export AUDIOPOD_API_KEY="ap_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export AP="https://api.audiopod.ai/api/v1"

# 1. Create a project
PID=$(curl -s -X POST "$AP/audiobook/projects" -H "X-API-Key: $AUDIOPOD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"The Lighthouse Keeper","author":"A. P. Tester"}' | jq -r .id)

# 2. Upload a manuscript (PDF / EPUB / DOCX / TXT)
FILE_KEY=$(curl -s -X POST "$AP/audiobook/projects/$PID/manuscript/upload" \
  -H "X-API-Key: $AUDIOPOD_API_KEY" -F "file=@book.epub" | jq -r .file_key)

# 3. Parse into chapters (async)
curl -s -X POST "$AP/audiobook/projects/$PID/manuscript/parse" \
  -H "X-API-Key: $AUDIOPOD_API_KEY" -F "file_key=$FILE_KEY" -F "filename=book.epub"

# 3b. Poll the PROJECT until parsing finishes — status tells you which way it went
while :; do
  P=$(curl -s "$AP/audiobook/projects/$PID?include_chapters=true" -H "X-API-Key: $AUDIOPOD_API_KEY")
  S=$(echo "$P" | jq -r .status)
  [ "$S" = "failed" ] && { echo "parse failed: $(echo "$P" | jq -r .error_message)"; exit 1; }
  [ "$(echo "$P" | jq -r .parsing_completed_at)" != "null" ] && break
  sleep 5
done
echo "$P" | jq '.chapters[] | {id, chapter_number, title}'

# 4. Narrate the whole project with a voice (omit chapter_ids/paragraph_ids = everything)
curl -s -X POST "$AP/audiobook/projects/$PID/narration/batch" \
  -H "X-API-Key: $AUDIOPOD_API_KEY" -H "Content-Type: application/json" \
  -d '{"voice_id":387}'

# 5. Export an ACX package, then download it
JOB=$(curl -s -X POST "$AP/audiobook/projects/$PID/export" \
  -H "X-API-Key: $AUDIOPOD_API_KEY" -H "Content-Type: application/json" -d '{}' | jq -r .job_id)
curl -s "$AP/audiobook/projects/$PID/export/$JOB/download" -H "X-API-Key: $AUDIOPOD_API_KEY"
# => { "download_url": "https://media.audiopod.ai/...zip?...", "file_size_bytes": ..., "chapter_count": ... }

curl -s "$AP/audiobook/projects/$PID?include_chapters=true" -H "X-API-Key: $AUDIOPOD_API_KEY"
# => { "id": "...", "status": "ready_for_narration", "total_chapters": 12,
#      "parsing_completed_at": "2026-07-23T09:14:02", "error_message": null,
#      "chapters": [ { "id": "...", "chapter_number": 1, "title": "...", ... } ] }

curl -s "$AP/audiobook/projects?page=2&per_page=50" -H "X-API-Key: $AUDIOPOD_API_KEY"

curl -X POST "$AP/audiobook/projects/$PID/manuscript/upload" \
  -H "X-API-Key: $AUDIOPOD_API_KEY" -F "file=@book.epub"

# JSON body
curl -X POST "$AP/audiobook/projects/$PID/manuscript/parse" \
  -H "X-API-Key: $AUDIOPOD_API_KEY" -H "Content-Type: application/json" \
  -d "{\"file_key\": \"$FILE_KEY\", \"filename\": \"book.epub\"}"

# ...or form fields (equivalent)
curl -X POST "$AP/audiobook/projects/$PID/manuscript/parse" \
  -H "X-API-Key: $AUDIOPOD_API_KEY" -F "file_key=$FILE_KEY" -F "filename=book.epub"
# => { "job_id": 99, "estimated_completion_time": "under 2 minutes" }

import time, requests

AP, H = "https://api.audiopod.ai/api/v1", {"X-API-Key": "ap_..."}

def wait_for_parse(pid: str, timeout_s: int = 900, interval_s: int = 5) -> list[dict]:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        p = requests.get(f"{AP}/audiobook/projects/{pid}",
                         params={"include_chapters": "true"}, headers=H).json()
        if p["status"] == "failed":                       # terminal failure
            raise RuntimeError(p.get("error_message") or "Manuscript parsing failed")
        if p.get("parsing_completed_at"):                 # terminal success
            return p["chapters"] or []
        time.sleep(interval_s)                            # still parsing
    raise TimeoutError("Manuscript parsing did not finish in time")

chapters = wait_for_parse(pid)
chapter_ids = [c["id"] for c in chapters]

curl -s "$AP/audiobook/projects/$PID/chapters?page=1&per_page=100" -H "X-API-Key: $AUDIOPOD_API_KEY"

# every paragraph in the chapter
curl -s "$AP/audiobook/projects/$PID/chapters/$CHAPTER_ID/paragraphs" \
  -H "X-API-Key: $AUDIOPOD_API_KEY" | jq '.paragraphs[] | {id, position, status}'

# or a page at a time
curl -s "$AP/audiobook/projects/$PID/chapters/$CHAPTER_ID/paragraphs?page=1&per_page=50" \
  -H "X-API-Key: $AUDIOPOD_API_KEY"

curl -X POST "$AP/audiobook/projects/$PID/paragraphs/$PARA_ID/narrate" \
  -H "X-API-Key: $AUDIOPOD_API_KEY" -H "Content-Type: application/json" \
  -d '{"voice_id":387,"emotion":"wistful"}'
# => { "task_id": "...", "paragraph_id": "...", "status": "queued",
#      "billing": { "is_free_regen": true, "estimated_credits": 0, "take_number_after": 2 } }

curl -X POST "https://api.audiopod.ai/api/v1/audiobook/projects/{project_id}/narration/cancel" \
  -H "X-API-Key: $AUDIOPOD_API_KEY"

{
  "voice_id": 389,
  "chapter_ids": ["<chapter-uuid>"],
  "include_completed": true
}

PUT /audiobook/projects/{project_id}/production-settings
{"silence": {"head_ms": 2000, "tail_ms": 2000}}

{ "silence": { "head_ms": 2000, "tail_ms": 2000, "acx_compliant": false },
  "warnings": ["head_ms 2000 is outside the ACX range 500–1000 ms; files may be rejected by ACX QA."] }

{ "detail": { "message": "Project is not ACX-compliant. Fix these issues first.",
              "issues": ["Chapter 3: 28s < ACX minimum 30s"], "warnings": [] } }

{ "download_url": "https://media.audiopod.ai/...acx_package_xxx.zip?...",
  "file_size_bytes": 2079760, "file_format": "zip", "chapter_count": 2 }

curl -X POST "$AP/webhooks/endpoints" -H "X-API-Key: $AUDIOPOD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-app.com/hooks/audiopod","events":["job.completed","job.failed","job.cancelled"]}'
# => { "id": "...", "url": "...", "events": [...], "secret": "whsec_..." }   # secret shown ONCE

import hmac, hashlib

def verify(secret: str, raw_body: bytes, signature_header: str, timestamp_header: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        timestamp_header.encode() + b"." + raw_body,   # exact raw bytes received
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature_header)