What's the difference between a package and a utility?

Packages (wall art, poster, clipart) bundle every deliverable a POD seller needs — print files, mockups, listing video, and Etsy PDF — into a single flat or bin-formula price. One call returns a complete listing kit. Utilities (upscale, mockup, listing video, listing PDF, DPI stamp) are charged per use and meant for one-off operations outside a package. Most automations should call a package endpoint.

Do I have to ask for the mockups, video, and PDF separately?

No. When you call POST /v1/batch/wallart or /v1/batch/poster, the bundled deliverables are included at the package price. Mockups need a userSetId (your saved mockup template set). The listing video and Etsy PDF are generated by default when you submit a job.

How do I check live pricing from my code?

GET /v1/pricing/costs returns three useful blocks: a flat costs map (every pricing key → credits), a structured packages block with each package's credits and what's included, and a utilities map for à la carte operations. No auth required.

Is the API free to use?

The API uses the same credit system as the dashboard. You get free credits when you create an account and verify your email. After that, purchase credit packs or subscribe to keep processing.

What are the rate limits?

There is no hard rate limit on API calls. Concurrency is managed by the job queue — if the queue is full, requests return a 429 status. For most workflows this is never an issue.

How long are results available?

Batch ZIP downloads are stored for 24 hours via the dashboard or 1 hour for API-key-initiated jobs. Individual job results are available for approximately 30 minutes after completion. Fetch results promptly in your automation workflow.

There is no official SDK yet. The API is standard REST with JSON request/response, so it works out of the box with any HTTP library in any language — fetch, axios, requests, curl, and more.

Where are the full API docs?

The complete API reference with all endpoints, parameters, error codes, and Make.com recipes is available in your dashboard at /app/docs. Create a free account to access it.

REST API

Automate your image processing workflow

Process images programmatically with a simple REST API. Integrates with Make.com, n8n, and any HTTP client.

Full Processing Suite

Clipart, wall art, poster, mockup, upscale, and DPI conversion — single image or batch, all via REST.

URL or File Upload

Submit images by direct URL (ideal for automation) or multipart file upload.

Async Job Polling

Long-running jobs return a job ID. Poll for status, download results when ready.

API Key Auth

Simple Bearer token authentication. Generate your key from your dashboard profile.

Batch Processing

Process up to 50 images per batch. ZIP download, individual file access, and automatic retry for failed images.

Webhook-friendly

Designed for no-code automation tools. Standard JSON request/response format.

Quick example

Request

# Wall Art package — 1 call, complete listing kit
curl -X POST https://api.ratioready.com/v1/batch/wallart \
  -H "Authorization: Bearer pk_your_api_key" \
  -F "images=@artwork.png" \
  -F 'payload={
    "userSetId": "ums_abc12345"
  }'

# 59 credits per image → includes:
#   • 5 ratio crops at 300 DPI (2:3, 3:4, 4:5, 11:14, A1)
#   • Bundled mockups
#   • Listing video
#   • Etsy listing PDF

Response

{
  "batchId": "batch-xyz-789",
  "status": "processing",
  "total": 1,
  "completed": 0,
  "failed": 0
}

// Poll GET /v1/batch/batch-xyz-789 →
{
  "status": "completed",
  "total": 1,
  "completed": 1,
  "downloadUrl": "/v1/batch/batch-xyz-789/download"
}

Packages vs Utilities

The API is organised around two pricing concepts. Most automations should call a package endpoint — utilities are reserved for one-off operations.

Packages — primary product

One call → complete listing kit

Print files, mockups, listing video, and Etsy PDF are all bundled into a single price.

POST /v1/batch/wallart — 59 cr / image
POST /v1/batch/poster — 55 cr / image
POST /v1/batch/clipart — bin formula (29 + 10·bin for JPG, +12 flat for PNG transparent)

Utilities — à la carte

Charged per use, for one-off ops

Reach for these only when you don't need the full package.

Upscale to 2K / 4K / 8K / 10K — 5 / 10 / 18 / 30 cr
Standalone mockup — 5 cr · listing video — 10 cr · listing PDF — 10 cr
Background removal — 3 cr · 300 DPI stamp — 1 cr

Always fetch live pricing at runtime: GET /v1/pricing/costs returns structured packages and utilities blocks.

Endpoint reference

Packages — the primary product

One call → complete listing kit. Use these for almost every automation.

Method	Endpoint	Description	Auth
POST	`/v1/batch/wallart`	Wall art package — 5 ratios + mockups + video + PDF (59 cr / image)	Bearer
POST	`/v1/batch/poster`	Poster package — 1 print + mockups + video + PDF (55 cr / image)	Bearer
POST	`/v1/batch/clipart`	Clipart batch package — 1-50 images, prints + previews + PDF (bin formula)	Bearer

Job lifecycle — polling & downloads

Track and retrieve results from any package job.

Method	Endpoint	Description	Auth
GET	`/v1/batch/:id`	Poll batch progress (every 2-3s until terminal)	Bearer
GET	`/v1/batch/:id/download`	Master ZIP (presigned R2 redirect)	Bearer
GET	`/v1/batch/:id/file`	Individual file by type (print \| preview \| mockup \| video \| listing)	Bearer
GET	`/v1/batch/:id/image/:idx/zip`	Per-image ZIP bundle	Bearer
POST	`/v1/batch/:id/retry`	Retry failed images (max 3 attempts)	Bearer

Standalone utilities — à la carte

Charged per use. Reach for these only when you do not need a full package.

Method	Endpoint	Description	Auth
POST	`/v1/batch/upscale`	AI upscale 1-50 images (2K / 4K / 8K / 10K)	Bearer
POST	`/v1/mockup`	Standalone mockup generation	Bearer
POST	`/v1/dpi`	300 DPI metadata stamp	Bearer

Account & pricing

Read-only endpoints for account info and live pricing.

Method	Endpoint	Description	Auth
GET	`/v1/me`	Account info & current credit balance	Bearer
GET	`/v1/me/history`	Recent processing history	Bearer
GET	`/v1/pricing/costs`	Live pricing — packages, utilities, costs map	Public
GET	`/v1/pricing/packs`	Available credit packs	Public
GET	`/v1/pricing/plans`	Available subscription plans	Public
GET	`/v1/health`	Server health check	Public

Legacy individual-file endpoints (/files/print/:i, /wallart/:ratio, /poster, /mockup/:i) are still supported for backward compatibility but new integrations should use /v1/batch/:id/file?type=….

Works with your tools

Make.com

Use the HTTP module to call any endpoint. Submit images by URL, poll for results, and route outputs to your next automation step.

n8n

Build workflows with the HTTP Request node. Chain image processing with listing creation on Etsy, Amazon, or Shopify.

Any HTTP client

Standard REST API with JSON responses. Works with curl, Python requests, Node.js fetch, or any language and framework.

Authentication

1 Create an account at ratioready.com/register
2 Go to your Profile page and generate an API key (starts with pk_)
3 Include it as a Bearer token: Authorization: Bearer pk_your_key