Jobs
Create single-input jobs, start them, list them, fetch status, and refresh signed result URLs when needed.
https://api.filemorf.com/api/public
Bearer API key from a Developer or Enterprise workspace.
Signed uploads, queued jobs, retained artifacts, refreshable URLs.
Endpoints
Single-input jobs are the core execution primitive
Use the jobs endpoints for any workflow that starts from one input file. The returned result object includes metadata and one or more signed download URLs.
/jobs
Create a single-input job and receive one upload URL.
/jobs
List API-created jobs for the authenticated key owner.
/jobs/:id
Fetch job status, result metadata, and download URLs.
/jobs/:id/start
Idempotently queue a pending job after upload completes.
/jobs/:id/refresh-url
Refresh signed output URLs for completed jobs.
Supported job types
Choose the job type that matches the input and output behavior
The public API validates content types before creating work. The job type and input content type must line up.
| Job type | Valid inputs | Notes |
|---|---|---|
| image-convert | PNG, JPEG, WebP, AVIF, GIF, BMP, SVG, TIFF, HEIC | Converts one image to another supported image target. |
| image-compress | PNG, JPEG, WebP, AVIF, GIF | Optimizes one image while keeping the same general media class. |
| image-resize | PNG, JPEG, WebP, AVIF, GIF, SVG, TIFF | Resizes a single image with width and height controls. |
| pdf-split | Multi-output; use result.files[] and retained artifacts for downstream automation. | |
| pdf-extract | Extracts specific pages into one new PDF. | |
| pdf-rotate | Rotates selected pages in a PDF. | |
| pdf-remove | Removes selected pages and returns a new PDF. | |
| pdf-merge | PDF (multiple files) | Use the dedicated POST /merge endpoint instead of POST /jobs. |
| pdf-compress | Compresses a PDF with quality presets while keeping it viewable everywhere. | |
| pdf-protect | Password-protects a PDF (options carry the password; send over TLS only). | |
| pdf-unlock | Removes a password from a PDF you can already open (password required in options). | |
| document-convert | PDF, DOCX, TXT, MD, HTML, XLSX, ODS, JSON, CSV, TSV, XML, YAML | Supports document, spreadsheet, and structured-data conversion targets. |
| ocr | PDF, PNG, JPEG, WebP, TIFF | OCR is a server-side job type and a valid terminal recipe step. |
| image-upscale | PNG, JPEG, WebP | AI upscaling (fal-backed). See AI Jobs for engines, options, and credit pricing. |
| audio-enhance | MP3, WAV, FLAC | AI voice isolation or prompt-driven stem separation. See AI Jobs. |
| audio-transcribe | MP3, WAV, M4A, WebM | AI speech-to-text with TXT, SRT, VTT, and word-timestamp JSON outputs. See AI Jobs. |
States
Poll until a terminal state
Job status drives the rest of the lifecycle. A job only exposes stable outputs once it is completed, and failed jobs expose machine-readable failure metadata instead of internal diagnostics.
| State | Meaning |
|---|---|
| pending | Job exists and is waiting for file upload or start. |
| queued | Upload is complete and the job is waiting in the worker queue. |
| processing | A worker is actively executing the job. |
| completed | The job finished successfully and result metadata is available. |
| failed | The job ended unsuccessfully. The response exposes a stable failure code and diagnostic id, never raw provider or document-derived error text. |
Safe retries
Starting a job is idempotent
After every required upload succeeds, retry POST /jobs/:id/start when a response is lost or a connection fails. A job already queued, processing, or completed returns success with reused: true and does not create a second dispatch.
{
"success": true,
"status": "queued",
"reused": true
}- Only pending jobs are dispatched.
- Queued, processing, and completed jobs return their durable status with reused: true.
- Failed or still-uploading jobs return HTTP 409 with code job_not_startable.
- After an ambiguous start response, read the job state or safely retry start; never create a replacement job by default.