prodeck-slide-edit-api-spec.md

ProDeck Slide Edit Loop API Spec

Goal

Add UI-equivalent slide editing to headless API so an agent can do:

• "Make slide 3 more like X"
• update only that slide image
• rebuild PPTX
• return updated deck artifact

This should mirror the current in-UI edit experience, but over API.

---

Scope

Implement Milestone 2A:

1. Edit a single slide in an existing job
2. Persist edited image in job outputs
3. Re-export PPTX using updated slides
4. Return updated status + artifact URLs

No major architecture rewrite required.

---

Existing Assumptions

• Job storage exists at server/storage/jobs/<jobId>/
• manifest.json tracks slides + status
• Slide images exist in outputs/ (e.g. slide-1.png)
• pptx export service already works in headless mode

---

API Additions

1) Edit Single Slide

POST /api/deck/jobs/:jobId/slides/:slideNumber/edit

Content type

Support either:

• application/json (recommended)
• or multipart/form-data (if optionally uploading additional refs)

JSON Request (v1)

{
  "instruction": "Make this slide cleaner and more executive, reduce text density, emphasize 3 bullet points.",
  "provider": "gemini",
  "rebuildPptx": true
}

Optional fields

• provider: gemini | openai (default: job provider or gemini)
• rebuildPptx: boolean (default: true)
• preserveAspect: boolean (default: true, forced 16:9 behavior)

Response (accepted)

{
  "jobId": "deck_...",
  "slideNumber": 3,
  "editJob": {
    "id": "edit_2026...",
    "status": "queued",
    "statusUrl": "/api/deck/jobs/deck_.../edits/edit_2026..."
  }
}

Note: Can also run synchronously and return final URLs, but async is safer.

---

2) Edit Status Endpoint

GET /api/deck/jobs/:jobId/edits/:editId

Response

{
  "jobId": "deck_...",
  "editId": "edit_...",
  "status": "queued|editing|reexporting|done|error",
  "slideNumber": 3,
  "error": null,
  "updatedAt": "..."
}

---

3) Optional Direct Rebuild Endpoint

POST /api/deck/jobs/:jobId/rebuild-pptx

Rebuild deck from current slide images + manifest.

Request

{
  "force": true
}

Response

{
  "jobId": "deck_...",
  "status": "done",
  "pptxUrl": "/api/deck/jobs/deck_.../pptx"
}

---

Manifest Changes

Extend manifest.json to track edit history:

{
  "jobId": "deck_...",
  "status": "done",
  "slides": [
    {
      "slideNumber": 3,
      "title": "...",
      "visualPrompt": "...",
      "imagePath": "outputs/slide-3.png",
      "versions": [
        {
          "version": 1,
          "imagePath": "outputs/slide-3.v1.png",
          "source": "initial"
        },
        {
          "version": 2,
          "imagePath": "outputs/slide-3.v2.png",
          "source": "edit",
          "instruction": "Make this slide cleaner...",
          "editedAt": "2026-..."
        }
      ]
    }
  ],
  "edits": [
    {
      "editId": "edit_...",
      "slideNumber": 3,
      "instruction": "...",
      "status": "done",
      "createdAt": "...",
      "completedAt": "..."
    }
  ]
}

Minimum requirement:

• preserve previous image version (slide-3.v1.png)
• write edited output (slide-3.v2.png)
• update active imagePath for slide 3 to latest version

---

Service-Level Implementation

A) Add slide edit service

server/services/slideEdit.ts

Functions:

• editSlide(jobId, slideNumber, instruction, options)
• load current slide image (base64)
• call provider edit model:
  • Gemini: existing image edit flow with prompt + inline image
• write new version file
• update manifest slide entry
• return new image metadata

B) Re-export service reuse

After successful edit (if rebuildPptx=true):

• call existing pptx export service
• overwrite outputs/deck.pptx
• update manifest timestamps

C) Queueing

• Use existing p-queue
• edit tasks should queue per job to avoid concurrent write conflicts

---

Prompting Guidance for Edit Endpoint

Use a deterministic edit wrapper prompt:

Edit this existing slide image according to the instruction.
Instruction: "{instruction}"
Constraints:
- Preserve 16:9 aspect ratio
- Keep overall brand style coherent with deck
- Do not alter unrelated regions unnecessarily
- Maintain legibility of visible text unless instruction requests text changes

If you support brand profile style reinforcement, append profile style prompt.

---

Error Handling

Return explicit errors:

• 404 job not found
• 404 slide number not found in manifest
• 400 missing/empty instruction
• 409 job currently in incompatible state (optional)
• 500 provider/edit/export failures with safe message

Examples:

{ "error": "Slide 3 not found for job deck_..." }
{ "error": "instruction is required" }

---

Acceptance Criteria

1. Generate a deck via /api/deck/generate
2. Call slide edit endpoint for slide N
3. Poll edit status to done
4. Fetch /api/deck/jobs/:jobId/result and confirm slide N image URL changed
5. Download /api/deck/jobs/:jobId/pptx and confirm updated slide present
6. Manifest contains edit history and prior version retained

---

Smoke Test Commands

1) Submit edit

curl -X POST http://<HOST>:8787/api/deck/jobs/<JOB_ID>/slides/3/edit \
  -H "Content-Type: application/json" \
  -d '{
    "instruction": "Make this slide cleaner, higher contrast, fewer words, stronger hierarchy.",
    "provider": "gemini",
    "rebuildPptx": true
  }'

2) Poll edit status

curl http://<HOST>:8787/api/deck/jobs/<JOB_ID>/edits/<EDIT_ID>

3) Download updated PPTX

curl -o updated.pptx http://<HOST>:8787/api/deck/jobs/<JOB_ID>/pptx

---

Nice-to-have (optional)

• POST /api/deck/jobs/:jobId/slides/:slideNumber/regenerate (use original visualPrompt, no edit image)
• POST /api/deck/jobs/:jobId/slides/:slideNumber/revert (switch active image to prior version)
• PATCH /api/deck/jobs/:jobId/slides/:slideNumber/prompt (update visualPrompt then regenerate)
• webhook callback when edit done

---

Minimal ETA

• Core implementation: ~2-4 hours
• With versioning + robust tests: ~1 day

This is the smallest addition that unlocks true conversational slide refinement from OpenClaw/agents.