slideforge-dev Translate API

openapi: 3.2.0
info:
  title: SlideForge Translate 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: Translate
paths:
  /v1/translate:
    post:
      tags:
      - Translate
      summary: Translate an uploaded PPTX file
      description: 'Upload a .pptx file and receive a translated version with all formatting preserved. Runs asynchronously — the response contains a job_id to poll via GET /v1/jobs/{job_id}.


        **Max file size:** 50 MB. **Max slides:** 100. **Macros rejected.**


        **Pricing:** $0.02 per slide, flat. The wallet is checked for every slide before any work starts (402 with a checkout link if it cannot cover the deck); slides whose translation still overflows at the minimum font size are not billed.


        **Fidelity-preserving:** text runs are translated in place via python-pptx, preserving fonts, colors, sizes, positions, charts, tables, and embedded images.'
      operationId: translate_upload_v1_translate_post
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_translate_upload_v1_translate_post'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '202':
          description: Translation queued
        '400':
          description: Invalid file (size, format, macros, or structure)
        '402':
          description: Insufficient balance
        '413':
          description: File too large
        '422':
          description: Validation error
        '429':
          description: Rate limit exceeded
  /v1/translate/from-job:
    post:
      tags:
      - Translate
      summary: Translate an existing job's PPTX (JSON body)
      description: 'JSON-body alternative to POST /v1/translate for the no-file case. Cleaner DX for agents that don''t want to construct multipart just to say ''translate this existing job into German''.


        Identical pricing and identical background pipeline as /v1/translate; the only difference is the request shape.'
      operationId: translate_from_job_v1_translate_from_job_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TranslateFromJobRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '202':
          description: Translation queued
        '400':
          description: Invalid input
        '402':
          description: Insufficient balance
        '404':
          description: Source job not found
        '429':
          description: Rate limit exceeded
        '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
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    Body_translate_upload_v1_translate_post:
      properties:
        file:
          anyOf:
          - type: string
            format: binary
          - type: 'null'
          title: File
          description: The .pptx file to translate (omit when source_job_id is provided)
        source_job_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Job Id
          description: ID of an existing slideforge job whose pptx_url should be translated (alternative to uploading a file). Useful for translating decks just produced by /v1/generate, /v1/deck, or /v1/deck/from-pdf without downloading and re-uploading the .pptx.
        target_language:
          type: string
          title: Target Language
          description: ISO 639-1 target language code
        source_language:
          type: string
          title: Source Language
          description: ISO 639-1 source language or 'auto' to detect
          default: auto
        mode:
          type: string
          title: Mode
          description: Translation model tier, 'draft' or 'pro'. No price effect.
          default: draft
        include_notes:
          type: boolean
          title: Include Notes
          description: Translate speaker notes
          default: false
        include_tables:
          type: boolean
          title: Include Tables
          description: Translate table cells
          default: true
        concise_mode:
          type: boolean
          title: Concise Mode
          description: Hint LLM to prefer shorter translations
          default: false
        delete_after_download:
          type: boolean
          title: Delete After Download
          description: Auto-delete source + output on first download
          default: false
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
          description: Human-readable job name
        dry_run:
          type: boolean
          title: Dry Run
          description: Return cost + duration estimate without creating a job.
          default: false
      type: object
      required:
      - target_language
      title: Body_translate_upload_v1_translate_post
    TranslateFromJobRequest:
      properties:
        source_job_id:
          type: string
          title: Source Job Id
        target_language:
          type: string
          title: Target Language
        source_language:
          type: string
          title: Source Language
          default: auto
        include_notes:
          type: boolean
          title: Include Notes
          default: false
        include_tables:
          type: boolean
          title: Include Tables
          default: true
        concise_mode:
          type: boolean
          title: Concise Mode
          default: false
        delete_after_download:
          type: boolean
          title: Delete After Download
          default: false
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
      type: object
      required:
      - source_job_id
      - target_language
      title: TranslateFromJobRequest
      description: 'POST /v1/translate/from-job request body.


        JSON-body alternative to /v1/translate (multipart) for the no-file case.

        Cleaner DX for agents that don''t want to construct multipart for what is

        effectively a JSON request: ''translate this existing job into German''.'
  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.