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.

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": "completed",
    "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": "completed",
  "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

Generate a pod from URL

This endpoint allows you to generate a new pod from a URL.

Parameters

Name
url
Type
string
Description
The URL of the content to generate a pod from.
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.
Name
create_video
Type
boolean
Description
Optional. Whether to create a video for the pod. Default is false.
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.

Request

POST

/v1/pods

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

  const data = {
    url: 'https://example.com/article',
    pod_type: 'summary_discussion',
    user_instructions: 'Focus on the main points',
    create_video: false
  };

  try {
    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),
    });
    if (!response.ok) throw new Error('API request failed');
    const result = await response.json();
    res.status(200).json(result);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
}

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

POST/v1/pods

Generate a pod from file

This endpoint allows you to generate a new pod from a PDF file.

Parameters

Name
file
Type
File
Description
The PDF file to generate a pod from.
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.
Name
create_video
Type
boolean
Description
Optional. Whether to create a video for the pod. Default is false.
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.

Request

POST

/v1/pods

import formidable from 'formidable';
import fs from 'fs';

export const config = {
  api: {
    bodyParser: false,
  },
};

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

  const form = new formidable.IncomingForm();
  form.parse(req, async (err, fields, files) => {
    if (err) {
      res.status(500).json({ error: 'Error parsing form data' });
      return;
    }

    const formData = new FormData();
    formData.append('file', fs.createReadStream(files.file.path));
    formData.append('pod_type', fields.pod_type);
    formData.append('user_instructions', fields.user_instructions);
    formData.append('create_video', fields.create_video);

    try {
      const response = await fetch('https://app.lettercast.ai/v1/pods', {
        method: 'POST',
        headers: { Authorization: `Bearer ${API_KEY}` },
        body: formData,
      });
      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 });
    }
  });
}

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

Notes

When uploading a file, the request must use multipart/form-data encoding.
When sending JSON data (not uploading a file), use Content-Type: application/json header.
The user_instructions parameter is optional and can be used to provide additional context or instructions for the pod generation.
The pod generation process may take some time. You'll need to poll the API to check the pod's status after creation.

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 "completed" or "failed".

Key points

Poll the API every 10 seconds
Check the generation_status field
Stop polling when status is "completed" 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 === 'completed' || 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()