FilezyAI API reference

The FilezyAI Developer API converts files in the cloud — programmatically, from your app, script, or backend. Upload a file (or a batch of images), describe what you want in one ops object, poll until the job finishes, then download the result.

Three endpoints: create task · check status · download output. Authenticate with Authorization: Bearer fz_live_… on every request. Get a key from the dashboard after subscribing on API pricing (separate from Web Pro).

Supported formats

Input & output — png, jpg, jpeg, heic, svg, avif, webp, gif, pdf, docx, xlsx, pptx
Batch (2–50 files in one request) — png, jpg, jpeg, heic, avif, webp, gif only · max 500 MB total · each file = 1 task

Operations (ops object)

Pass ops as a JSON string on POST /v1/api/tasks. Only to is required — everything else is optional and runs in one pipeline pass.

to — output format (required)
compress — target file size range (minKb, maxKb)
resize — width / height, unit (px, in, cm, mm), fit mode
crop — crop region before resize (fractions 0–1)
dpi — output density (1–2400)
name — output base filename (no extension)
pages — PDF/DOCX/PPTX → image: page range e.g. 1-3,5
stripMetadata — remove EXIF, GPS, camera info, etc.
pdfPageSize — image → PDF: fit, a4, or letter
merge — batch only: one combined PDF/DOCX, or ZIP of separate files

Full field reference in the ops object section below.

One call, many operations — no separate compress / resize / rename APIs
Flat monthly pricing — from $10/mo for 2,000 tasks
500 MB per file · 60 create requests/min · poll & download unlimited

Authentication

Request

Send on every request:

Authorization: Bearer fz_live_…

Get a key from the dashboard after subscribing. One active key per account.

Endpoints

Method	Path	Purpose
`POST`	`/v1/api/tasks`	Create task (1 file or batch)
`GET`	`/v1/api/tasks/:id`	Check status
`GET`	`/v1/api/tasks/:id/download`	Download output

Create a task

`POST /v1/api/tasks`

Request

Content-Type: multipart/form-data

Field	Type	Required	Description
`ops`	string	yes	JSON string — see ops object
`file`	file	yes*	Input file. Repeat field for batch (multiple images)
`format`	string	no	Source format if extension is unclear (e.g. `png`)

Header: Authorization: Bearer fz_live_…

Examples

curl -X POST https://api.filezyai.com/v1/api/tasks \
  -H "Authorization: Bearer $FILEZY_API_KEY" \
  -F 'ops={"to":"webp","compress":{"minKb":50,"maxKb":200},"resize":{"width":1200,"unit":"px"},"name":"hero","stripMetadata":true}' \
  -F "format=png" \
  -F "file=@photo.png"

Response · 200

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "tasksUsed": 1
}

Batch: tasksUsed equals the number of files uploaded.

Check status

`GET /v1/api/tasks/:id`

Request

Part	Value
URL param	`id` — task UUID from create response
Header	`Authorization: Bearer fz_live_…`

Examples

curl https://api.filezyai.com/v1/api/tasks/TASK_ID \
  -H "Authorization: Bearer $FILEZY_API_KEY"

Response

200 · processing

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "error": null
}

200 · done

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "done",
  "error": null,
  "output": {
    "format": "webp",
    "size": 184320,
    "filename": "hero.webp"
  },
  "download": {
    "path": "/v1/api/tasks/550e8400-e29b-41d4-a716-446655440000/download"
  }
}

200 · failed

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "error": "Conversion failed: …"
}

status values: queued · processing · done · failed

Download

`GET /v1/api/tasks/:id/download`

Request

Part	Value
URL param	`id` — task UUID
Header	`Authorization: Bearer fz_live_…`

Call only when status is done.

Examples

curl -L https://api.filezyai.com/v1/api/tasks/TASK_ID/download \
  -H "Authorization: Bearer $FILEZY_API_KEY" \
  -o output.webp

Response

200 · file

Raw file bytes. Headers include Content-Disposition: attachment and Content-Type for the output format.

404 / 410

Task not found, not finished, or file expired (2 hours after conversion).

Batch

Send multiple file parts in one POST /v1/api/tasks request. Repeat the file field once per input — at least 2 images required. Images only · max 50 files · 500 MB total · each file = 1 task.

Set "merge": true in ops to combine into one PDF or DOCX (default for those targets). Set "merge": false to get a ZIP of separate outputs.

Examples · merged PDF

Three separate -F file=@… flags in one request:

curl -X POST https://api.filezyai.com/v1/api/tasks \
  -H "Authorization: Bearer $FILEZY_API_KEY" \
  -F 'ops={"to":"pdf","merge":true,"name":"my-album"}' \
  -F "file=@photo1.png" \
  -F "file=@photo2.jpg" \
  -F "file=@photo3.webp"

Examples · separate files (ZIP)

curl -X POST https://api.filezyai.com/v1/api/tasks \
  -H "Authorization: Bearer $FILEZY_API_KEY" \
  -F 'ops={"to":"webp","merge":false,"name":"batch-out"}' \
  -F "file=@photo1.png" \
  -F "file=@photo2.png"

The `ops` object

Fields

Pass as a JSON string in the ops form field. Only to is required — everything else is optional and runs in one pipeline pass.

Field	Type	Required	Description
`to`	string	yes	Output format: png, jpg, jpeg, heic, svg, avif, webp, gif, pdf, docx, xlsx, pptx
`compress`	object	no	Target file size range (KB). Pipeline picks quality to land between min and max.
`compress.minKb`	number	if compress	Minimum output size in KB (≥ 0)
`compress.maxKb`	number	if compress	Maximum output size in KB (must be > minKb)
`resize`	object	no	Resize output. Requires at least `width` or `height`.
`resize.width`	number	no	Target width (positive, max 100000)
`resize.height`	number	no	Target height (positive, max 100000)
`resize.unit`	string	no	`px` (default) · `in` · `cm` · `mm`
`resize.fit`	string	no	`inside` (default) · `contain` · `cover` · `fill` · `outside`
`crop`	object	no	Crop before resize. All values are fractions 0–1 of the source image.
`crop.x` · `crop.y`	number	if crop	Top-left corner of crop region
`crop.w` · `crop.h`	number	if crop	Width and height of crop region
`dpi`	number	no	Output DPI (integer, 1–2400). Applies to formats that support density metadata.
`name`	string	no	Output base filename without extension (max 200 chars, sanitized server-side)
`pages`	string	no	PDF/DOCX/PPTX → image: page range e.g. `1-3,5` or `all`. Multiple pages → ZIP.
`stripMetadata`	boolean	no	Remove EXIF, GPS, camera info, ICC profile, etc. from output
`pdfPageSize`	string	no	Image → PDF only: `fit` (default) · `a4` · `letter`
`merge`	boolean	no	Batch only. `true` = one combined PDF/DOCX (default for those targets). `false` = ZIP.

Example

{
  "to": "webp",
  "compress": { "minKb": 50, "maxKb": 200 },
  "resize": { "width": 1200, "unit": "px", "fit": "inside" },
  "dpi": 300,
  "name": "hero",
  "stripMetadata": true
}

Limits

500 MB per file
50 files per batch (1 file = 1 task)
60 task-creating requests per minute
Monthly task pool per plan — poll & download are unlimited

Errors

Code	HTTP	Meaning
`invalid_api_key`	401	Bad or revoked key
`api_key_required`	403	Route requires Developer API key
`subscription_inactive`	403	No active API plan
`monthly_limit_reached`	429	Monthly task pool exhausted
`rate_limit_exceeded`	429	>60 create requests/min
`file_too_large`	413	Over 500 MB
`unsupported_conversion`	422	Invalid format pair
`invalid_ops`	400	Malformed or invalid ops JSON

Authentication

Request

Endpoints

Create a task

POST /v1/api/tasks

Request

Examples

Response · 200

Check status

GET /v1/api/tasks/:id

Request

Examples

Response

200 · processing

200 · done

200 · failed

Download

GET /v1/api/tasks/:id/download

Request

Examples

Response

200 · file

404 / 410

Batch

Examples · merged PDF

Examples · separate files (ZIP)

The ops object

Fields

Example

Limits

Errors

`POST /v1/api/tasks`

`GET /v1/api/tasks/:id`

`GET /v1/api/tasks/:id/download`

The `ops` object