slideforge-dev PDF API

openapi: 3.2.0
info:
  title: SlideForge PDF API
  description: 'Agent-first PowerPoint generation. Send structured slide intents (a `form` plus typed fields) or a brief; get back a real, editable `.pptx`. The draw path is deterministic — no model renders your slide, so supplied numbers and text come out verbatim. Every response carries `status`, `fidelity` and `warnings` so an automated caller can tell whether the output is usable. $0.05 per slide; an unusable slide is not billed. Authenticate with a SlideForge API key (`Authorization: Bearer sf_live_…` or `X-API-Key`) — new accounts include 60 free slides, no credit card: https://slideforge.dev/sign-up'
  version: 5.356.0
servers:
- url: https://api.slideforge.dev
security:
- bearerAuth: []
- apiKeyAuth: []
tags:
- name: PDF
paths:
  /v1/render/from-pdf/analyze:
    post:
      tags:
      - PDF
      summary: 'Ingest: inspect a PDF, no job, no charge'
      description: 'Free preview endpoint — no charge, no persistence.


        Logs each call''s producer + page count + source classification to

        slideforge.telemetry so we can see what real users upload and prioritize

        which producers to support next. Fire-and-forget — never fails the

        request.'
      operationId: analyze_pdf_endpoint_v1_render_from_pdf_analyze_post
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_analyze_pdf_endpoint_v1_render_from_pdf_analyze_post'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PdfAnalysis'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/deck/from-pdf/analyze:
    post:
      tags:
      - PDF
      summary: Inspect a PDF and propose an extraction strategy (no job, no charge)
      description: Upload a PDF and receive metadata, per-page stats, source classification, and an estimated cost. Use this to show users what they're about to spend before calling `/v1/deck/from-pdf`. No job is created and the file is not persisted — re-upload the same file to `/v1/deck/from-pdf` when ready.
      operationId: analyze_pdf_endpoint_v1_deck_from_pdf_analyze_post
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_analyze_pdf_endpoint_v1_deck_from_pdf_analyze_post'
        required: true
      responses:
        '200':
          description: Analysis returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PdfAnalysis'
        '400':
          description: Invalid PDF (size, format, corrupted)
        '413':
          description: File too large
        '429':
          description: Rate limit exceeded
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/render/from-pdf:
    post:
      tags:
      - PDF
      summary: 'Ingest: PDF (PowerPoint export) → editable PPTX deck'
      description: POST /v1/deck/from-pdf — convert a PowerPoint-exported PDF into an editable PPTX.
      operationId: deck_from_pdf_v1_render_from_pdf_post
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_deck_from_pdf_v1_render_from_pdf_post'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '202':
          description: Extraction queued
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/deck/from-pdf:
    post:
      tags:
      - PDF
      summary: Convert a PDF (PowerPoint export) into an editable PPTX deck
      description: 'Upload a PDF and receive an editable .pptx with the original text, layout, shapes, and images preserved.


        Currently supports PDFs exported from slide tools (PowerPoint, Keynote, Google Slides, Canva, LaTeX Beamer, etc.). Text documents are not converted: to turn a document into slides, let the calling assistant read it and send the slides as intents.


        **Max file size:** 50 MB.'
      operationId: deck_from_pdf_v1_deck_from_pdf_post
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_deck_from_pdf_v1_deck_from_pdf_post'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '202':
          description: Extraction queued
        '400':
          description: Invalid PDF (size, format, corrupted)
        '402':
          description: Insufficient balance
        '413':
          description: File too large
        '422':
          description: Unsupported PDF source (not a PowerPoint export)
        '429':
          description: Rate limit exceeded
components:
  schemas:
    Body_analyze_pdf_endpoint_v1_deck_from_pdf_analyze_post:
      properties:
        file:
          type: string
          format: binary
          title: File
          description: The .pdf file to analyze
      type: object
      required:
      - file
      title: Body_analyze_pdf_endpoint_v1_deck_from_pdf_analyze_post
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    PdfFeatures:
      properties:
        aspect_ratio_first:
          type: number
          title: Aspect Ratio First
          description: width / height of the first page
        is_slide_aspect:
          type: boolean
          title: Is Slide Aspect
          description: True if the first page sits in a slide-shaped aspect band (roughly 1.25–2.45 — covers 4:3, 16:10, 16:9, ultrawide)
        is_doc_portrait:
          type: boolean
          title: Is Doc Portrait
          description: True if the first page is portrait-oriented (aspect < 1.0)
        consistent_dimensions:
          type: boolean
          title: Consistent Dimensions
          description: True if every page in the document shares the same width/height
        total_text_chars:
          type: integer
          title: Total Text Chars
          description: Sum of extractable characters across all pages
        total_text_spans:
          type: integer
          title: Total Text Spans
          description: Sum of text spans (formatted runs) across all pages. Zero with non-zero total_text_chars suggests glyph-outlined text — readable but unformatted.
        total_images:
          type: integer
          title: Total Images
          description: Sum of embedded images across all pages
        total_drawings:
          type: integer
          title: Total Drawings
          description: Sum of vector drawing primitives (rects, paths, lines) across all pages — high counts indicate hand-built slide content rather than scanned/raster
        unique_fonts:
          type: integer
          title: Unique Fonts
          description: Number of distinct fonts seen across the doc
        pages_with_text:
          type: integer
          title: Pages With Text
          description: Pages with at least 50 chars of extractable text
        pages_image_only:
          type: integer
          title: Pages Image Only
          description: Pages with images present but fewer than 50 chars of extractable text
        pages_blank:
          type: integer
          title: Pages Blank
          description: Pages with no text and no images
      type: object
      required:
      - aspect_ratio_first
      - is_slide_aspect
      - is_doc_portrait
      - consistent_dimensions
      - total_text_chars
      - total_text_spans
      - total_images
      - total_drawings
      - unique_fonts
      - pages_with_text
      - pages_image_only
      - pages_blank
      title: PdfFeatures
      description: 'Document-level structural features used by the bucket classifier.


        Everything here comes from `fitz` primitives — no LLM calls. The fields

        are deliberately concrete (counts, ratios, booleans) so threshold tuning

        against a real corpus is reproducible.'
    Body_deck_from_pdf_v1_deck_from_pdf_post:
      properties:
        file:
          type: string
          format: binary
          title: File
          description: The .pdf file to convert
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
          description: Human-readable job name
        source:
          anyOf:
          - type: string
          - type: 'null'
          title: Source
          description: Entry tag persisted on jobs.source (attribution)
      type: object
      required:
      - file
      title: Body_deck_from_pdf_v1_deck_from_pdf_post
    Body_deck_from_pdf_v1_render_from_pdf_post:
      properties:
        file:
          type: string
          format: binary
          title: File
          description: The .pdf file to convert
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
          description: Human-readable job name
        source:
          anyOf:
          - type: string
          - type: 'null'
          title: Source
          description: Entry tag persisted on jobs.source (attribution)
      type: object
      required:
      - file
      title: Body_deck_from_pdf_v1_render_from_pdf_post
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    Body_analyze_pdf_endpoint_v1_render_from_pdf_analyze_post:
      properties:
        file:
          type: string
          format: binary
          title: File
          description: The .pdf file to analyze
      type: object
      required:
      - file
      title: Body_analyze_pdf_endpoint_v1_render_from_pdf_analyze_post
    PdfPageInfo:
      properties:
        page_number:
          type: integer
          title: Page Number
          description: 1-based page number
        has_text:
          type: boolean
          title: Has Text
          description: True if the page contains extractable text
        has_images:
          type: boolean
          title: Has Images
          description: True if the page contains embedded images
        text_char_count:
          type: integer
          title: Text Char Count
          description: Total characters of extractable text
        text_preview:
          type: string
          title: Text Preview
          description: First ~80 characters of text content (for the analysis card)
          default: ''
      type: object
      required:
      - page_number
      - has_text
      - has_images
      - text_char_count
      title: PdfPageInfo
      description: Per-page summary returned by the analyzer (lean — used by the UI list).
    PdfAnalysis:
      properties:
        producer:
          type: string
          title: Producer
          description: PDF metadata producer string (telemetry only — never used for routing). Captured so we can correlate buckets with real-world tools after the fact.
          default: ''
        page_count:
          type: integer
          title: Page Count
          description: Number of pages in the PDF
        file_size_bytes:
          type: integer
          title: File Size Bytes
          description: Source PDF size in bytes
        bucket:
          type: string
          enum:
          - slide-vector
          - slide-raster
          - doc-text
          - doc-image-heavy
          - scanned
          - mixed
          - unknown
          title: Bucket
          description: Routing decision derived from structural features. The /v1/deck/from-pdf endpoint accepts a file iff its bucket is currently implemented.
        features:
          $ref: '#/components/schemas/PdfFeatures'
          description: Document-level structural features used by the classifier
        estimated_cost_usd:
          type: number
          title: Estimated Cost Usd
          description: Per-page price for the bucket × page_count
        can_extract:
          type: boolean
          title: Can Extract
          description: True iff /v1/deck/from-pdf will currently accept this file.
        unsupported_reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Unsupported Reason
          description: Human-readable hint shown to the user when can_extract is False, explaining what's not yet supported.
        pages:
          items:
            $ref: '#/components/schemas/PdfPageInfo'
          type: array
          title: Pages
          description: Per-page summary, in document order
      type: object
      required:
      - page_count
      - file_size_bytes
      - bucket
      - features
      - estimated_cost_usd
      - can_extract
      title: PdfAnalysis
      description: Output of analyze_pdf() — what /analyze returns and what /generate uses to route.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'SlideForge API key: `Authorization: Bearer sf_live_…`. Create one at https://slideforge.dev/console/keys'
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Same key, header form — for clients that cannot set Authorization.