# SlideMaster AI — Complete Documentation

> AI teaching design agent and REST API. Design complete course experiences through conversation, or integrate directly via API to generate narration scripts, TTS audio, and export video.

## Base URL

```
https://api.slidemaster.tw/api/v1/public
```

## Agent Discovery

- MCP endpoint: https://mcp.slidemaster.tw/mcp
- MCP manifest: https://slidemaster.tw/mcp/manifest.json
- MCP status: https://slidemaster.tw/mcp/status.json
- Public tool manifest: https://slidemaster.tw/mcp/tools.json
- Agent recipes: https://slidemaster.tw/mcp/recipes.json
- OpenAPI spec: https://api.slidemaster.tw/api/v1/public/openapi.json
- Claude/Cursor connection guide: https://slidemaster.tw/guides/claude-cursor-mcp-connection-guide

Public discovery files describe callable capabilities and safe workflow guidance only. They do not expose internal implementation details, deployment details, secrets, or private prompts.

## Agent Intent Modes

SlideMaster MCP supports three explicit task modes:

1. **structured_output** — use when the user asks for course outlines, lecture notes, learning activities, questions, narration scripts, slide structure, JSON-like planning output, or editable PPTX/PDF exports.
2. **visual_rendering** — use when the user asks for rendered slide images, visual redesign, visual style matching, AI-generated slides, narrated video, TTS, or MP4 export.
3. **intelligent_layout** — use when the user asks for template-based editable PPTX, brand-safe layout, safe areas, or structured content placed into a layout system.

Guardrail: structure-only requests must not trigger `render_slides`, `generate_tts`, `topic_to_video`, or `generate_video` unless the user explicitly requests media generation or approves estimated credit usage.

## Authentication

All requests require an API key via the `X-API-Key` header.

```
X-API-Key: sm_live_YOUR_KEY
```

Alternative: `Authorization: Bearer sm_live_YOUR_KEY`

Keys start with `sm_live_` followed by 32 hex characters.
Get your API key at: https://slidemaster.tw/settings/api-keys

## Rate Limits

- 60 requests per minute
- 1,000 requests per day
- Exceeding limits returns HTTP 429 with `retry_after`

Response headers:
```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1670000000
```

---

## Typical Workflow

Structure-only workflow:

1. **Generate outline** — `POST /outlines/generate` with topic, audience, language, and slide count
2. **Return structured content** — slide titles, key points, teaching objective, and narration notes
3. **Optionally export** — use PDF/PPTX export only if the user asks for a file output

Structure-only agent example:

```text
請建立一份 8 張投影片的「資訊安全意識訓練」課程大綱，目標對象是一般員工。
請只輸出結構化內容：每張投影片標題、教學目標、重點、建議講稿提示。
不要渲染投影片，不要生成 TTS，也不要生成影片。
```

Recommended tool chain: `generate_outline`.

The standard workflow to create a narrated video from a topic:

1. **Generate outline** — `POST /outlines/generate` with your topic
2. **Create project** — `POST /projects` with a title
3. **Render slides** — `POST /slides/render` with slide data from the outline
4. **Generate scripts** — `POST /scripts/batch-generate` for all slides
5. **Generate TTS** — `POST /tts/generate` to create audio narration
6. **Generate video** — `POST /video/generate` to compose final video
7. **Poll status** — `GET /projects/{id}/status` until completed
8. **Export** — `GET /projects/{id}/export` for download URLs

Or use `POST /pipelines/topic-to-video` to do all of the above in one call.

Agent example task:

```text
請用 8 張投影片建立一門「資訊安全意識訓練」課程，目標對象是一般員工。
請先估算 credits，再生成投影片、講稿、TTS 配音與 MP4 影片。
完成後請回傳專案狀態與可下載連結。
```

Recommended tool chain: `estimate_cost -> topic_to_video -> check_status -> export_project`.

---

## Endpoints — Content Creation

### POST /outlines/generate

Generate a structured slide outline from a topic using AI.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| topic | string | yes | Topic to generate outline for |
| slides_count | int | no | Number of slides, 3-30, default 8 |
| language | string | no | "zh-TW", "en", or "ja" |
| style | string | no | Outline style, default "professional" |

**Response:**
```json
{
  "topic": "Quantum Computing",
  "slides": [
    {
      "title": "Introduction to Quantum Computing",
      "description": "Cover slide",
      "key_points": ["What is quantum computing"]
    }
  ]
}
```

**Example:**
```bash
curl -X POST "https://api.slidemaster.tw/api/v1/public/outlines/generate" \
  -H "X-API-Key: sm_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"topic": "Quantum Computing", "slides_count": 8}'
```

---

### POST /projects

Create a new project.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| title | string | yes | Project title |
| description | string | no | Project description |
| type | string | no | "traditional" (default) or "flow" |

**Response:**
```json
{
  "id": "abc123",
  "title": "My Presentation",
  "description": "",
  "status": "pending",
  "type": "traditional",
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z"
}
```

**Example:**
```bash
curl -X POST "https://api.slidemaster.tw/api/v1/public/projects" \
  -H "X-API-Key: sm_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "My Presentation"}'
```

---

### POST /upload/init

Create a project and get a signed upload URL for PDF/PPTX file.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| title | string | yes | Project title |
| filename | string | yes | File name (.pdf, .pptx, or .ppt) |

**Response:**
```json
{
  "project_id": "abc123",
  "upload_url": "https://storage...",
  "blob_path": "projects/abc123/ppt/slides.pdf",
  "expires_in_minutes": 60
}
```

**Example:**
```bash
# Step 1: Get upload URL
curl -X POST "https://api.slidemaster.tw/api/v1/public/upload/init" \
  -H "X-API-Key: sm_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "My Slides", "filename": "slides.pdf"}'

# Step 2: Upload file to the returned URL
curl -X PUT "UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary @slides.pdf
```

---

### POST /upload/complete

Confirm file upload and trigger parsing.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| project_id | string | yes | Project ID from upload/init |

**Example:**
```bash
curl -X POST "https://api.slidemaster.tw/api/v1/public/upload/complete" \
  -H "X-API-Key: sm_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project_id": "abc123"}'
```

---

### POST /slides/render

Generate slide images using Gemini AI.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| project_id | string | yes | Project ID |
| slides | array | yes | Array of {title, description} objects |
| image_size | string | no | "1K", "2K", or "4K" |

**Example:**
```bash
curl -X POST "https://api.slidemaster.tw/api/v1/public/slides/render" \
  -H "X-API-Key: sm_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project_id": "abc123", "slides": [{"title": "Intro", "description": "Modern title slide"}], "image_size": "2K"}'
```

---

## Endpoints — Content Processing

### POST /scripts/generate

Generate narration script for a single slide.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| slide_id | string | yes | Slide ID |
| prompt_style | string | no | "professional", "casual", "educational", or "storytelling" |
| regenerate | bool | no | Force regenerate existing script |

**Example:**
```bash
curl -X POST "https://api.slidemaster.tw/api/v1/public/scripts/generate" \
  -H "X-API-Key: sm_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"slide_id": "slide_001"}'
```

---

### POST /scripts/batch-generate

Generate narration scripts for all slides in a project.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| project_id | string | yes | Project ID |
| prompt_style | string | no | "professional", "casual", "educational", or "storytelling" |
| regenerate | bool | no | Force regenerate existing scripts |
| slide_ids | array | no | Specific slide IDs to generate (omit for all) |

**Example:**
```bash
curl -X POST "https://api.slidemaster.tw/api/v1/public/scripts/batch-generate" \
  -H "X-API-Key: sm_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project_id": "abc123"}'
```

---

### POST /tts/generate

Generate text-to-speech audio for slide scripts.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| project_id | string | no | Project ID (generates for all slides) |
| slide_id | string | no | Single slide ID |
| tts_provider | string | no | "gemini", "cosyvoice", or "azure" |
| voice_name | string | no | Voice name (see GET /voices for options) |
| speaking_rate | float | no | Speech speed, default 1.0 |

**Example:**
```bash
curl -X POST "https://api.slidemaster.tw/api/v1/public/tts/generate" \
  -H "X-API-Key: sm_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project_id": "abc123", "tts_provider": "gemini", "voice_name": "zephyr"}'
```

---

### POST /video/generate

Compose final video from slides and audio.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| project_id | string | yes | Project ID |
| resolution | array | no | [width, height], default [1920, 1080] |
| fps | int | no | Frames per second, default 30 |
| force | bool | no | Force regenerate video |

**Example:**
```bash
curl -X POST "https://api.slidemaster.tw/api/v1/public/video/generate" \
  -H "X-API-Key: sm_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project_id": "abc123"}'
```

---

## Endpoints — Management

### GET /projects

List all projects for the API key owner.

**Query Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| limit | int | no | Max results, default 20 |

**Response:**
```json
[
  {
    "id": "abc123",
    "title": "My Presentation",
    "description": "",
    "status": "completed",
    "type": "traditional",
    "created_at": "2026-01-01T00:00:00Z"
  }
]
```

**Example:**
```bash
curl "https://api.slidemaster.tw/api/v1/public/projects?limit=20" \
  -H "X-API-Key: sm_live_YOUR_KEY"
```

---

### GET /projects/{id}

Get details of a specific project.

**Path Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| id | string | yes | Project ID |

**Response:**
```json
{
  "id": "abc123",
  "title": "My Presentation",
  "description": "",
  "status": "completed",
  "type": "traditional",
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z"
}
```

**Example:**
```bash
curl "https://api.slidemaster.tw/api/v1/public/projects/abc123" \
  -H "X-API-Key: sm_live_YOUR_KEY"
```

---

### PATCH /projects/{id}

Update project settings.

**Path Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| id | string | yes | Project ID |

**Body Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| title | string | no | New project title |
| tts_provider | string | no | TTS provider |
| tts_voice | string | no | Voice name |

**Example:**
```bash
curl -X PATCH "https://api.slidemaster.tw/api/v1/public/projects/abc123" \
  -H "X-API-Key: sm_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tts_provider": "gemini", "tts_voice": "zephyr"}'
```

---

### DELETE /projects/{id}

Delete a project and all its slides, scripts, and assets.

**Path Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| id | string | yes | Project ID |

**Example:**
```bash
curl -X DELETE "https://api.slidemaster.tw/api/v1/public/projects/abc123" \
  -H "X-API-Key: sm_live_YOUR_KEY"
```

---

### GET /projects/{id}/slides

List all slides in a project with image/audio URLs.

**Path Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| id | string | yes | Project ID |

**Response:**
```json
{
  "project_id": "abc123",
  "total": 8,
  "slides": [
    {
      "id": "s1",
      "slide_number": 1,
      "title": "Introduction",
      "image_url": "https://...",
      "script": "Hello everyone...",
      "audio_url": "https://...",
      "duration": 12.5,
      "status": "completed"
    }
  ]
}
```

**Example:**
```bash
curl "https://api.slidemaster.tw/api/v1/public/projects/abc123/slides" \
  -H "X-API-Key: sm_live_YOUR_KEY"
```

---

### PATCH /slides/{id}

Update a slide's title or narration script.

**Path Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| id | string | yes | Slide ID |

**Body Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| title | string | no | New slide title |
| script | string | no | New narration script |

**Example:**
```bash
curl -X PATCH "https://api.slidemaster.tw/api/v1/public/slides/slide_001" \
  -H "X-API-Key: sm_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"script": "Updated narration..."}'
```

---

### DELETE /slides/{id}

Delete a single slide and its associated scripts.

**Path Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| id | string | yes | Slide ID |

**Example:**
```bash
curl -X DELETE "https://api.slidemaster.tw/api/v1/public/slides/slide_001" \
  -H "X-API-Key: sm_live_YOUR_KEY"
```

---

## Endpoints — Query & Export

### GET /projects/{id}/status

Check processing status and progress.

**Path Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| id | string | yes | Project ID |

**Response:**
```json
{
  "project_id": "abc123",
  "status": "completed",
  "video_url": "https://...",
  "slides_total": 8,
  "slides_completed": 8
}
```

**Status values:** pending, processing, parsed, completed, video_completed, failed

**Example:**
```bash
curl "https://api.slidemaster.tw/api/v1/public/projects/abc123/status" \
  -H "X-API-Key: sm_live_YOUR_KEY"
```

---

### GET /projects/{id}/export

Get download URLs for video and all project assets.

**Path Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| id | string | yes | Project ID |

**Response:**
```json
{
  "project_id": "abc123",
  "title": "My Presentation",
  "video_url": "https://...",
  "slides": [
    {
      "slide_number": 1,
      "title": "Introduction",
      "image_url": "https://...",
      "audio_url": "https://..."
    }
  ]
}
```

**Example:**
```bash
curl "https://api.slidemaster.tw/api/v1/public/projects/abc123/export" \
  -H "X-API-Key: sm_live_YOUR_KEY"
```

---

### GET /voices

List all available TTS voices.

**Response:**
```json
{
  "providers": ["gemini", "cosyvoice", "azure"],
  "voices": [
    {
      "name": "zephyr",
      "provider": "gemini",
      "gender": "FEMALE",
      "language": "multilingual",
      "description": "Bright, higher pitch"
    }
  ]
}
```

**Example:**
```bash
curl "https://api.slidemaster.tw/api/v1/public/voices" \
  -H "X-API-Key: sm_live_YOUR_KEY"
```

---

## Endpoints — Automation

### POST /pipelines/topic-to-video

Fully automated pipeline: topic → outline → slides → scripts → TTS → video.

This is the simplest way to create a complete narrated video. One API call triggers the entire pipeline. Poll `GET /projects/{id}/status` to track progress.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| topic | string | yes | Video topic |
| slides_count | int | no | Number of slides, 3-20, default 8 |
| language | string | no | "zh-TW" or "en" |
| tts_provider | string | no | TTS provider |
| tts_voice | string | no | Voice name |
| image_size | string | no | "1K", "2K", or "4K" |

**Response:**
```json
{
  "project_id": "abc123",
  "status": "accepted",
  "message": "Pipeline started: Quantum Computing (8 slides)"
}
```

**Example:**
```bash
curl -X POST "https://api.slidemaster.tw/api/v1/public/pipelines/topic-to-video" \
  -H "X-API-Key: sm_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "Quantum Computing",
    "slides_count": 8,
    "tts_provider": "gemini",
    "tts_voice": "zephyr",
    "image_size": "2K"
  }'
```

---

## Error Codes

All errors return JSON with a `detail` field.

```json
{"detail": "Project not found"}
```

| Code | Description |
|------|-------------|
| 400 | Bad Request — Invalid parameters |
| 401 | Unauthorized — Invalid or missing API key |
| 403 | Forbidden — No access to this resource, or project limit reached |
| 404 | Not Found — Resource does not exist |
| 429 | Too Many Requests — Rate limit exceeded, check retry_after |
| 500 | Internal Server Error — Please retry |
| 503 | Service Unavailable — AI service not configured |

---

## Code Examples

### Python

```python
import requests, time

API_KEY = "sm_live_YOUR_KEY"
BASE = "https://api.slidemaster.tw/api/v1/public"
H = {"X-API-Key": API_KEY, "Content-Type": "application/json"}

# One call → video
r = requests.post(f"{BASE}/pipelines/topic-to-video", headers=H, json={
    "topic": "Quantum Computing",
    "slides_count": 8,
    "tts_voice": "zephyr",
})
pid = r.json()["project_id"]

# Poll until done
while True:
    s = requests.get(f"{BASE}/projects/{pid}/status", headers=H).json()
    print(f'{s["status"]} ({s["slides_completed"]}/{s["slides_total"]})')
    if s["status"] in ("completed", "video_completed", "failed"):
        break
    time.sleep(10)

# Download
exp = requests.get(f"{BASE}/projects/{pid}/export", headers=H).json()
print(f"Video: {exp['video_url']}")
```

### JavaScript

```javascript
const KEY = "sm_live_YOUR_KEY";
const BASE = "https://api.slidemaster.tw/api/v1/public";
const H = { "X-API-Key": KEY, "Content-Type": "application/json" };

// One call → video
const { project_id } = await fetch(`${BASE}/pipelines/topic-to-video`, {
  method: "POST", headers: H,
  body: JSON.stringify({ topic: "Quantum Computing", slides_count: 8, tts_voice: "zephyr" }),
}).then(r => r.json());

// Poll until done
while (true) {
  const s = await fetch(`${BASE}/projects/${project_id}/status`, { headers: H }).then(r => r.json());
  console.log(`${s.status} (${s.slides_completed}/${s.slides_total})`);
  if (["completed", "video_completed", "failed"].includes(s.status)) break;
  await new Promise(r => setTimeout(r, 10000));
}

// Download
const exp = await fetch(`${BASE}/projects/${project_id}/export`, { headers: H }).then(r => r.json());
console.log("Video:", exp.video_url);
```

---

## Additional Resources

- [API Documentation](https://slidemaster.tw/api-docs): Interactive web documentation
- [OpenAPI Spec](https://api.slidemaster.tw/api/v1/public/openapi.json): Machine-readable schema
- [API Playground](https://slidemaster.tw/api-playground): Test endpoints interactively
- [Guides](https://slidemaster.tw/guides): Step-by-step tutorials
- [FAQ](https://slidemaster.tw/faq): 20 frequently asked questions — product overview, voice cloning, pricing, MCP integration, file formats, API access, EverCam export, commercial usage