API Reference

The Lalia API is a conventional REST API: predictable resource URLs, JSON request and response bodies, and standard HTTP status codes. Every response includes a request_id you can quote to support.

https://api.laliabook.com/v1

Local sandbox: http://localhost:3002/api/v1

Authentication

Authenticate with your secret key in the Authorization header. Keys are created in the dashboard and start with lalia_sk_live_. Keep them server-side — never ship a key in client code.

curl https://api.laliabook.com/v1/usage \
  -H "Authorization: Bearer lalia_sk_live_e91b4c…"

Errors

Errors use standard status codes and a consistent envelope. The code is stable and safe to branch on.

{
  "error": {
    "code": "invalid_api_key",
    "message": "Missing or invalid API key. Pass it as: Authorization: Bearer <key>"
  },
  "request_id": "req_5c1f0a92b3d84e07a6f1"
}

Status	Code	Meaning
400	invalid_request	Malformed body or missing parameter
400	text_too_long	Page text over 6,000 characters
401	invalid_api_key	Key missing, revoked, or malformed
429	rate_limited	Too many requests — retry after the reset window
502	upstream_error	A dependency failed — safe to retry

Rate limits

Default limits are 300 requests/minute per key (narration: 60/minute). Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. Need more? Limits are raised automatically on the Growth plan.

POST/v1/narrate

Convert one page of text (up to 6,000 characters) into narrated audio. Returns a URL that streams WAV audio, playable directly in an <audio> element. Identical text, voice, and language always resolve to the same cached narration — repeat calls are served from cache and not billed twice.

Parameter		Description
text	Required	The page text to narrate, ≤ 6,000 characters
language	Optional	BCP-47 code: en es fr de it pt so ar zh ja. Default en
voice	Optional	amber cove juniper sol vale. Default amber

Request

curl https://api.laliabook.com/v1/narrate \
  -H "Authorization: Bearer $LALIA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "It was the best of times, it was the worst of times…",
    "language": "en",
    "voice": "amber"
  }'

Response · 200

{
  "object": "narration",
  "narration_id": "narr_9f2c41d07ab3e8c2",
  "status": "ready",
  "audio_url": "https://api.laliabook.com/v1/audio/narr_9f2c41d07ab3e8c2",
  "format": "wav",
  "voice": "amber",
  "language": "en",
  "characters": 52,
  "cached": true,
  "billing": { "billable": true, "unit_price_usd": 0.012 },
  "request_id": "req_c02b7c1e4f9a4d33b6c8"
}

POST/v1/translate

Translate one page of text into a target language, tuned for literary prose rather than word-for-word output. Chain it with /v1/narrateto offer “listen in Spanish” on any book.

Parameter		Description
text	Required	The page text to translate
target_language	Required	en es fr de it pt so ar zh ja

Response · 200

{
  "object": "translation",
  "target_language": "es",
  "translated_text": "Era el mejor de los tiempos, era el peor de los tiempos…",
  "characters": 52,
  "billing": { "billable": true, "unit_price_usd": 0.004 },
  "request_id": "req_a81d3f7c2e5b49d0a1f2"
}

GET/v1/catalog/search

Search 75,000+ public-domain titles with covers, author metadata, and summaries. Use it to stock a library shelf without licensing content — everything returned is free to display, translate, and narrate.

Parameter		Description
q	Optional	Free-text title/author search
topic	Optional	Subject filter, e.g. science fiction
page	Optional	Page number. Empty query returns the most popular titles

Request

curl "https://api.laliabook.com/v1/catalog/search?q=sherlock%20holmes" \
  -H "Authorization: Bearer $LALIA_KEY"

Response · 200

{
  "object": "catalog.search",
  "count": 32,
  "results": [
    {
      "book_id": 1661,
      "title": "The Adventures of Sherlock Holmes",
      "authors": "Doyle, Arthur Conan",
      "languages": ["en"],
      "cover_url": "https://www.gutenberg.org/cache/epub/1661/pg1661.cover.medium.jpg",
      "summary": "A collection of twelve short stories…",
      "popularity": 104201
    }
  ],
  "billing": { "billable": true, "unit_price_usd": 0.0005 },
  "request_id": "req_e33a9b0d17c64f8ab2d0"
}

GET/v1/usage

Your metered usage for the current window — per endpoint, per day, with the running spend estimate. Free to call, so you can pipe it into your own admin dashboards.

Response · 200

{
  "object": "usage.summary",
  "plan": "payg",
  "window_days": 14,
  "totals": { "narrate": 1482, "catalog": 903, "translate": 456 },
  "total_calls": 2841,
  "estimated_cost": 20.06,
  "days": [ { "date": "2026-08-01", "narrate": 141, "catalog": 86, "translate": 40 }, … ],
  "request_id": "req_77b1c94e02d84f61a3e5"
}