Voxscribe API Documentation

Integrate audio/video summarization, text-to-speech, and local file conversion into your own apps, products, or workflows.

Authentication

All requests require an API key. Pass your key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Generate and manage your API keys in your dashboard. Keep your API key secret!

Base URL

https://api.voxscribe.app

Credit System

All operations consume credits based on your plan. Credits are deducted for:

Endpoints

1. Summarize Video/Audio

POST /api/summarize

Request:

{
  "video_url": "https://www.youtube.com/watch?v=YOUR_VIDEO_ID",
  "prompt": "Summarize this",
  "save_summary": true // Optional, default: true
}

Set save_summary to false if you do not want the summary saved to your account or history. Only saved summaries deduct a credit and appear in your dashboard.

Headers:

Authorization: Bearer YOUR_API_KEY Content-Type: application/json

Response:

{
  "task_id": "abc123",
  "status": "processing"
}

2. Check Summarization Status

GET /api/summarize-status/{task_id}

Response:

{
  "status": "completed",
  "result": {
    "summary": "In this video, ...",
    "video_title": "Video Title"
  }
}

3. Generate Audio (Text-to-Speech)

POST /api/generate-audio

Request:

{
  "summary_text": "Your text to convert to audio",
  "preserve": false, // Optional: preserve permanently (+1 credit)
  "summary_id": 123 // Optional: link to existing summary
}

Headers:

Authorization: Bearer YOUR_API_KEY Content-Type: application/json

Response:

{
  "audio": "BASE64_ENCODED_AUDIO",
  "mime_type": "audio/wav",
  "audio_file_id": 456,
  "is_preserved": false,
  "generation_credits_deducted": true,
  "preservation_credits_deducted": false,
  "total_credits_deducted": 1,
  "expires_at": "2024-01-15T10:30:00Z"
}

4. Upload Audio File (Local Processing)

POST /api/upload-audio

Request:

Content-Type: multipart/form-data Form Data: - file: Audio file (max 100MB) - preserve: boolean (default: false) - optimize: boolean (default: true) - summary_id: integer (optional)

Supported Formats:

Headers:

Authorization: Bearer YOUR_API_KEY Content-Type: multipart/form-data

Response:

{
  "message": "Audio file uploaded and processed successfully",
  "audio_file_id": 789,
  "file_name": "abc123.wav",
  "file_size": 1024000,
  "mime_type": "audio/wav",
  "is_preserved": false,
  "generation_credits_deducted": true,
  "preservation_credits_deducted": false,
  "total_credits_deducted": 1,
  "expires_at": "2024-01-15T10:30:00Z",
  "conversion_metadata": {
    "duration_seconds": 30.5,
    "sample_rate": 22050,
    "channels": 1,
    "bit_depth": 16,
    "format": "wav"
  }
}

5. Convert Audio (Preview)

POST /api/convert-audio

Request:

Content-Type: multipart/form-data Form Data: - file: Audio file (max 100MB) - target_format: string (default: "wav") - optimize: boolean (default: true)

Convert audio files without storing them. Useful for previewing conversions before storage.

Response:

{
  "message": "Audio file converted successfully",
  "base64_data": "UklGRiQAAABXQVZFZm10IBAAAAABAAEA...",
  "mime_type": "audio/wav",
  "format": "wav",
  "original_format": "mp3",
  "file_size": 1024000,
  "metadata": {
    "duration_seconds": 30.5,
    "sample_rate": 22050,
    "channels": 1,
    "bit_depth": 16
  }
}

6. Validate Audio File

POST /api/validate-audio

Request:

Content-Type: multipart/form-data Form Data: - file: Audio file

Response:

{
  "valid": true,
  "message": "Audio file is valid",
  "file_size": 1024000,
  "detected_format": "mp3",
  "content_type": "audio/mpeg"
}

7. Get Supported Formats

GET /api/supported-formats

Response:

{
  "supported_formats": {
    "mp3": "audio/mpeg",
    "wav": "audio/wav",
    "ogg": "audio/ogg",
    "m4a": "audio/mp4",
    "flac": "audio/flac",
    "aac": "audio/aac",
    "wma": "audio/x-ms-wma"
  },
  "target_format": "wav",
  "target_mime_type": "audio/wav"
}

8. List Audio Files

GET /api/audio-files

Headers:

Authorization: Bearer YOUR_API_KEY

Response:

[
  {
    "id": 789,
    "file_name": "abc123.wav",
    "file_size": 1024000,
    "mime_type": "audio/wav",
    "is_preserved": false,
    "created_at": "2024-01-15T10:00:00Z",
    "expires_at": "2024-01-16T10:00:00Z",
    "summary_id": 123
  }
]

9. Get Audio File

GET /api/audio-files/{audio_file_id}

Headers:

Authorization: Bearer YOUR_API_KEY

Response:

{
  "id": 789,
  "file_name": "abc123.wav",
  "file_size": 1024000,
  "mime_type": "audio/wav",
  "is_preserved": false,
  "created_at": "2024-01-15T10:00:00Z",
  "expires_at": "2024-01-16T10:00:00Z",
  "audio_data": "BASE64_ENCODED_AUDIO"
}

10. Preserve Audio File

POST /api/audio-files/{audio_file_id}/preserve

Convert a temporary audio file to permanent storage (deducts 1 credit).

Headers:

Authorization: Bearer YOUR_API_KEY

Response:

{
  "message": "Audio file preserved successfully"
}

11. Delete Audio File

DELETE /api/audio-files/{audio_file_id}

Headers:

Authorization: Bearer YOUR_API_KEY

Response:

{
  "message": "Audio file deleted successfully"
}

12. Health Check

GET /health

Response:

{ "status": "ok" }

Local File Processing Benefits

Error Handling

Example error:

{ 
  "error": "Insufficient credits for generate. Required: 1, Available: 0",
  "credits_required": true
}

Best Practices

Example cURL Requests

Summarize Video

curl -X POST https://api.voxscribe.app/api/summarize \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"video_url": "https://www.youtube.com/watch?v=YOUR_VIDEO_ID", "prompt": "Summarize this"}'

Upload Audio File

curl -X POST https://api.voxscribe.app/api/upload-audio \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@audio.mp3" \
  -F "preserve=true" \
  -F "optimize=true"

Convert Audio Preview

curl -X POST https://api.voxscribe.app/api/convert-audio \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@audio.mp3" \
  -F "target_format=wav" \
  -F "optimize=true"

Generate Audio from Text

curl -X POST https://api.voxscribe.app/api/generate-audio \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"summary_text": "Your text to convert to audio", "preserve": false}'

Support

For help, contact: support@voxscribe.app

Changelog