@presentations-ai/api-client

Direct REST client for the Presentations.AI API. Call typed methods, get presentations back. No AI agent in the loop, no LLM tokens, no tool routing — just HTTP.

When to use this

Use this when your code already knows what to create — topic, slide count, export format are all decided by your application logic, not by a user typing in plain English.

Typical use cases:

• A backend service generating presentations from form input or a job queue
• A scheduled task converting reports to slide decks
• A workflow automation calling the API as part of a larger pipeline
• A custom UI where the user picks options through buttons and dropdowns

If you want users to chat in natural language and get a presentation back, install @presentations-ai/cloudy-runtime instead — it wraps Claude on top of this API.

Installation

npm install @presentations-ai/api-client

You'll need a Presentations.AI API key.

Quick start

import { PresentationsAIClient } from '@presentations-ai/api-client';

const client = new PresentationsAIClient({
  apiKey: process.env.PRESENTATIONS_AI_API_KEY!,
});

const result = await client.createFromTopic({
  topic: 'Series B Pitch: AI-Powered Design Platform',
  exportType: 'pptx',
  slideCount: 12,
});

if ('docurl' in result) {
  console.log(result.docurl);   // https://console.presentations.ai/view/...
} else if ('url' in result) {
  console.log(result.url);      // CDN URL for ppt/pdf/image exports
} else {
  console.log(result.job_id);   // Async — poll for the final result
}

That's the basic shape: pass typed input, get a typed result. The result is a discriminated union — different export types return different fields.

Creating presentations

// From a topic — Claude writes the deck for you
await client.createFromTopic({
  topic: 'Q4 Growth Strategy for Enterprise Sales',
  exportType: 'pptx',
  slideCount: 15,
  targetAudience: 'leadership team',
  tone: 'professional',
});

// From a file (PDF, DOCX, XLSX, PPTX) — converts the file to slides
import { readFileSync } from 'node:fs';
await client.createFromFile({
  file: readFileSync('annual-report-2024.pdf'),
  fileName: 'annual-report-2024.pdf',
  exportType: 'pptx',
  instruction: 'summarize',  // or 'enhance' / 'preserve' / 'instruction'
});

// From raw text — turn meeting notes, articles, blog posts into a deck
await client.createFromRawContent({
  content: 'Our platform processed 2M+ presentations this quarter. Revenue grew 140% YoY...',
  exportType: 'pptx',
  instruction: 'enhance',
  slideCount: 10,
  targetAudience: 'investors',
});

// From pre-structured slides — you provide title + section text
await client.createFromContent({
  name: 'Product Launch Plan',
  slides: [
    { title: 'Market Opportunity', section: '$4.2B TAM with 23% CAGR through 2028' },
    { title: 'Go-to-Market', section: 'Three-phase rollout starting with enterprise' },
    { title: 'Competitive Advantage', section: 'AI-native design engine, 10x faster' },
  ],
});

// Single slide (image output)
await client.createSingleSlide({
  topic: 'Monthly Revenue Dashboard',
});

Editing existing presentations

// Update specific slides by index
await client.updateSlides({
  docId: 12345,
  slides: [
    { action: 'update', slideContent: 'Revised Q4 outlook', index: 0 },
    { action: 'add', slideContent: 'New competitive analysis', index: 5 },
    { action: 'delete', slideContent: '', index: 8 },
  ],
});

// Regenerate the whole deck (optionally with a new source file)
await client.refreshPresentation({
  docid: '12345',
  // file: readFileSync('updated-report.pdf'),  // optional
  // fileName: 'updated-report.pdf',
});

Use updateSlides for surgical edits, refreshPresentation to redo the whole deck.

Async jobs

Long-running requests return a job_id instead of the final result. Poll with pollUntilComplete:

import { PresentationsAIClient, pollUntilComplete } from '@presentations-ai/api-client';

const client = new PresentationsAIClient({ apiKey: process.env.PRESENTATIONS_AI_API_KEY! });

const job = await client.createFromTopic({
  topic: '2024 Annual Report: Year in Review',
  exportType: 'pdf',
  slideCount: 30,
  callback_url: 'https://your-webhook.example.com/presentations',  // or use immediatePollUrl: true
});

if ('job_id' in job) {
  const result = await pollUntilComplete(client, job.job_id, {
    intervalMs: 5000,
    maxAttempts: 60,
    onProgress: (status) => console.log(status.message),
  });
  console.log(result.url);
}

Verifying your API key

const auth = await client.authenticate();
console.log(auth.message);  // "API key is valid"

Useful at startup or as a "test connection" button — no credits charged.

Configuration

const client = new PresentationsAIClient({
  apiKey: 'pai_...',                       // Required
  baseUrl: 'https://api.presentations.ai', // Default — override for staging/dev
  timeoutMs: 120_000,                      // Default: 60_000 (60s per request)
});

Retries and timeouts

Built-in retry on transient failures:

• Retries on 429 and 5xx with exponential backoff (1s base, 30s max)
• Stops after 3 retries
• Times out after 60s per request (override with timeoutMs)
• Does not retry on 4xx client errors (400/401/402/404) — those throw immediately

For requests that genuinely take longer than 60s (e.g. a 50-slide deck from a 25 MB PDF), use the async pattern above.

Error handling

All errors are StructuredError with code, message, and remediation:

import { StructuredError } from '@presentations-ai/shared';

try {
  await client.createFromTopic({ topic: '', exportType: 'pptx' });
} catch (error) {
  if (error instanceof StructuredError) {
    error.code;        // "API_VALIDATION_FAILED"
    error.message;     // "topic must be a non-empty string"
    error.remediation; // "Provide a presentation topic (1-500 characters)."
  }
}

| Code | HTTP | Meaning | |---|---|---| | API_UNAUTHORIZED | 401 | Invalid or missing API key | | API_INSUFFICIENT_CREDITS | 402 | Account is out of credits | | API_VALIDATION_FAILED | 400 | Invalid request parameters | | API_NOT_FOUND | 404 | Resource not found | | API_RATE_LIMITED | 429 | Too many requests (auto-retried) | | API_SERVER_ERROR | 5xx | Server error (auto-retried) | | API_TIMEOUT | — | Request exceeded timeoutMs |

Requirements

• Node.js >= 20.0.0
• Presentations.AI API key

License

MIT