PDFThin API

Ueberblick

Alle Uploads nutzen multipart/form-data. Antworten sind JSON.

• Basis-URL: https://pdfthin.com (oder Ihre SITE_URL).
• Rate Limit: RATE_LIMIT_RPM pro IP (Standard 60/min).
• Max. Upload: MAX_UPLOAD_MB (Standard 200 MB).
• Dateien werden nach 60 Stunden gelöscht.
• Eingaben: PDF-Datei; optionales Wasserzeichen PNG/JPG bis 5MB.
• Upload-Varianten: einzelne Datei (optimize/split) oder mehrere Dateien (organize).

Server-Konfiguration

Wichtige Umgebungsvariablen, die das API-Verhalten beeinflussen.

• REDIS_URL: Job-Queue und Statusspeicher.
• S3_ENDPOINT/S3_BUCKET/S3_ACCESS_KEY/S3_SECRET_KEY: Objektspeicher (optional, sonst lokal).
• Dateien werden nach 60 Stunden gelöscht.
• RATE_LIMIT_RPM und DOWNLOAD_TOKEN_TTL_MIN.

Job erstellen (optimize oder split)

POST /api/jobs mit multipart/form-data.

• mode=split ignoriert quality und liefert bei Bedarf Teile.
• Wenn quality gesetzt ist, werden preset/custom_mb ignoriert.
• Bei quality_mode=smart probiert die API hohe bis niedrige Qualitaet, um die Groesse zu treffen.

curl -X POST https://pdfthin.com/api/jobs   -F "[email protected]"   -F "preset=gmail25"   -F "mode=optimize"

curl -X POST https://pdfthin.com/api/jobs   -F "[email protected]"   -F "preset=custom"   -F "custom_mb=12"   -F "quality_mode=smart"   -F "mode=optimize"

curl -X POST https://pdfthin.com/api/jobs   -F "[email protected]"   -F "quality=printer"   -F "mode=optimize"

Job erstellen (organize)

Mit mode=organize Seiten zusammenfuehren, drehen, loeschen, neu anordnen und teilen.

• Bei mehreren Dateien werden sie in Upload-Reihenfolge zusammengefuehrt.
• Mindestens eine Operation oder mehrere Dateien sind erforderlich.

curl -X POST https://pdfthin.com/api/jobs   -F "[email protected]"   -F "[email protected]"   -F "mode=organize"   -F "rotate_angle=90"   -F "rotate_pages=1-2"

Status pruefen

GET /api/jobs/{id} liefert Job-Status und Ergebnisdateien.

• Statuswerte: queued | processing | done | failed.

{
  "id": "job-id",
  "status": "done",
  "progress_pct": 100,
  "expires_at": "2026-01-22T11:02:51Z",
  "result": {
    "kind": "single",
    "files": [
      {
        "name": "output.pdf",
        "size": 503937,
        "download_url": "/api/jobs/job-id/download?index=0"
      }
    ]
  }
}

Ergebnisse herunterladen

GET /api/jobs/{id}/download?index=0

• Nutze index=0..n fuer Mehrteilergebnisse.
• Ohne Token liefert die API eine Weiterleitung mit kurzlebigem Token.
• Token-TTL: DOWNLOAD_TOKEN_TTL_MIN Minuten.

curl -L "https://pdfthin.com/api/jobs/job-id/download?index=0" -o output.pdf

Job loeschen

DELETE /api/jobs/{id} entfernt gespeicherte Dateien und Status.

• Antwort: 204 No Content.

curl -X DELETE https://pdfthin.com/api/jobs/job-id

Fehlercodes

Fehler nutzen JSON: {"error":{"code":"...","message":"..."}}

• ERR_INVALID_FILE
• ERR_TOO_LARGE
• ERR_PASSWORD_PROTECTED
• ERR_CANNOT_FIT_SINGLE_PAGE
• ERR_TIMEOUT
• ERR_INTERNAL
• ERR_NOT_FOUND
• ERR_NOT_READY
• ERR_TOKEN_USED
• ERR_FORBIDDEN

OpenAPI (Entwurf)

Minimales OpenAPI-3.0-Snippet zur schnellen Integration.

openapi: 3.0.3
info:
  title: PDFThin API
  version: "1.0"
paths:
  /api/jobs:
    post:
      summary: Create a job
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                mode:
                  type: string
                preset:
                  type: string
                custom_mb:
                  type: integer
                quality:
                  type: string
                quality_mode:
                  type: string
                watermark:
                  type: string
                  format: binary
      responses:
        "202":
          description: Accepted
  /api/jobs/{id}:
    get:
      summary: Get job status
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: OK
    delete:
      summary: Delete job
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: No Content
  /api/jobs/{id}/download:
    get:
      summary: Download result
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: query
          name: index
          schema:
            type: integer
      responses:
        "303":
          description: See Other