Generate a Deck

POST/v1/deck

Generate a multi-slide deck. Slides are generated in parallel (up to 3 concurrent) and auto-compiled into a single .pptx. Supports two modes: explicit briefs or auto-brief from a prompt.

Parameters

Name	Type	Required	Description
slides	SlideSpec[]	optional	Explicit slide briefs. Each has: brief (string, required), name (string, optional), slide_number (int, optional). Leave empty for auto-brief mode.
prompt	string	optional	High-level deck topic (auto-brief mode). Used when slides is empty.
slide_count	integer	optional	Target number of slides (1-30). Used with prompt for auto-brief mode.
audience	string	optional	Target audience description (auto-brief mode).
focus_area	string	optional	What to emphasize (auto-brief mode).
visual_style	string	optional	Visual tone description (auto-brief mode).
name	string	optional	Deck name. Defaults to title or 'Untitled Deck'.
theme_id	string	optional	Theme for all slides.
title	string	optional	Deck title (PowerPoint metadata).
author	string	optional	Author name (PowerPoint metadata).
mode	string	optional	Ignored — always pro quality ($0.20/slide). Kept for backward compat.
auto_iterations	integer	optional	Visual QA rounds per slide (0-3). Default: 0.

Response

202

{
  "job_id": "deck-a1b2c3d4",
  "status": "queued",
  "name": "Q4 Strategy Deck",
  "slides": [
    {
      "slide_number": 1,
      "status": "queued"
    },
    {
      "slide_number": 2,
      "status": "queued"
    },
    {
      "slide_number": 3,
      "status": "queued"
    }
  ]
}

Mode 1: Explicit briefs

Provide a slides array with individual briefs for each slide.

curl

curl -X POST https://api.slideforge.dev/v1/deck \
  -H "Authorization: Bearer sf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slides": [
      {"brief": "Title slide: Q4 Strategy Review"},
      {"brief": "2x2 matrix: market opportunity vs effort"},
      {"brief": "Timeline: key milestones for Q4"}
    ],
    "theme_id": "consulting_dark",
    "title": "Q4 Strategy Review"
  }'

Mode 2: Auto-brief

Provide a prompt and slide_count. The AI generates per-slide briefs automatically.

curl

curl -X POST https://api.slideforge.dev/v1/deck \
  -H "Authorization: Bearer sf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Cloud migration strategy for a mid-size enterprise",
    "slide_count": 5,
    "audience": "CTO and engineering leadership",
    "theme_id": "consulting_blue"
  }'

Polling for deck status

The job response includes per-slide progress so you can show a progress bar.

curl

# Poll deck status — includes per-slide progress
curl https://api.slideforge.dev/v1/jobs/DECK_JOB_ID \
  -H "Authorization: Bearer sf_live_YOUR_KEY"

# Response when complete:
# {
#   "job_id": "deck-a1b2c3d4",
#   "status": "complete",
#   "pptx_url": "https://...",
#   "slides": [
#     {"slide_number": 1, "status": "complete"},
#     {"slide_number": 2, "status": "complete"},
#     {"slide_number": 3, "status": "complete"}
#   ]
# }

PATCH /v1/deck/{id}

Update a deck — swap individual slides, change metadata, or apply a different theme. Pass a replace array to swap slides by position.

curl

# Swap slide at position 2 with a new job
curl -X PATCH https://api.slideforge.dev/v1/deck/DECK_JOB_ID \
  -H "Authorization: Bearer sf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "replace": [{"position": 2, "job_id": "NEW_SLIDE_JOB_ID"}],
    "title": "Updated Q4 Strategy"
  }'

POST /v1/deck/from-jobs

Assemble a deck from existing completed slide jobs. No generation — just merge and compile. Free. Auto-follows iteration chains: pass any version's job_id and the latest iterate child is used.

curl

# Assemble a deck from existing slide jobs
curl -X POST https://api.slideforge.dev/v1/deck/from-jobs \
  -H "Authorization: Bearer sf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "job_ids": ["slide-job-1", "slide-job-2", "slide-job-3"],
    "title": "Compiled Deck",
    "theme_id": "consulting_blue"
  }'

POST /v1/deck/{id}/fork

Create a variant of an existing deck. The fork shares slide blobs (no duplication) but has its own metadata, so changes to the fork don't affect the original. Free. Use for A/B testing, per-audience versions, or alternative narratives.

curl

# Fork a deck for a different audience
curl -X POST https://api.slideforge.dev/v1/deck/DECK_JOB_ID/fork \
  -H "Authorization: Bearer sf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q4 Strategy — Board Version",
    "title": "Q4 Strategy Review (Board)"
  }'