Images in. Editable files out.

6. Convert in batches

Convert many images with one batch and download the results as one zip. Subscribers can batch on every paid plan: up to 10 files on the $19.90/month plan, 50 on the $49.90/month plan and 100 on the $99.90/month plan (with priority). Through an API key, batches need a plan with API batch access (150 and 333). An account that has credits but no subscription can batch on the website, up to 10 files. Accounts with neither a subscription nor credits, and API keys without batch access, get 403 plan_required (max 0). A batch uses a single output, svg or pptx. Keys need conversions:write to create, upload, start and cancel, and conversions:read to read.

Endpoints

• POST /v1/batchesDeclare the files and reserve credits. Needs Idempotency-Key.
• PUT /v1/batches/{id}/files/{idx}Upload one file as multipart field file.
• POST /v1/batches/{id}/startBegin conversion. Files not uploaded are released.
• POST /v1/batches/{id}/cancelStop waiting files; running files are charged only if delivered.
• GET /v1/batchesYour last 50 batches, newest first, under batches.
• GET /v1/batches/{id}State, counts, credits and per-file status.
• GET /v1/batches/{id}/archiveZip of every delivered file.

Flow

1. Create the batch, declaring each file’s name, size and type. Save the returned id and each item’s idx.
2. Upload each file to /files/{idx}.
3. Start the batch.
4. Poll GET /v1/batches/{id} every few seconds until finished_at is set, or wait for the batch.finished webhook.
5. Download the zip from /archive. For a single file, use GET /v1/conversions/{task_id} with the task_id from the batch.

curl https://unraster.ai/v1/batches \
  -H "Authorization: Bearer $UNRASTER_API_KEY" \
  -H "Idempotency-Key: $REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{"output":"svg","files":[
    {"name":"a.png","size":183204,"type":"image/png"},
    {"name":"b.jpg","size":96311,"type":"image/jpeg"}
  ]}'

A new batch returns HTTP 201 (200 if you repeat the same request with the same key).

{
  "id": "job_0b6f6c1e-5c1a-4a58-9d42-2f3f6e0a9a11",
  "state": "open",
  "item_limit": 50,
  "items": [
    { "idx": 0, "task_id": "cnv_example_0" },
    { "idx": 1, "task_id": "cnv_example_1" }
  ],
  "reserved_credits": 2
}

The rest of the flow:

BATCH=job_0b6f6c1e-5c1a-4a58-9d42-2f3f6e0a9a11

# Upload each file to its idx (PNG, JPEG or WebP)
curl -X PUT https://unraster.ai/v1/batches/$BATCH/files/0 \
  -H "Authorization: Bearer $UNRASTER_API_KEY" \
  -F "file=@a.png"
curl -X PUT https://unraster.ai/v1/batches/$BATCH/files/1 \
  -H "Authorization: Bearer $UNRASTER_API_KEY" \
  -F "file=@b.jpg"

# Start the batch; files not uploaded are released
curl -X POST https://unraster.ai/v1/batches/$BATCH/start \
  -H "Authorization: Bearer $UNRASTER_API_KEY"

# Poll until finished_at is set (after a cancel, files already converting still finish)
curl https://unraster.ai/v1/batches/$BATCH \
  -H "Authorization: Bearer $UNRASTER_API_KEY"

# Download every delivered file as one zip
curl -o results.zip https://unraster.ai/v1/batches/$BATCH/archive \
  -H "Authorization: Bearer $UNRASTER_API_KEY"

A batch has ended when finished_at is set. Its final state is completed (no file failed; files you never uploaded are simply not converted), partial, failed or cancelled. After a cancel the state reads cancelled at once, but files already converting still finish and are charged if delivered: wait for finished_at before reading charged_credits or downloading the archive. An open batch that you never start is closed after 24 hours and its credits are released.

{
  "id": "job_0b6f6c1e-5c1a-4a58-9d42-2f3f6e0a9a11",
  "output": "svg",
  "state": "partial",
  "counts": { "done": 1, "failed": 1, "running": 0, "waiting": 0, "cancelled": 0 },
  "charged_credits": 1,
  "reserved_credits": 0,
  "items": [
    { "idx": 0, "file_name": "a.png", "state": "done",
      "task_id": "cnv_example_0", "error_code": null, "credits": 1 },
    { "idx": 1, "file_name": "b.jpg", "state": "failed",
      "task_id": "cnv_example_1", "error_code": "conversion_failed", "credits": 0 }
  ],
  "item_count": 2,
  "created_at": "2026-11-08T10:00:00.000Z",
  "started_at": "2026-11-08T10:00:20.000Z",
  "finished_at": "2026-11-08T10:01:05.000Z"
}

Credits

Creating a batch reserves credits for every file at once. A subscriber pays 1 credit per SVG and 2 credits per PowerPoint; a credit-pack batch pays one credit more per file (2 per SVG, 3 per PowerPoint). If your balance does not cover the whole batch, the request returns 402 insufficient_credits and nothing is reserved. Only delivered files are charged. Failed, cancelled and never-uploaded files are released, not charged. Progress checks and downloads are free.

Limits

• Files: PNG, JPEG or WebP, up to 20 MiB each.
• Files per batch: 10 on the $19.90/month plan, 50 on the $49.90/month plan, 100 on the $99.90/month plan. Credit-pack accounts: 10 files per batch, on the website only.
• Idempotency-Key is required when creating a batch. Retry a lost response with the same key.
• Uploads: 240 per minute per account.
• Delivered files are kept for seven days. After that, /archive returns 410 batch_expired. While the batch is still running it returns 409 batch_not_finished; if nothing was delivered it returns 404.

The zip

Each delivered file is named {idx}-{original name}.svg (or .pptx), with duplicate names made unique. Files that were not delivered are not included.

The batch.finished webhook

Once a batch reaches a final state, your enabled webhook endpoints receive batch.finished. It is sent once per batch, for batches created through the API. Signing, headers and retries work as in the previous section. The body has counts and charged credits but no download links; fetch the batch or the archive for those. Every file also sends its usual conversion.* event. Events may arrive in any order, so deduplicate by id. A batch that is cancelled or expires before any file starts sends no event.

{
  "id": "evt_job_0b6f6c1e-5c1a-4a58-9d42-2f3f6e0a9a11_finished",
  "type": "batch.finished",
  "created_at": "2026-11-08T10:01:05.000Z",
  "data": {
    "id": "job_0b6f6c1e-5c1a-4a58-9d42-2f3f6e0a9a11",
    "state": "partial",
    "output": "svg",
    "counts": { "done": 1, "failed": 1, "running": 0, "waiting": 0, "cancelled": 0 },
    "charged_credits": 1
  }
}

Handle errors

Errors use {"error": {"code": "…", "message": "…"}}. Branch on error.code.

• 400 / 413 / 415: correct the request, file size, or format.
• 401 / 403: check your key and permissions.
• 402: insufficient available credits.
• 404: the task or file is unavailable to this account.
• 409: check for an idempotency conflict.
• 429: respect Retry-After before retrying.
• 503: retry later, preserving the original idempotency key.

Batch requests add these codes: