Migrate from CloudConvert

This guide maps every piece of a typical CloudConvert integration onto its Converterer equivalent. It comes from a real port: we helped migrate Breeze, a photo-booth software product, from CloudConvert to Converterer, and this is the mapping we used.

Most of the features that make this port straightforward (URL input, the webhooks API, signed deliveries, metadata) shipped in the July 2026 release.

The headline difference: CloudConvert models a conversion as a job containing a chain of tasks (import, convert, export) that you assemble per request. Converterer models it as a single conversion task against a pre-configured destination. Most integrations get shorter when they move.

Concept map

CloudConvert	Converterer
Job with tasks object (import/* → convert → export/*)	One POST /convert request
Authorization: Bearer <token> with scopes	HTTP Basic: API key as username, blank password
import/upload (two-step signed form upload)	Multipart input field on the same request
import/url task (url, filename)	Pass the URL as the input value
export/url task (temporary hosted URL)	Default destination: built-in storage, fetchable URL, 7-day retention
export/s3, export/azure/blob, export/google-cloud-storage task per job	Your own bucket as the destination, configured once; every task delivers to it
Job tag string	metadata object (up to 50 keys, 4 KB)
Statuses: waiting, processing, finished, error	queued, started, delivered, creation_failed, delivery_failed (+ done boolean)
Webhooks: POST /v2/webhooks, events job.created / job.finished / job.failed	POST /webhooks; fires on terminal states only
CloudConvert-Signature (HMAC-SHA256 of body)	Converterer-Signature: t=<ts>,v1=<hmac> (HMAC-SHA256 of timestamp.body)
Credits per conversion minute (2 to 4 base credits for office/PDF work)	Flat: one conversion, one unit of your plan
Sandbox environment	Free tier (100 conversions/month)

Authentication

CloudConvert uses a Bearer token with scopes. Converterer uses HTTP Basic auth with the API key as the username and an empty password:

# CloudConvert
curl -H "Authorization: Bearer $CLOUDCONVERT_API_KEY" ...

# Converterer
curl -u "$CONVERTERER_API_KEY:" ...

One thing to know before you start: your API key is bound to a destination (where output lands). You do not need to bring your own bucket: every account starts with a built-in default destination, Converterer-managed storage that hosts each output file at a fetchable URL for 7 days. That maps directly onto CloudConvert’s export/url pattern: a temporary hosted URL you download the result from, except the window is 7 days rather than hours. Connect your own S3/B2/GCS/Azure bucket whenever you need durable storage; either way, per-request export configuration disappears from your code entirely.

Converting an uploaded file

On CloudConvert, converting a local file means creating a job with three tasks, then performing the signed-form upload as a second request:

# CloudConvert: create the job...
curl -X POST https://api.cloudconvert.com/v2/jobs \
  -H "Authorization: Bearer $CLOUDCONVERT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tasks": {
      "upload-file": { "operation": "import/upload" },
      "convert-file": {
        "operation": "convert",
        "input": "upload-file",
        "output_format": "pdf"
      },
      "export-file": { "operation": "export/url", "input": "convert-file" }
    }
  }'
# ...then POST the file to the signed form URL from the response.

On Converterer the upload and the conversion are the same request, and there is no export step because the destination is already configured:

# Converterer
curl -u "$CONVERTERER_API_KEY:" \
  https://api.converterer.com/convert \
  -F input=@report.docx \
  -F output_format=pdf
# → {"id":"9f1a8e7c-…", "status":"queued"}

Conversion options move from the convert task’s fields into the options[...] namespace; the options reference lists them per pipeline.

Converting from a URL

CloudConvert’s import/url task becomes the input field itself. If the value is a URL, Converterer fetches it server-side:

# CloudConvert: import/url task + convert + export in a job body

# Converterer
curl -u "$CONVERTERER_API_KEY:" \
  https://api.converterer.com/convert \
  -F "input=https://example.com/reports/q2.docx" \
  -F "output_format=pdf"

The fetch follows up to 5 redirects, refuses private addresses, and accepts files up to 1 GB. Failures surface as url_blocked, url_too_large, or url_unreachable error codes.

A note if you only used import/url because CloudConvert’s upload flow was a two-step process: you do not need a URL at all here. Uploading is a single multipart request (see above), so if the file is private or you would rather not expose a link, just send the file itself in the same input field. There is no equivalent of import/base64 or import/raw; write the content to a file and upload it, or serve it from a URL.

Statuses and polling

CloudConvert	Converterer	Meaning
waiting	queued	Accepted, not yet processing
processing	started	In progress
finished	delivered	Done and uploaded to your storage
error	creation_failed or delivery_failed	Converterer splits processing failures from upload failures

Poll GET /convert/{id} and check the done boolean, or skip polling and use webhooks. Note that Converterer has no synchronous endpoint (CloudConvert’s sync.api.cloudconvert.com); every task is async, so port any synchronous call sites to webhooks or a short poll loop.

Webhooks

Both platforms deliver a signed POST. The differences worth knowing:

1. Events. CloudConvert fires job.created, job.finished, and job.failed. Converterer fires only on terminal states (delivered and the two failure states); there is no created event, and in-progress transitions never fire.
2. Registration. Same idea, simpler shape:

# CloudConvert
curl -X POST https://api.cloudconvert.com/v2/webhooks \
  -H "Authorization: Bearer $CLOUDCONVERT_API_KEY" \
  -d '{"url": "https://example.com/hooks", "events": ["job.finished", "job.failed"]}'

# Converterer
curl -u "$CONVERTERER_API_KEY:" \
  https://api.converterer.com/webhooks \
  -d "url=https://example.com/hooks"

The response includes the signing_secret. There is no per-job webhook_url parameter; subscriptions are per destination.

3. Signature verification. CloudConvert signs the raw body: HMAC-SHA256(body, secret) in the CloudConvert-Signature header. Converterer signs a timestamped string: the Converterer-Signature header carries t=<unix>,v1=<hex> where v1 = HMAC-SHA256("{t}.{body}", secret). The timestamp lets you reject replayed deliveries, so port your verification rather than reusing it:

// CloudConvert verification
const expected = createHmac('sha256', secret).update(rawBody).digest('hex');
return expected === header;

// Converterer verification
const parts = Object.fromEntries(header.split(',').map((kv) => kv.split('=')));
const expected = createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex');
return timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));

Full snippets in Node, Python, and PHP are in the webhooks docs.

4. Payload. CloudConvert sends the whole job with nested tasks and result file URLs. Converterer sends the flat task shape: id, status, done, file_name, your metadata, and a url when the destination has a public base URL. If your handler currently digs the output URL out of the export task’s result, read url (or construct the path from file_name) instead.

Output delivery

CloudConvert integrations usually end with an export/url task (temporary URL) or an export/s3-style task carrying bucket credentials on every job. Converterer inverts this: you connect your bucket (S3, B2, GCS, Azure Blob, and others) to a destination once, and every conversion delivers into it. For the export/url pattern, set public_base_url on the destination and each delivered task carries a ready-made url.

Files in the default destination are purged after 7 days; connect your own bucket for anything durable.

Job tags become metadata

If you used CloudConvert’s tag to correlate jobs with rows in your database, use metadata instead. It is richer: up to 50 key-value pairs (4 KB total) rather than one string, and it comes back on every fetch and webhook:

-F "metadata[order_id]=ord_8817" \
-F "metadata[tenant]=breeze-prod"

Billing translation

CloudConvert meters conversion minutes: a credit per started minute, with office and PDF conversions costing 2 to 4 base credits, so costs vary with file size and type. Converterer is flat: every conversion counts once regardless of duration or format, and every file up to 1 GB counts the same. The practical effect is that video-heavy and office-heavy workloads become predictable; the pricing comparison has worked examples at 1k/10k/50k conversions per month.

What Converterer does not have

Ported honestly, these CloudConvert features have no direct equivalent:

• A sandbox environment. Use the free tier (100 conversions/month, no card) as your test environment; it is the same production API.
• The long-tail format catalogue. CloudConvert covers 200+ formats including audio, ebooks, and archives. Converterer covers 300+ pairs across documents, images, and video; audio and SVG are on the roadmap. Check the format matrix against your traffic before you commit.
• import/base64 / import/raw, per-job webhook_url, and the synchronous endpoint, as noted above.
• Merge/archive/OCR task types. Converterer converts files; it does not merge PDFs or build archives.

Migration checklist

1. Create a Converterer account, connect your bucket as a destination, and note the API key.
2. Set public_base_url on the destination if your code expects a fetchable output URL.
3. Swap auth: Bearer header → HTTP Basic with the key as username.
4. Collapse each job’s task chain into one POST /convert; move convert-task fields into options[...].
5. Replace import/url tasks with a URL in input; replace upload flows with a multipart input.
6. Move tag values into metadata.
7. Re-register webhooks via POST /webhooks, store the new signing secret, and port signature verification to the timestamped scheme.
8. Update status handling: finished → delivered (or just check done), error → both _failed states.
9. Run your real traffic against the free tier, compare outputs, then switch production keys.