Pods

Pods are the core building blocks in Lettercast. On this page, we'll explore the different pod endpoints you can use to manage pods programmatically. We'll look at how to list, retrieve, and create pods.

The pod model

The pod model contains all the information about the pods you create and manage in Lettercast.

Properties

Name
id
Type
string
Description
Unique identifier for the pod.
Name
title
Type
string
Description
The title of the pod.
Name
source
Type
string
Description
Source of the content used to generate the pod.
Name
content_publication_date
Type
string
Description
The publication date of the original content.
Name
created_at
Type
string
Description
The date and time when the pod was created.
Name
generation_status
Type
string
Description
The current status of the pod generation process.
Name
table_of_contents
Type
array
Description
An array of objects containing timestamps and descriptions of the pod's contents.
Name
authors
Type
array
Description
An array of strings representing the authors of the original content.
Name
summary
Type
string
Description
A summary of the pod's content.
Name
instructions
Type
string
Description
The user instructions provided during pod creation.
Name
host_configs
Type
array
Description
Optional. An array of host configurations for the pod. Each item should contain a name (string, can be null) and a voice_config object with voice_name (string) property.
Name
has_music
Type
boolean
Description
Optional. Whether to include intro and outro music in the pod. Default is true.
Name
video_image_file
Type
File
Description
Optional. The image file to be used as a thumbnail for the video. This should be uploaded when create_video is true.

GET/v1/pods

List all pods

This endpoint allows you to retrieve a list of all your pods.

Request

GET

/v1/pods

export default async function handler(req, res) {
  const API_KEY = process.env.LETTERCAST_API_KEY;

  try {
    const response = await fetch('https://app.lettercast.ai/v1/pods', {
      headers: { Authorization: `Bearer ${API_KEY}` },
    });
    if (!response.ok) throw new Error('API request failed');
    const data = await response.json();
    res.status(200).json(data);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
}

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "title": "My First Pod",
    "source": "https://example.com/article",
    "content_publication_date": "2023-01-01T00:00:00",
    "created_at": "2023-01-01T12:00:00Z",
    "generation_status": "done",
    "table_of_contents": [
      {
        "timestamp_s": 0,
        "description": "Introduction"
      },
      {
        "timestamp_s": 60,
        "description": "Main Points"
      }
    ],
    "authors": ["John Doe", "Jane Smith"],
    "summary": "This pod covers...",
    "instructions": "Summarize the main points"
  }
]

GET/v1/pods/:id

Retrieve a pod

This endpoint allows you to retrieve a specific pod by providing its ID.

Request

GET

/v1/pods/123e4567-e89b-12d3-a456-426614174000

export default async function handler(req, res) {
  const API_KEY = process.env.LETTERCAST_API_KEY;
  const { id } = req.query;

  try {
    const response = await fetch(`https://app.lettercast.ai/v1/pods/${id}`, {
      headers: { Authorization: `Bearer ${API_KEY}` },
    });
    if (!response.ok) throw new Error('API request failed');
    const data = await response.json();
    res.status(200).json(data);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "title": "My First Pod",
  "source": "https://example.com/article",
  "content_publication_date": "2023-01-01T00:00:00",
  "created_at": "2023-01-01T12:00:00Z",
  "generation_status": "done",
  "table_of_contents": [
    {
      "timestamp_s": 0,
      "description": "Introduction"
    },
    {
      "timestamp_s": 60,
      "description": "Main Points"
    }
  ],
  "authors": ["John Doe", "Jane Smith"],
  "summary": "This pod covers...",
  "instructions": "Summarize the main points"
}

POST/v1/pods

Create a pod

This endpoint allows you to generate a new pod from different types of content sources: URL, PDF, or HTML content.

Common Parameters

Name
pod_type
Type
string
Description
The type of pod to generate. Options: "summary_single_host", "summary_discussion", "full_single_host", "full_discussion".
Name
user_instructions
Type
string
Description
Optional. User instructions to guide the pod generation. Right now this only supports questions about the content.
Name
intro_plug_text
Type
string
Description
Optional. Text to be used as an introduction plug for the pod.
Name
outro_plug_text
Type
string
Description
Optional. Text to be used as an outro plug for the pod.
Name
host_configs
Type
array
Description
Optional. An array of host configurations for the pod. Each item should contain a name (string, can be null) and a voice_config object with voice_name (string) property.
Name
has_music
Type
boolean
Description
Optional. Whether to include background music in the pod. Default is true.
Name
create_video
Type
boolean
Description
Optional. Whether to create a video for the pod. Default is false. This only applies to PDF inputs.
Name
video_image_file
Type
File
Description
Optional. The image file to be used as a thumbnail for the video. This should be uploaded when create_video is true.

Source-Specific Parameters

Name
url
Type
string
Description
Required for URL source. The URL of the content to generate a pod from.
Name
file
Type
File
Description
Required for PDF source. The PDF file to generate a pod from.
Name
html_content
Type
string
Description
Required for HTML source. The HTML content to generate a pod from.

Request

POST

/v1/pods

const data = {
  url: 'https://example.com/article',
  pod_type: 'summary_discussion',
  host_configs: [
    {
      name: "Alice",
      voice_config: { voice_name: "mira" }
    },
    {
      name: null,
      voice_config: { voice_name: "jensen" }
    }
  ],
  has_music: true
};

const response = await fetch('https://app.lettercast.ai/v1/pods', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data),
});

{
  "pod_id": "123e4567-e89b-12d3-a456-426614174000"
}

Notes

When uploading a file or HTML content, the request must use multipart/form-data encoding.
When sending URL data, use Content-Type: application/json header.
The pod generation process may take some time. You'll need to poll the API to check the pod's status after creation.
For single-host pods, provide one item in the host_configs array.
For two-host pods, provide two items in the host_configs array.
If a host's name is set to null, they won't be referred to by name in the podcast.

GET/v1/pods/:id/audio

Get pod audio

This endpoint allows you to retrieve the audio file for a specific pod.

Request

GET

/v1/pods/123e4567-e89b-12d3-a456-426614174000/audio

Curl -X GET https://app.lettercast.ai/v1/pods/123e4567-e89b-12d3-a456-426614174000/audio \
  -H "Authorization: Bearer {API_KEY}"

HTTP/1.1 302 Found
Location: https://storage.lettercast.ai/path/to/audio/file.mp3

GET/v1/pods/:id/video

Get pod video

This endpoint allows you to retrieve the video file for a specific pod, if available.

Request

GET

/v1/pods/123e4567-e89b-12d3-a456-426614174000/video

Curl -X GET https://app.lettercast.ai/v1/pods/123e4567-e89b-12d3-a456-426614174000/video \
  -H "Authorization: Bearer {API_KEY}"

HTTP/1.1 302 Found
Location: https://storage.lettercast.ai/path/to/video/file.mp4

GET/v1/pods/:id

Polling for pod status

After creating a new pod, you'll need to poll the API to check its status. This process involves repeatedly calling the "Retrieve a pod" endpoint until the pod's status is either "done" or "failed".

Key points

Poll the API every 10 seconds
Check the generation_status field
Stop polling when status is "done" or "failed"

Request

GET

/v1/pods/123e4567-e89b-12d3-a456-426614174000

const API_KEY = 'API_KEY'
const POD_ID = 'pod_id_returned_from_creation'

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

      if (!response.ok) throw new Error('API request failed')
      const data = await response.json()
      const status = data.generation_status

      if (status === 'done' || status === 'failed') {
        console.log(`Pod status: ${status}`)
        break
      } else {
        console.log(`Pod is still being created. Status: ${status}`)
        await new Promise((resolve) => setTimeout(resolve, 10000))
      }
    } catch (error) {
      console.error('Error checking pod status:', error.message)
      break
    }
  }
}

checkPodStatus()

Notes on host_configs

For single-host pods, provide one item in the host_configs array.
For two-host pods, provide two items in the host_configs array.
The first item in host_configs corresponds to the main host, the second item (if present) corresponds to the co-host.
If a host's name is set to null, the corresponding host or co-host will not be referred to by name in the podcast.

Notes on has_music

When set to true, intro and outro music will be included in the pod.
When set to false, the pod will be generated without intro and outro music.
If not specified, the default value is true.