slidespeak

What this skill does

# SlideSpeak Presentation Skill

This skill enables you to create and edit PowerPoint presentations using the SlideSpeak API.

## IMPORTANT: Timing Behavior

**Presentation generation takes 30-60 seconds.**

### Option 1: Wait for completion (default)
Run the command and wait. The script polls internally until complete:
```bash
node scripts/slidespeak.mjs generate --text "Topic"
```
- Blocks until the task finishes (typically 30-60 seconds)
- Returns the complete result with download URL

### Option 2: Return immediately with `--no-wait`
If you cannot wait for the command to complete, use `--no-wait`:
```bash
node scripts/slidespeak.mjs generate --text "Topic" --no-wait
```
Returns immediately with:
```json
{
  "success": true,
  "data": {
    "task_id": "abc123...",
    "message": "Task started. Check status with: node scripts/slidespeak.mjs status abc123..."
  }
}
```

Then poll the status until complete:
```bash
node scripts/slidespeak.mjs status <task_id>
```
When `task_status` is `SUCCESS`, use the `request_id` to download.

### Timeout behavior
If the script times out while waiting, it returns the task_id so you can continue polling:
```json
{
  "success": true,
  "data": {
    "complete": false,
    "task_id": "abc123...",
    "task_status": "STARTED",
    "message": "Task still processing. Check status with: node scripts/slidespeak.mjs status abc123..."
  }
}
```

## Setup

The `SLIDESPEAK_API_KEY` environment variable must be set. Get your API key from https://app.slidespeak.co/settings/developer

## Quick Reference

All commands use the helper script at `scripts/slidespeak.mjs`. The script handles API authentication and waits for async tasks to complete automatically (no manual polling needed).

### Generate a Presentation from Text

```bash
node scripts/slidespeak.mjs generate --text "Your topic or content" --length 6
```

Options:
- `--text` (required): Topic or content for the presentation
- `--length`: Number of slides (default: 10)
- `--template`: Template name or ID (default: "default")
- `--language`: Output language (default: "ORIGINAL")
- `--tone`: casual, professional, funny, educational, sales_pitch
- `--verbosity`: concise, standard, text-heavy
- `--no-images`: Disable stock image fetching
- `--no-cover`: Exclude cover slide
- `--no-toc`: Exclude table of contents

### Generate from an Uploaded Document

First upload the document, then generate:

```bash
# Upload a document (PDF, DOCX, PPTX, etc.)
node scripts/slidespeak.mjs upload /path/to/document.pdf

# Use the returned document_uuid to generate
node scripts/slidespeak.mjs generate --document <document_uuid> --length 10
```

Supported formats: `.pdf`, `.docx`, `.doc`, `.pptx`, `.ppt`, `.xlsx`, `.txt`, `.md`

### List Available Templates

```bash
# Default templates
node scripts/slidespeak.mjs templates

# Branded templates (if configured)
node scripts/slidespeak.mjs templates --branded
```

### Download a Presentation

After generation completes, use the `request_id` to download:

```bash
node scripts/slidespeak.mjs download <request_id>
```

Returns a JSON object with a short-lived download URL.

### Edit an Existing Presentation

Edit slides in an existing presentation:

```bash
# Insert a new slide at position 2
node scripts/slidespeak.mjs edit-slide \
  --presentation-id <id> \
  --type INSERT \
  --position 2 \
  --prompt "Content about market analysis"

# Regenerate slide at position 3
node scripts/slidespeak.mjs edit-slide \
  --presentation-id <id> \
  --type REGENERATE \
  --position 3 \
  --prompt "Updated content for this slide"

# Remove slide at position 4
node scripts/slidespeak.mjs edit-slide \
  --presentation-id <id> \
  --type REMOVE \
  --position 4
```

Edit types:
- `INSERT`: Add a new slide at the position
- `REGENERATE`: Replace existing slide content
- `REMOVE`: Delete the slide (no prompt needed)

### Check Task Status

For debugging or manual polling:

```bash
node scripts/slidespeak.mjs status <task_id>
```

### Get Account Info

```bash
node scripts/slidespeak.mjs me
```

## Slide-by-Slide Generation

For precise control over each slide, use the slide-by-slide endpoint. See `references/API.md` for the full schema.

```bash
node scripts/slidespeak.mjs generate-slides --config slides.json
```

Where `slides.json` contains:
```json
{
  "slides": [
    {"title": "Introduction", "layout": "title", "content": "Welcome message"},
    {"title": "Key Points", "layout": "bullets", "item_amount": 4, "content": "Main discussion points"}
  ],
  "template": "default"
}
```

## Webhooks

Subscribe to receive notifications when tasks complete:

```bash
# Subscribe
node scripts/slidespeak.mjs webhook-subscribe --url "https://your-webhook.com/endpoint"

# Unsubscribe
node scripts/slidespeak.mjs webhook-unsubscribe --url "https://your-webhook.com/endpoint"
```

## Error Handling

The script outputs JSON with either:
- Success: `{"success": true, "data": {...}}`
- Error: `{"success": false, "error": "message"}`

## Common Workflows

### Create a presentation about a topic
```bash
node scripts/slidespeak.mjs generate --text "Introduction to Machine Learning" --length 8 --tone educational
```

### Create a presentation from a PDF report
```bash
# Upload the PDF
RESULT=$(node scripts/slidespeak.mjs upload report.pdf)
DOC_ID=$(echo $RESULT | jq -r '.data.document_uuid')

# Generate presentation
node scripts/slidespeak.mjs generate --document "$DOC_ID" --length 12
```

### Edit a presentation to add a new slide
```bash
node scripts/slidespeak.mjs edit-slide \
  --presentation-id "abc123" \
  --type INSERT \
  --position 5 \
  --prompt "Add a slide about quarterly revenue growth with charts"
```

## Additional Resources

For detailed API documentation including all parameters, layout types, and constraints, read `references/API.md`.