Plaud API Client

A clean, asynchronous Python client for the Plaud.ai API. Allows you to programmatically log in, iterate over your conversations, and download original audio files (like .ogg).

Features

• Asynchronous: Built on top of httpx for fast, non-blocking network operations.
• Robust Parsing: Leverages Python 3.10+ match/case pattern matching for predictable data extraction without "paranoid" fallbacks.
• Pagination: Supports clean iteration over all conversations via generators or explicit page objects.
• Direct S3 Downloads: Extracts short-lived signed URLs from Plaud to stream original audio files directly from AWS S3.

Installation

This project is built using uv.

You can add it directly to your uv project:

uv add path/to/plaud-api

Or install it globally / in your virtual environment:

uv pip install .

Quick Start

import asyncio
from plaud_api import PlaudAPI

async def main():
    api = PlaudAPI()

    # 1. Login
    print("Logging in...")
    await api.login("your.email@example.com", "your_password")

    # 2. Iterate over ALL conversations
    print("Fetching conversations...")
    count = 0
    async for file_obj in api.iter_conversations(chunk_size=60):
        count += 1

        # Download the first 3 audio files
        if count <= 3:
            match file_obj:
                case {"id": file_id}:
                    filename = f"{file_id}.ogg"
                    print(f"Downloading audio to {filename}...")
                    await api.download_audio(file_id, filename)
                case data:
                    print(f"Warning: Could not extract file ID from {data}")

    print(f"Iterated over {count} total conversations.")

    await api.close()

if __name__ == "__main__":
    asyncio.run(main())

Explicit Pagination

If you want fine-grained control over pagination, you can fetch explicitly:

page = await api.get_conversations_page(limit=10, skip=0)
print(f"Total available: {page.total}")
for item in page.items:
    print(item["id"])

if page.has_next:
    next_page = await page.next_page()
    # ...

CLI Usage

The package provides a command-line interface via rich-click. Once installed, you can use the plaud command or run it as a Python module: python -m plaud_api.

Authentication

You have three ways to provide credentials to the CLI, in order of precedence:

1. CLI Arguments: Pass --username and --password explicitly to any command.
2. System Keyring (Recommended): Store them securely once using the auth command:

   plaud auth
   

   You will be prompted to enter your username and securely type your password (from stdin). (You can bypass this with --no-keyring if desired).
3. Environment Variables:

   export PLAUD_USERNAME="your.email@example.com"
   export PLAUD_PASSWORD="your_password"
   

List Conversations

List the last N conversations (defaults to 10) in a nicely formatted table:

plaud list -n 5

Download Audio

Download a specific conversation's .ogg audio file by providing its ID:

plaud download <file_id> output.ogg

Requirements

• Python >= 3.10
• httpx >= 0.28.1

Disclaimer

Disclaimer: This is not an official Plaud.ai client. It is a community-built API client and is not affiliated with, endorsed by, or supported by Plaud.ai. Use at your own risk.

License

This project is licensed under the WTFPL License.