Text-to-Speech API

Submit plain text and get a single rendered audio file. A lean, single-voice endpoint — no character detection, portraits, scenes, or music. For full audiobook production use the Audiobook API.

Quick Start

Submit text, poll for completion, fetch the audio URL.

1. Submit text

bash

curl -X POST https://notevibes.com/api/tts/create \
  -H "Authorization: Bearer nvb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Welcome message",
    "content": "Hello, and welcome to Notevibes.",
    "voice": "en-US-Chirp3-HD-Achernar"
  }'

2. Poll for completion

bash

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

3. When status is "completed", download result.audioUrl

Create TTS Job

POST

/api/tts/create

Submit plain text to be rendered as a single-voice audio file. Returns immediately with a job ID — synthesis runs asynchronously.

Request Body

Parameter	Type	Description
`title`*	string	Label for the job. Shows up in the status response and in your library.
`content`*	string	The text to synthesize. Plain text only.
`voice`	string	Voice ID. Default: "en-US-Chirp3-HD-Achernar". Three forms: a catalog id ({locale}-Chirp3-HD-{Name}), a library voice ("lib:…") or one of your cloned voices ("clone:…"). See the Voices tab.

Example

bash

curl -X POST https://notevibes.com/api/tts/create \
  -H "Authorization: Bearer nvb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Episode intro",
    "content": "Welcome back to the show. Today we dive into AI voice technology.",
    "voice": "en-US-Chirp3-HD-Leda"
  }'

Response

json

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

Error Responses

Status	Reason
`400`	Missing title or content, malformed voice ID, or a cloned voice that is not ready
`401`	Invalid or missing API key
`402`	Insufficient credits
`403`	API key lacks write permission, or the cloned voice belongs to another workspace
`404`	Unknown library or cloned voice

List Jobs

GET

/api/tts/jobs

List TTS jobs for the authenticated organization, newest first. Returns a slim view — fetch /api/tts/jobs/:jobId for the full result payload (including audioUrl).

Query Parameters

Parameter	Type	Description
`status`	string	Filter by status: "queued", "processing", "completed", or "failed".
`limit`	number	Max jobs to return (1–100). Default: 20.
`cursor`	string	Job ID from the previous response’s nextCursor. Used for pagination.

Example

bash

curl "https://notevibes.com/api/tts/jobs?status=completed&limit=20" \
  -H "Authorization: Bearer nvb_your_api_key"

Response

json

{
  "jobs": [
    {
      "jobId": "abc123def456",
      "status": "completed",
      "step": "completed",
      "title": "Episode intro",
      "estimatedCredits": 68,
      "createdAt": "2026-04-18T14:23:01.000Z",
      "updatedAt": "2026-04-18T14:23:14.000Z"
    }
  ],
  "nextCursor": "abc123def456"
}

If nextCursor is non-null, pass it back as ?cursor=... to fetch the next page.

List Voices

GET

/api/tts/voices

List the library voices and your workspace's cloned voices. Use each entry's id as the voice when creating a job. Requires read permission.

Query Parameters

Parameter	Type	Description
`locale`	string	Only library voices in this locale, e.g. "en-US" (case-insensitive). Cloned voices are always returned.
`gender`	string	Only library voices of this gender, e.g. "female" or "male". Cloned voices are always returned.

Example

bash

curl "https://notevibes.com/api/tts/voices?locale=en-US" \
  -H "Authorization: Bearer nvb_your_api_key"

Response

json

{
  "library": [
    {
      "id": "lib:en-us-storyteller-1",
      "name": "Abigail",
      "locale": "en-US",
      "gender": "female",
      "age": "young adult",
      "pitch": "high",
      "energy": "energetic",
      "accent": "General American",
      "description": "Higher-pitched, expressive reading style with animated emphasis and bright theatrical coloring.",
      "bestFor": ["kids stories", "audiobook narration", "education"],
      "sampleUrl": "https://storage.googleapis.com/notevibes-public/public/voices/library/v1/samples/en-us-storyteller-1.mp3"
    }
  ],
  "cloned": [
    {
      "id": "clone:org_abc123:vx9Kq2",
      "name": "My voice",
      "locale": "en-US",
      "status": "ready",
      "createdAt": "2026-09-20T10:12:44.000Z"
    }
  ]
}

The full library is returned in one response. Play sampleUrl to audition a voice before using it.

Get Job Status

GET

/api/tts/jobs/:jobId

Poll this endpoint to track progress. Recommended interval: every 3-5 seconds for short text.

Response (Processing)

json

{
  "jobId": "abc123def456",
  "status": "processing",
  "step": "generating_audio",
  "title": "Episode intro",
  "progress": { "currentChapter": 0, "totalChapters": 1 },
  "estimatedCredits": 68
}

Response (Queued)

json

{
  "jobId": "abc123def456",
  "status": "queued",
  "queuePosition": 3,
  "title": "Episode intro",
  "estimatedCredits": 68
}

Response (Completed)

json

{
  "jobId": "abc123def456",
  "status": "completed",
  "step": "completed",
  "title": "Episode intro",
  "progress": { "currentChapter": 1, "totalChapters": 1 },
  "estimatedCredits": 68,
  "result": {
    "audioUrl": "https://storage.googleapis.com/notevibes.com/...?X-Goog-Signature=...",
    "audioUrlExpiresIn": 3600,
    "duration": 9.4,
    "credits": {
      "total": 68,
      "remaining": 9932,
      "breakdown": []
    }
  }
}

audioUrl is a fresh signed URL that expires in audioUrlExpiresIn seconds (1 hour). Re-poll this endpoint to get a new URL if the previous one expired.

Response (Failed)

json

{
  "jobId": "abc123def456",
  "status": "failed",
  "error": "Pipeline failed"
}

Status Values

Status	Meaning
`queued`	Waiting for a processing slot. See `queuePosition`.
`processing`	Synthesis in progress.
`completed`	Done. `result.audioUrl` is ready.
`failed`	Job failed. See `error`.