Audiobook API

Upload a file or submit text to produce a full audiobook with multi-voice narration, character portraits, scene illustrations, and published library entry. For lean single-voice synthesis, see the Text-to-Speech API.

Quick Start

Upload an EPUB and get a fully produced audiobook with AI narration, character portraits, and scene illustrations.

1. Upload a file

bash

curl -X POST https://notevibes.com/api/audiobook/create \
  -H "Authorization: Bearer nvb_your_api_key" \
  -F "[email protected]" \
  -F "title=My Book" \
  -F "multiVoice=true" \
  -F "generatePortraits=true" \
  -F "generateScenes=true" \
  -F "publish=true"

2. Poll for completion

bash

curl https://notevibes.com/api/audiobook/jobs/{jobId} \
  -H "Authorization: Bearer nvb_your_api_key"

Create Audiobook

POST

/api/audiobook/create

Submit text or upload a file to produce a full audiobook. Accepts either JSON (for raw text/HTML) or multipart FormData (for file uploads). Returns immediately with a job ID — generation runs asynchronously.

JSON Request Body

Parameter	Type	Description
`title`*	string	Book title
`content`*	string	Full text of the book. Chapters are auto-detected from headings.
`contentType`	string	"text/plain" (default) or "text/html". Plain text splits on chapter heading patterns; HTML splits on <h1>/<h2> tags.
`settings.voice`	string	Default narrator voice ID. Default: "en-US-Chirp3-HD-Achernar".
`settings.multiVoice`	boolean	Enable AI character detection and multi-voice narration. Default: true.
`settings.speakingRate`	number	Speaking rate multiplier (0.5 - 2.0). Default: 1.0.
`settings.generatePortraits`	boolean	Generate AI character portraits and book cover. Default: false.
`settings.generateScenes`	boolean	Generate AI scene illustrations for each chapter. Default: false.
`settings.sceneDensity`	string	"chapter" (1 per chapter) or "scene" (1 per detected scene). Default: "chapter".
`settings.readAlong`	boolean	Generate word-level read-along sync timings for each chapter. Default: false.
`settings.batch`	boolean	Use batch mode for portraits/scenes (cheaper, async). When false, generates inline (slower but immediate). Default: true.
`settings.publish`	boolean	Publish to library as public after completion. Default: false (private draft).
`settings.backgroundMusic`	boolean	Generate AI background music per chapter (mixed under narration). Costs 6,000 credits per chapter. Default: false.
`settings.musicStyle`	string	Optional music style hint (e.g. "calm piano", "orchestral", "lo-fi"). Used with backgroundMusic or lullabies.
`settings.autoTagEmotions`	boolean	Auto-insert Gemini 3.1 inline emotion/delivery [tags] (e.g. [whispers], [long pause], [menacing]) into each chapter before audio generation. Uses character detection outputs when available, otherwise tags purely from text. Default: false.

FormData Fields (File Upload)

Parameter	Type	Description
`file`*	File	The book file (EPUB, PDF, DOCX, TXT, AZW3, MOBI).
`title`	string	Book title. If omitted, derived from filename.
`voice`	string	Default narrator voice ID.
`multiVoice`	string	"true" or "false". Default: "true".
`speakingRate`	string	Speaking rate as string number.
`generatePortraits`	string	"true" to generate AI portraits + cover.
`generateScenes`	string	"true" to generate scene illustrations.
`sceneDensity`	string	"chapter" or "scene".
`readAlong`	string	"true" to generate word-level read-along sync.
`batch`	string	"false" for fast inline image generation. Default: "true" (batch).
`publish`	string	"true" to publish publicly after completion.
`backgroundMusic`	string	"true" to generate AI background music per chapter.
`musicStyle`	string	Optional music style hint (e.g. "calm piano").
`autoTagEmotions`	string	"true" to auto-insert Gemini 3.1 inline emotion/delivery [tags] into each chapter before audio generation.

Response

json

{
  "jobId": "abc123def456",
  "status": "processing",
  "estimatedCredits": 4500
}

Error Responses

Status	Reason
`400`	Missing required fields or unsupported file type
`401`	Invalid or missing API key
`402`	Insufficient credits
`403`	API key lacks write permission

Bedtime Stories & Lullabies

POST

/api/audiobook/create

Generate AI-powered personalized bedtime stories or lullabies. Set sourceType to "bedtime-story" for a narrated story or "bedtime-lullaby" for a fully sung lullaby.

Request Body

Parameter	Type	Description
`sourceType`*	string	"bedtime-story" (narrated) or "bedtime-lullaby" (sung by AI).
`characters`*	string	Character names (e.g. "Emma and Buddy the dog").
`prompt`	string	Creative direction for the story or lullaby. Auto-generated from characters if omitted.
`duration`	string	"mini" (~2-5 min), "short" (~5-8 min), or "medium" (~10-15 min). Stories only. Default: "short".
`language`	string	Language code (e.g. "en", "es"). Default: "en".
`settings.voice`	string	Narrator voice ID. Default: "en-US-Chirp3-HD-Achernar".
`settings.backgroundMusic`	boolean	Add instrumental background music under narration. Stories only. Default: false.
`settings.generatePortraits`	boolean	Generate character portraits and cover. Default: true for stories, false for lullabies.
`settings.generateScenes`	boolean	Generate scene illustrations. Default: true for stories, false for lullabies.
`settings.publish`	boolean	Publish to library after completion. Default: false.

Bedtime Story Example

bash

curl -X POST https://notevibes.com/api/audiobook/create \
  -H "Authorization: Bearer nvb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceType": "bedtime-story",
    "characters": "Luna and her cat Whiskers",
    "prompt": "An adventure about stargazing, for a 5 year old who loves painting",
    "duration": "short",
    "settings": {
      "backgroundMusic": true,
      "generatePortraits": true,
      "publish": true
    }
  }'

Lullaby Example

bash

curl -X POST https://notevibes.com/api/audiobook/create \
  -H "Authorization: Bearer nvb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceType": "bedtime-lullaby",
    "characters": "Mia",
    "prompt": "A gentle lullaby about butterflies and flowers, soft acoustic guitar",
    "settings": {
      "publish": true
    }
  }'

Credits

Type	Cost
Bedtime story (narration)	TTS credits based on word count
Background music (per chapter)	6,000 credits
Character song (each)	6,000 credits
Lullaby	6,000 credits (fixed)

Get Job Status

GET

/api/audiobook/jobs/:jobId

Poll this endpoint to track progress. Recommended interval: every 5-10 seconds.

Response (Completed)

json

{
  "jobId": "abc123def456",
  "status": "completed",
  "step": "completed",
  "title": "My Book",
  "progress": { "currentChapter": 12, "totalChapters": 12 },
  "estimatedCredits": 4500,
  "result": {
    "bookId": "lib_xyz789",
    "slug": "my-book",
    "libraryUrl": "/library/my-book",
    "exportUrls": {
      "zipUrl": "https://storage.googleapis.com/.../chapters.zip",
      "mergedUrl": "https://storage.googleapis.com/.../full-book.mp3"
    },
    "totalDuration": 3600,
    "chapterCount": 12,
    "creditsUsed": 4320,
    "portraits": {
      "generated": 5,
      "coverUrl": "https://storage.googleapis.com/.../cover.webp"
    },
    "scenes": {
      "status": "submitted",
      "batchName": "projects/.../batchPredictionJobs/123"
    },
    "readAlong": {
      "status": "submitted",
      "submitted": 12
    }
  }
}

Pipeline Steps

Step	Description
`queued`	Waiting for a processing slot
`parsing_file`	Parsing uploaded file (EPUB, PDF, etc.)
`creating_document`	Setting up the production document
`splitting_chapters`	Splitting content into chapters
`generating_story`	AI story generation (bedtime stories only)
`generating_lullaby`	AI lullaby lyrics + music generation (lullabies only)
`detecting_characters`	AI character detection and voice assignment
`generating_audio`	TTS synthesis (track via progress.currentChapter)
`generating_music`	Background music generation and mixing
`exporting`	Merging audio and creating ZIP
`adding_to_library`	Creating the library entry
`generating_cover`	AI cover art generation
`submitting_batches`	Submitting portraits, scenes, and read-along sync
`publishing`	Making the book publicly visible
`completed`	All done