@mymagicpencil/sdk

Official TypeScript/JavaScript client for the My Magic Pencil developer API — turn any topic, passage, book, or question paper into animated, narrated whiteboard lessons, synthesize speech, build playlists, embed live plays, and export PDFs. Billed per use against a prepaid credit balance.

npm install @mymagicpencil/sdk

• Works in Node 18+ and modern browsers/bundlers (uses the global fetch).
• Fully typed. ESM.

Quick start

import { MagicPencil } from "@mymagicpencil/sdk";

const mp = new MagicPencil({ apiKey: process.env.MMP_API_KEY! }); // mmp_live_…

// 1) Generate a lesson
const { lessons } = await mp.generateLesson({ topic: "The water cycle" });

// 2) Bundle into a playlist → get an embeddable live-play URL
const { id, playUrl } = await mp.createPlaylist({ title: "Science", lessons });
console.log(playUrl); // https://mymagicpencil.com/embed/<id>  — iframe this

// 3) Export the playlist as a PDF
const pdfBytes = await mp.exportPdf(id);

Get an API key + credits at https://mymagicpencil.com/developers.

Configuration

new MagicPencil({
  apiKey: "mmp_live_…",   // required
  baseUrl: "https://…",   // optional — defaults to the production API
  fetch: customFetch,     // optional — for Node < 18 or custom transport
});

API

Every response includes _meta.charged and _meta.balance so you can track spend. A MagicPencilError with status === 402 means you're out of credits.

generateLesson(input) → GenerateLessonResult

Generate one lesson (scene script + audio). Charged per lesson.

await mp.generateLesson({
  topic: "Photosynthesis",   // or prompt / source
  language: "en",            // BCP-47; narration language
  quality: "std",            // "std" (fast, cheaper) | "high" (best)
});

speech(input) → SpeechResult

Synthesize narration audio. Charged per character.

const { audio } = await mp.speech({ text: "Welcome!", language: "en" }); // base64 MP3

createPlaylist(input) → { id, lessonCount, playUrl }

Save an ordered set of lessons; returns a hosted, embeddable live-play URL.

const { playUrl } = await mp.createPlaylist({ title: "Biology", lessons });

listPlaylists() / getPlaylist(id)

List your playlists, or fetch one's full lessons.

createBook(input) → Job  ·  createPaper(input) → Job

Start an async multi-lesson job; poll with getJob. Charged per lesson.

const job = await mp.createBook({
  title: "Physics 101",
  chapters: [{ title: "Motion", text: "…" }, { title: "Forces", text: "…" }],
  quality: "std",
});

let status = job;
while (status.status !== "done" && status.status !== "error") {
  await new Promise((r) => setTimeout(r, 3000));
  status = await mp.getJob(job.jobId);
}
console.log(status.playUrl); // embed when done

createPaper({ pages, ... }) takes page images ({ base64, mediaType, width, height, page }).

getJob(jobId) → Job

Poll an async job: { status, done, total, cloudId, playUrl }. Set a webhook in the dashboard to be POSTed on completion instead of polling.

exportPdf(notebookId) → Uint8Array

Export a playlist as a printable lesson-script PDF. Charged a small fee.

import { writeFileSync } from "node:fs";
writeFileSync("lesson.pdf", await mp.exportPdf(id));

Embedding the live play

A "live play" is the animated, narrated whiteboard. Embed it with the hosted player — no rendering code needed:

<iframe src="https://mymagicpencil.com/embed/PLAYLIST_ID"
        width="720" height="440" allow="autoplay" style="border:0"></iframe>

The embed is chrome-free (no login, no paywall) for API-created content.

Errors & billing

import { MagicPencilError } from "@mymagicpencil/sdk";

try {
  await mp.generateLesson({ topic: "…" });
} catch (e) {
  if (e instanceof MagicPencilError && e.status === 402) {
    // out of credits — top up at /developers
  }
}

• Pricing is usage-based: ≈ $0.18/lesson (std) or $0.30/lesson (high); speech per character.
• Keys come in two scopes: generate (full) and read (GET only).
• Manage keys, balance, usage, and webhooks at https://mymagicpencil.com/developers.

Full REST reference: docs/DEVELOPER_API.md.

License

MIT © My Magic Pencil