Quickstart

This guide will get you all set up and ready to use the Lettercast API. We'll cover how to authenticate and make your first API request. We'll also look at where to go next to find all the information you need to take full advantage of our powerful REST API.

Authentication

Lettercast uses an API key for authentication. You'll need to include your access token in the Authorization header of your requests:

const headers = {
  Authorization: `Bearer API_KEY`,
}

Making your first API request

Now that you have your API key, you're ready to make your first call to the Lettercast API. Let's start by sending a GET request to the Pods endpoint to get a list of all your pods.

// JS implementation using fetch
fetch('https://app.lettercast.ai/v1/pods', {
  headers: {
    Authorization: `Bearer ${API_KEY}`,
  },
})
  .then((response) => {
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`)
    }
    return response.json()
  })
  .then((data) => {
    console.log(data)
  })
  .catch((error) => {
    console.error('Error:', error)
  })

This request will return a list of all your pods, including their IDs, titles, sources, and other details as defined in the pod schema.

Creating a new pod

To create a new pod, you can send a POST request to the Pods endpoint. You can create a pod from a URL, a PDF file, or HTML content:

Creating a pod from a URL

const data = {
  url: 'https://ia.samaltman.com/',
  intro_plug_text: "This is with custom voices, made by Lettercast",
  outro_plug_text: "This is the outro plug text",
  host_configs: [
    {
      name: "Ben",
      voice_config: { voice_name: "jensen" }
    },
    {
      name: "Julia",
      voice_config: { voice_name: "mira" }
    }
  ],
  has_music: false
};

fetch('https://app.lettercast.ai/v1/pods', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(data),
})
  .then((response) => {
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`)
    }
    return response.json()
  })
  .then((data) => {
    console.log(data)
  })
  .catch((error) => {
    console.error('Error:', error)
  })

Creating a pod from HTML content

const data = {
  html_content: `
    <html lang="en">
    <head>
        <title>Impact of Lettercast Generation API on the World</title>
    </head>
    <body>
        <h1>How an API for Lettercast Generation Can Impact the World</h1>
        <p>Podcasts are an increasingly popular way to consume content. However, creating podcasts from written material can be time-consuming. A <strong>Lettercast Generation API</strong> solves this by automating the process, allowing articles, reports, and more to be converted into podcasts quickly. This innovation can transform how we engage with information.</p>
        <h2>1. Democratizing Information</h2>
        <p>This API makes content accessible to people with reading disabilities, language barriers, or low literacy. Audio content can be consumed anywhere, helping spread knowledge to a broader audience.</p>
        <h2>2. Enhancing Education</h2>
        <p>Students and educators can turn reading materials into podcasts, allowing for flexible learning. It supports auditory learners and makes education accessible for those with reading difficulties or visual impairments.</p>
        <h2>3. Boosting Productivity</h2>
        <p>Busy individuals can convert long articles into podcasts to listen while multitasking, improving productivity. It gives professionals the ability to consume content on the go.</p>
        <h2>4. Empowering Content Creators</h2>
        <p>Bloggers, journalists, and companies can expand their reach by quickly converting articles into podcasts without needing audio production skills, growing their audience and engagement.</p>
        <h2>5. Global Reach for Businesses</h2>
        <p>Businesses can reach more customers by offering content in audio form, increasing engagement. Podcasts allow businesses to stay connected with their audience in flexible, on-demand formats.</p>
    </body>
    </html>
  `,
  pod_type: 'summary_single_host',
}

fetch('https://app.lettercast.ai/v1/pods', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(data),
})
  .then((response) => {
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`)
    }
    return response.json()
  })
  .then((data) => {
    console.log(data)
  })
  .catch((error) => {
    console.error('Error:', error)
  })

Creating a pod from a PDF file

const form = new FormData()
form.append(
  'file',
  new Blob(
    [await fetch('/path/to/document.pdf').then((res) => res.arrayBuffer())],
    { type: 'application/pdf' },
  ),
  'document.pdf',
)
form.append('pod_type', 'full_discussion')

fetch('https://app.lettercast.ai/v1/pods', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${API_KEY}`,
  },
  body: form,
})
  .then((response) => {
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`)
    }
    return response.json()
  })
  .then((data) => {
    console.log(data)
  })
  .catch((error) => {
    console.error('Error:', error)
  })

Creating a pod with video

To create a pod with a video, you can set the create_video option to true. You must also provide a video_image_file or, if not provided, the first page of the PDF will be used as the video image. Note this works for URLs and HTMLs as well.

// JavaScript implementation for creating a pod with video
const form = new FormData();
form.append('file', new Blob([await fetch('/path/to/document.pdf').then((res) => res.arrayBuffer())], { type: 'application/pdf' }), 'document.pdf');
form.append('pod_type', 'full_discussion');
form.append('create_video', 'true');
// Note: When adding host_configs, ensure to serialize to JSON first
form.append('host_configs', JSON.stringify([
    {
        name: 'John',
        voice_config: { voice_name: 'jensen-hd' }
    },
    {
        name: 'Sarah',
        voice_config: { voice_name: 'mira' }
    }
]));

fetch('https://app.lettercast.ai/v1/pods', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${API_KEY}`,
  },
  body: form,
})
  .then((response) => {
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    return response.json();
  })
  .then((data) => {
    console.log(data);
  })
  .catch((error) => {
    console.error('Error:', error);
  });

This will return the details of the newly created pod, including its ID. Note that the pod creation process may take some time to complete.

Checking pod status

After creating a new pod, you'll need to poll the API to check its status. Here's an example of how to do this:

async function checkPodStatus(podId) {
  while (true) {
    try {
      const response = await fetch(
        `https://app.lettercast.ai/v1/pods/${podId}`,
        {
          headers: { Authorization: `Bearer ${API_KEY}` },
        },
      )

      if (!response.ok) {
        throw new Error(`HTTP error! status: ${response.status}`)
      }

      const pod = await response.json()

      if (pod.generation_status === 'done') {
        console.log('Pod is ready!')
        return pod
      } else if (pod.generation_status === 'failed') {
        console.log('Pod creation failed.')
        return null
      } else {
        console.log(
          `Pod is still being created. Status: ${pod.generation_status}`,
        )
        await new Promise((resolve) => setTimeout(resolve, 10000)) // Wait for 10 seconds
      }
    } catch (error) {
      console.error('Error checking pod status:', error.message)
      return null
    }
  }
}

// Usage example:
async function example() {
  try {
    const podId = 'pod_id_returned_from_creation'
    const pod = await checkPodStatus(podId)
    if (pod) {
      console.log('Pod details:', pod)
    } else {
      console.log('Pod not available. Try again later.')
    }
  } catch (error) {
    console.error('An error occurred:', error.message)
  }
}

example()

Understanding the pod structure

When you retrieve a pod, it will have the following structure:

Javascript

{
  id: string,
  title: string,
  source: string,
  content_publication_date: string | null,
  created_at: string | null,
  generation_status: string,
  table_of_contents: array,
  authors: array | null,
  summary: string,
  instructions: string
}

Let's break down these fields:

  • id: Unique identifier for the pod
  • title: Title of the pod
  • source: Source of the pod content
  • content_publication_date: Publication date of the content (ISO format)
  • created_at: Creation date of the pod (ISO format)
  • generation_status: Current status of the pod generation process
  • table_of_contents: Array of objects with timestamp_s (number) and description (string)
  • authors: Array of authors (if available)
  • summary: Summary of the pod content
  • instructions: User input query or instructions for pod creation

Make sure to handle these fields appropriately in your application.

Downloading Pod Audio and Video

Before downloading the audio and video files of a pod, it's important to ensure that the pod generation is complete. We'll use the status checking function from earlier to wait until the pod is ready before attempting to download.

async function downloadPodMedia(podId, mediaType) {
  try {
    const pod = await checkPodStatus(podId)
    if (!pod) {
      console.log(`Cannot download ${mediaType}. Pod is not ready.`)
      return
    }

    const response = await fetch(
      `https://app.lettercast.ai/v1/pods/${podId}/${mediaType}`,
      {
        headers: { Authorization: `Bearer ${API_KEY}` },
      },
    )

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`)
    }

    const blob = await response.blob()
    const url = window.URL.createObjectURL(blob)
    const a = document.createElement('a')
    a.style.display = 'none'
    a.href = url
    a.download = `pod_${mediaType}.${mediaType === 'audio' ? 'mp3' : 'mp4'}`
    document.body.appendChild(a)
    a.click()
    window.URL.revokeObjectURL(url)
    console.log(`${mediaType} downloaded successfully.`)
  } catch (error) {
    console.error(`Error downloading ${mediaType}:`, error.message)
  }
}

// Usage
async function main() {
  await downloadPodMedia('your_pod_id_here', 'audio')
  await downloadPodMedia('your_pod_id_here', 'video')
}

main()

These examples demonstrate how to check the pod status before attempting to download both audio and video files for a specific pod. The download function will only proceed if the pod status is "done". Make sure to replace API_KEY with your actual API key and your_pod_id_here with the ID of the pod you want to download.

Changing the Audio Configuration

You can customize the audio configuration of your pod by specifying different voice_names for each host in the host_configs. The name of the host is optional and can be used to identify different speakers in your podcast.

Example: Changing Audio Configuration

// JavaScript implementation for changing audio configuration
const data = {
  url: 'https://ia.samaltman.com/',
  host_configs: [
    {
      name: 'John',
      voice_config: { voice_name: 'jensen-hd' }
    },
    {
      name: 'Sarah',
      voice_config: { voice_name: 'mira' }
    }
  ],
  has_music: false
};

fetch('https://app.lettercast.ai/v1/pods', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(data),
})
  .then((response) => {
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    return response.json();
  })
  .then((data) => {
    console.log(data);
  })
  .catch((error) => {
    console.error('Error:', error);
  });

In this example, the voice_names correspond to different voices available in the Lettercast API. You can choose from a variety of voices to suit your podcast's style. The name field is optional and can be used to label the hosts for clarity.

The voice_name in voice_config can be one of the following values:

  • "mira"
  • "jensen"

The following voices are only available for Pro users:

  • "mira-hd"
  • "jensen-hd"

The following voices add $0.1/minute to the cost:

  • "taylor"
  • "harry"
  • "ben"
  • "julia"
  • "alan"
  • "olivia"
  • "jake"
  • "mary"
  • "sarah"
  • "matt"

The following voices add $0.2/minute to the cost:

  • "taylor-hd"
  • "harry-hd"
  • "ben-hd"
  • "julia-hd"
  • "alan-hd"
  • "olivia-hd"

So for example, if you have a 5 minute podcast with 2 hosts, one of which is "taylor-hd" and the other is "harry", the cost will be 5 * (0.1 + 0.1 + 0.2) = $2.

What's next?

Great! You're now set up with an API key and have made your first requests to the Lettercast API. Here are a few links that might be handy as you explore further:

Read the docs for the Pods endpoint

Was this page helpful?