slideforge-dev Tools Free Tier API

openapi: 3.2.0
info:
  title: SlideForge Tools Free Tier 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: tools-free-tier
paths:
  /v1/tools/pdf-analyze:
    post:
      tags:
      - tools-free-tier
      summary: Inspect a PDF and say what is possible (public, no auth, no conversion)
      description: 'The public half of /tools/pdf-to-pptx: returns producer, page count, source classification and `can_extract` so a visitor learns whether their PDF converts to editable shapes — before signing up. No job, no persistence, no conversion, no charge. Converting is authenticated: POST /v1/deck/from-pdf.'
      operationId: public_pdf_analyze_v1_tools_pdf_analyze_post
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_public_pdf_analyze_v1_tools_pdf_analyze_post'
        required: true
      responses:
        '200':
          description: Analysis returned
          content:
            application/json:
              schema: {}
        '400':
          description: Invalid PDF (not a PDF, corrupted, empty)
        '413':
          description: File too large
        '429':
          description: Rate limit exceeded (30/hour/IP)
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/tools/pdf-to-pptx:
    post:
      tags:
      - tools-free-tier
      summary: Convert the first 3 pages of a PDF to editable .pptx (public, no auth)
      description: 'The free taste: a real, editable, unwatermarked .pptx of the first 3 pages, on a 1-hour download link. Only PDFs the analyzer classifies as `slide-vector` convert here — that path is pure compute. 25 MB max, 5 requests per hour per IP. The full document is authenticated: POST /v1/deck/from-pdf.'
      operationId: free_pdf_to_pptx_v1_tools_pdf_to_pptx_post
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_free_pdf_to_pptx_v1_tools_pdf_to_pptx_post'
        required: true
      responses:
        '200':
          description: Converted — response includes a signed download_url
          content:
            application/json:
              schema: {}
        '400':
          description: Invalid PDF (not a PDF, corrupted, empty)
        '413':
          description: File exceeds the 25 MB free-tier cap
        '422':
          description: This PDF's bucket does not convert on the free path
        '429':
          description: Rate limit exceeded (5/hour/IP)
        '503':
          description: Conversion timed out or storage unavailable
  /v1/tools/combine-powerpoint:
    post:
      tags:
      - tools-free-tier
      summary: Merge the first 2 uploaded .pptx files into one deck (public, no auth)
      description: 'The free merge: your first 2 uploaded decks combined in full, on a 1-hour download link. Pure compute — no LLM, no watermark, and no AI-disclosure stamp, because these are your slides and we only concatenated them. 20 MB per file. 5 merges per hour per IP.'
      operationId: free_combine_powerpoint_v1_tools_combine_powerpoint_post
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_free_combine_powerpoint_v1_tools_combine_powerpoint_post'
        required: true
      responses:
        '200':
          description: Merged — response includes a signed download_url
          content:
            application/json:
              schema: {}
        '400':
          description: Fewer than 2 .pptx files, or a file that is not a readable .pptx
        '413':
          description: A file exceeds 20 MB, or the pair exceeds 40 MB
        '429':
          description: Rate limit exceeded (5/hour/IP)
        '503':
          description: Busy, merge failed, or storage unavailable
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/tools/preview-variant:
    post:
      tags:
      - tools-free-tier
      summary: Render a catalog variant to a preview PNG (public, no auth)
      description: 'Renders one pinned catalog variant to an image so a visitor can see real output before signing up. No .pptx is produced and nothing is downloadable. Takes a `prior_id` from the catalog — NOT a free-text brief: matching a brief to a layout needs the router, which spends model tokens, so it happens behind a free account.'
      operationId: preview_catalog_variant_v1_tools_preview_variant_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VariantPreviewRequest'
        required: true
      responses:
        '200':
          description: Rendered — response includes a short-lived preview_url
          content:
            application/json:
              schema: {}
        '400':
          description: Unknown prior_id
        '429':
          description: Rate limit exceeded (30/hour/IP)
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/tools/preview-code:
    post:
      tags:
      - tools-free-tier
      summary: Run python-pptx code and return a preview image (public, no auth)
      description: Executes python-pptx code in the sandbox and returns slide 1 as an inline PNG (768px) plus static lint findings (overlaps, off-canvas shapes, tiny fonts, chart semantics) in `lint[]`. Send a python-pptx script as it is (the presentation it saves is the one shown), or a `build(prs)` function. No .pptx is produced and nothing is downloadable — the file, PDF export, and full-resolution renders live in the playground and /v1/render/code. 16KB code cap, 10s timeout, 1 slide.
      operationId: preview_code_v1_tools_preview_code_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CodePreviewRequest'
        required: true
      responses:
        '200':
          description: Preview rendered, or code diagnostics with status invalid/failed
          content:
            application/json:
              schema: {}
        '429':
          description: Rate limit exceeded (3/minute, 20/hour per IP)
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/tools/attempt:
    post:
      tags:
      - tools-free-tier
      summary: Record an anonymous free-tool attempt (public, no auth)
      description: Fire-and-forget beacon so an anonymous attempt on a free-tool page is countable. Accepts shape only — file count, total bytes, mime types. Never filenames or content.
      operationId: record_tool_attempt_v1_tools_attempt_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ToolAttempt'
        required: true
      responses:
        '200':
          description: Recorded (or silently dropped)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolAttemptAck'
        '429':
          description: Rate limit exceeded (60/hour/IP)
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    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
    Body_free_pdf_to_pptx_v1_tools_pdf_to_pptx_post:
      properties:
        file:
          type: string
          format: binary
          title: File
          description: The .pdf file to convert
      type: object
      required:
      - file
      title: Body_free_pdf_to_pptx_v1_tools_pdf_to_pptx_post
    VariantPreviewRequest:
      properties:
        prior_id:
          type: string
          maxLength: 120
          minLength: 1
          title: Prior Id
      type: object
      required:
      - prior_id
      title: VariantPreviewRequest
      description: A pinned catalog variant to render. NOT a brief — see the endpoint docstring.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    CodePreviewRequest:
      properties:
        code:
          type: string
          maxLength: 16384
          minLength: 1
          title: Code
        theme_id:
          anyOf:
          - type: string
            maxLength: 80
          - type: 'null'
          title: Theme Id
      type: object
      required:
      - code
      title: CodePreviewRequest
      description: python-pptx source to preview. Code only — no chrome, no job refs, no uploads.
    ToolAttempt:
      properties:
        tool:
          type: string
          enum:
          - image-to-pptx
          - combine-powerpoint
          - pdf-to-pptx
          title: Tool
        file_count:
          type: integer
          maximum: 100.0
          minimum: 1.0
          title: File Count
        total_bytes:
          type: integer
          minimum: 0.0
          title: Total Bytes
        mimes:
          items:
            type: string
          type: array
          maxItems: 100
          title: Mimes
      type: object
      required:
      - tool
      - file_count
      - total_bytes
      title: ToolAttempt
      description: A file picked on a free-tool page. Shape only — never a filename or content.
    ToolAttemptAck:
      properties:
        recorded:
          type: boolean
          title: Recorded
      type: object
      required:
      - recorded
      title: ToolAttemptAck
    Body_public_pdf_analyze_v1_tools_pdf_analyze_post:
      properties:
        file:
          type: string
          format: binary
          title: File
          description: The .pdf file to analyse
      type: object
      required:
      - file
      title: Body_public_pdf_analyze_v1_tools_pdf_analyze_post
    Body_free_combine_powerpoint_v1_tools_combine_powerpoint_post:
      properties:
        files:
          items:
            type: string
            format: binary
          type: array
          title: Files
          description: Two or more .pptx files, in merge order
      type: object
      required:
      - files
      title: Body_free_combine_powerpoint_v1_tools_combine_powerpoint_post
  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.