API Documentation
v1.0Get API Key

Fyncast API Documentation

Build powerful podcast and audiobook applications with the Fyncast API. Generate AI-powered scripts, create dual-voice podcasts, and convert text to audiobooks.

REST API

JSON responses

Enterprise Ready

API key auth

Fast Generation

Fast script + audio generation

Base URL

url
https://fyncast-api-production.up.railway.app/api

Authentication

All API requests require authentication using an API key. Include your API key in theAuthorization header.

Note: API access is only available on the Enterprise plan (€349/month). Generate your API key from the B2B Dashboard.

bash
curl -X GET "https://fyncast-api-production.up.railway.app/api/podcasts" \
  -H "Authorization: Bearer fyn_live_sk_YOUR_API_KEY" \
  -H "Content-Type: application/json"

API Key Format

API keys follow this format: fyn_{env}_sk_{random}

  • fyn_live_sk_* - Production keys
  • fyn_test_sk_* - Test/development keys

Podcasts

Generate AI-powered podcast scripts and audio with dual-voice synthesis.

GET/podcasts

List all podcasts for the authenticated user.

Response

json
{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "title": "AI in Healthcare",
      "description": "A discussion about AI trends",
      "status": "completed",
      "audio_url": "https://...",
      "duration": 300,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}
GET/podcasts/:id

Get details of a specific podcast including segments.

POST/podcasts/generate-script

Generate a podcast script from a topic. Returns a preview before audio generation.

Request Body

json
{
  "topic": "The future of artificial intelligence",
  "duration": 10,        // minutes (5-45)
  "language": "en",      // en, it, es, fr, de
  "mood": "informative", // informative, casual, educational, entertaining
  "singleSpeaker": false // true for monologue
}

Response

json
{
  "success": true,
  "data": {
    "script": {
      "title": "The Future of AI",
      "segments": [
        {
          "speaker": "speaker1",
          "text": "Welcome to our podcast...",
          "emotion": "excited"
        }
      ]
    },
    "estimatedDuration": 10,
    "totalWords": 1500,
    "segmentCount": 24,
    "model": "GPT-4o"
  }
}
POST/podcasts/render-from-script

Render audio from a previously generated script. This creates the final podcast audio.

Request Body

json
{
  "script": { /* script object from generate-script */ },
  "voice1": "alloy",     // Primary voice
  "voice2": "echo",      // Secondary voice
  "quality": "tts-1-hd", // tts-1 (standard) or tts-1-hd
  "language": "en",
  "topic": "AI Discussion",
  "targetDuration": 10   // Target duration in minutes
}

Available Voices

alloy
echo
fable
onyx
nova
shimmer
POST/podcasts/generate

Generate a complete podcast in one step (script + audio). Longer timeout required.

Request Body

json
{
  "topic": "Climate change solutions",
  "duration": 10,
  "language": "en",
  "mood": "informative",
  "voice1": "nova",
  "voice2": "onyx",
  "quality": "tts-1-hd"
}
DELETE/podcasts/:id

Delete a podcast and its associated audio files.

Voice Profiles

Manage voice profiles including voice samples and custom voice clones.

GET/voice

List all voice profiles for the authenticated user.

GET/voice/sample/:voiceId

Get a voice sample preview for stock voices. Supports language parameter.

Query Parameters

bash
GET /voice/sample/alloy?lang=en

Supported languages: en, it, es, fr, de, pt

POST/voice/enroll

Enroll a custom voice profile with audio sample. Requires consent for BIPA/GDPR compliance.

Request (multipart/form-data)

bash
curl -X POST "https://fyncast-api-production.up.railway.app/api/voice/enroll" \
  -H "Authorization: Bearer fyn_live_sk_YOUR_API_KEY" \
  -F "audioSample=@voice_sample.mp3" \
  -F "name=My Voice" \
  -F "consentText=I consent to voice processing..." \
  -F "consentConfirmed=true" \
  -F "ageVerified=true" \
  -F "thirdPartyConsent=true"
PUT/voice/:id

Update a voice profile name or default status.

POST/voice/:id/revoke

Revoke consent for a voice profile. Triggers GDPR/BIPA compliant deletion process.

DELETE/voice/:id

Permanently delete a voice profile and associated data.

Audiobooks

Convert text documents into audiobooks. Supports PDF, DOCX, and TXT files.

Tier Restrictions: Audiobook creation requires Basic plan or higher. Basic: 1 chapter, Creator/Pro: Unlimited chapters, Enterprise: HD quality + no watermark.

GET/audiobooks

List all audiobooks for the authenticated user.

POST/audiobooks/upload

Upload a document file (PDF, DOCX, TXT) to convert to audiobook.

Request (multipart/form-data)

bash
curl -X POST "https://fyncast-api-production.up.railway.app/api/audiobooks/upload" \
  -H "Authorization: Bearer fyn_live_sk_YOUR_API_KEY" \
  -F "file=@book.pdf" \
  -F "voiceId=nova" \
  -F "title=My Audiobook"
POST/audiobooks

Create an audiobook from raw text.

Request Body

json
{
  "title": "My Audiobook",
  "text": "Chapter 1: Introduction\n\nThis is the content...",
  "voiceId": "nova"
}
GET/audiobooks/:id

Get audiobook details including processing status and chapters.

GET/audiobooks/:id/download

Download the completed audiobook file (MP3).

POST/audiobooks/:id/cancel

Cancel an audiobook that is currently being processed.

DELETE/audiobooks/:id

Delete an audiobook and its audio files.

Users

GET/users/profile

Get the authenticated user's profile information.

Response

json
{
  "success": true,
  "data": {
    "id": "uuid",
    "email": "user@example.com",
    "fullName": "John Doe",
    "subscriptionTier": "enterprise",
    "subscriptionStatus": "active",
    "createdAt": "2024-01-01T00:00:00Z"
  }
}
PUT/users/profile

Update user profile information.

json
{ "fullName": "New Name" }

Subscriptions

GET/subscriptions/tiers

Get all available subscription tiers and their features.

GET/subscriptions/current

Get the current user's subscription details.

GET/subscriptions/usage

Get current usage statistics against subscription limits.

Response

json
{
  "success": true,
  "data": {
    "podcastsUsed": 15,
    "podcastsLimit": -1,
    "minutesUsed": 450,
    "minutesLimit": 4000,
    "voiceProfilesUsed": 3,
    "voiceProfilesLimit": -1,
    "periodStart": "2024-01-01",
    "periodEnd": "2024-01-31"
  }
}

Rate Limits

API requests are rate limited to ensure fair usage. Rate limit headers are included in all responses.

TierRequests/minGeneration/hour
Free103
Basic3010
Creator6020
Pro10050
Enterprise1000Unlimited

Rate Limit Headers

http
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1705320000

Error Handling

The API uses standard HTTP status codes and returns errors in a consistent JSON format.

json
{
  "status": "fail",
  "message": "Detailed error message",
  "code": "ERROR_CODE"
}

HTTP Status Codes

CodeDescription
200Success
201Created successfully
400Bad request - Invalid parameters
401Unauthorized - Invalid or missing API key
403Forbidden - Subscription or usage limit exceeded
404Not found - Resource does not exist
429Too many requests - Rate limit exceeded
500Server error - Please retry or contact support

Code Examples

Node.js / TypeScript

typescript
import axios from 'axios';

const API_KEY = 'fyn_live_sk_YOUR_API_KEY';
const BASE_URL = 'https://fyncast-api-production.up.railway.app/api';

const api = axios.create({
  baseURL: BASE_URL,
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  }
});

// Generate a podcast
async function generatePodcast() {
  // Step 1: Generate script
  const scriptRes = await api.post('/podcasts/generate-script', {
    topic: 'The future of AI',
    duration: 10,
    language: 'en',
    mood: 'informative'
  });

  // Step 2: Render audio
  const audioRes = await api.post('/podcasts/render-from-script', {
    script: scriptRes.data.data.script,
    voice1: 'nova',
    voice2: 'onyx',
    quality: 'tts-1-hd'
  });

  console.log('Podcast created:', audioRes.data.data.audio_url);
}

generatePodcast();

Python

python
import requests

API_KEY = 'fyn_live_sk_YOUR_API_KEY'
BASE_URL = 'https://fyncast-api-production.up.railway.app/api'

headers = {
    'Authorization': f'Bearer {API_KEY}',
    'Content-Type': 'application/json'
}

# Generate a podcast
def generate_podcast():
    # Step 1: Generate script
    script_res = requests.post(
        f'{BASE_URL}/podcasts/generate-script',
        headers=headers,
        json={
            'topic': 'The future of AI',
            'duration': 10,
            'language': 'en',
            'mood': 'informative'
        }
    )
    script = script_res.json()['data']['script']

    # Step 2: Render audio
    audio_res = requests.post(
        f'{BASE_URL}/podcasts/render-from-script',
        headers=headers,
        json={
            'script': script,
            'voice1': 'nova',
            'voice2': 'onyx',
            'quality': 'tts-1-hd'
        }
    )

    print('Podcast created:', audio_res.json()['data']['audio_url'])

generate_podcast()

cURL

bash
# List all podcasts
curl -X GET "https://fyncast-api-production.up.railway.app/api/podcasts" \
  -H "Authorization: Bearer fyn_live_sk_YOUR_API_KEY"

# Generate a podcast script
curl -X POST "https://fyncast-api-production.up.railway.app/api/podcasts/generate-script" \
  -H "Authorization: Bearer fyn_live_sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "Climate change solutions",
    "duration": 10,
    "language": "en",
    "mood": "informative"
  }'

Need Help?

Enterprise customers have access to dedicated 24/7 support. Contact us for technical assistance.

support@fyncast.comEnterprise Dashboard