API Documentation

REST API for text-to-speech generation. Base URL: https://voxnutshell.com/api/v1

Authentication

All API requests require a Bearer token. Create an API key from your dashboard.

curl https://voxnutshell.com/api/v1/tts \
  -H "Authorization: Bearer vnk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello world", "voice": "voice-uuid"}'

Rate limits

Plan	Requests/min	Parallel jobs	Chars/month
Free	3	1	10,000
Starter	10	2	200,000
Creator	10	3	600,000
Pro	10	5	2,000,000

Endpoints

POST/api/v1/tts

Generate speech from text. Returns a job ID for async polling.

Request body

{
  "text": "Your text to convert to speech",
  "voice": "voice-uuid"  // optional, defaults to first preset
}

Response

{
  "job_id": "uuid",
  "chars": 35,
  "status": "pending"
}

Errors

400 — Invalid input (empty text, bad voice ID)
403 — Character limit exceeded
429 — Rate limit or too many parallel jobs

GET/api/v1/tts/:jobId

Check the status of a generation job. Poll every 1-2 seconds until completed or failed.

Response (processing)

{
  "status": "processing",
  "audio_url": null,
  "duration": null,
  "chars": 35
}

Response (completed)

{
  "status": "completed",
  "audio_url": "https://r2.voxnutshell.com/audio/job-id.mp3",
  "duration": 3.5,
  "chars": 35
}

GET/api/v1/voices

List available voices, including your custom cloned voices.

Response

{
  "voices": [
    {
      "id": "uuid",
      "name": "Emma",
      "language": "English",
      "description": "Warm, professional",
      "type": "preset"
    },
    {
      "id": "uuid",
      "name": "My Voice",
      "language": "Italian",
      "description": "Cloned voice (youtube)",
      "type": "custom"
    }
  ]
}

Full example

# 1. Generate speech
JOB=$(curl -s https://voxnutshell.com/api/v1/tts \
  -H "Authorization: Bearer vnk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello from VoxNutshell!"}')
JOB_ID=$(echo $JOB | jq -r .job_id)

# 2. Poll until complete
while true; do
  STATUS=$(curl -s https://voxnutshell.com/api/v1/tts/$JOB_ID \
    -H "Authorization: Bearer vnk_your_key")
  echo $STATUS | jq .status
  if echo $STATUS | jq -e '.status == "completed"' > /dev/null; then
    break
  fi
  sleep 2
done

# 3. Download audio
URL=$(echo $STATUS | jq -r .audio_url)
curl -o output.mp3 $URL

Python and Node.js SDKs coming soon.

For now, use the REST API with any HTTP client.