Migrate from ConvertAPI to ChangeThisFile

ConvertAPI is a document and file conversion service with a large format catalog and a credit-based billing model. It's well-documented and has official SDKs. The credits system works fine until you hit its edges: credits vary by conversion type (a PDF-to-DOCX costs more credits than a JPG-to-PNG), making costs hard to predict, and monthly credit allocations don't always align with usage patterns.

ChangeThisFile charges one conversion = one unit regardless of the format pair. If predictable billing and a simpler API call are your priorities, this guide walks through the migration.

Why people migrate from ConvertAPI

Variable credit costs by conversion type. ConvertAPI assigns different credit costs to different conversions — converting a PDF to DOCX costs more credits than converting JPG to PNG. This means the same number of "conversions" costs different amounts depending on the mix of formats in your pipeline. Budget forecasting is harder than it should be.

Credits expire. Unused monthly credits reset — they don't roll over. Bursty workloads (high one month, low the next) lose credits they've paid for.

Secret key in query parameters. ConvertAPI authenticates via a Secret= query parameter appended to URLs. This pattern leaks secrets into server logs, URL history, and browser history. Bearer token in an Authorization header is the standard for a reason.

SDK dependency for complex workflows. ConvertAPI has official SDKs for most languages. They're convenient but add maintenance overhead. ChangeThisFile works with any HTTP client without any package.

Who should stay on ConvertAPI: If you need ConvertAPI's chaining feature (chain multiple conversions in a single request), its HTML-to-PDF engine with CSS rendering, or any format it covers that falls outside ChangeThisFile's catalog. ConvertAPI's HTML renderer handles complex CSS well, which is relevant for report generation.

Cost comparison

Note: ConvertAPI costs vary significantly by conversion type (PDF operations cost more credits than image operations). Estimates above assume a mixed workload. PDF-heavy workflows trend toward the higher end.

API endpoint mapping

Code migration: BEFORE and AFTER

# BEFORE: ConvertAPI (secret in URL, JSON response with download URL)
import requests

CONVERTAPI_SECRET = 'your_convertapi_secret'

# Step 1: Submit conversion (secret in query param)
with open('report.docx', 'rb') as f:
    resp = requests.post(
        f'https://v2.convertapi.com/convert/docx/to/pdf?Secret={CONVERTAPI_SECRET}',
        files={'File': ('report.docx', f, 'application/vnd.openxmlformats-officedocument.wordprocessingml.document')}
    )
result = resp.json()

# Step 2: Download from response URL
file_url = result['Files'][0]['Url']
file_data = requests.get(file_url).content
with open('report.pdf', 'wb') as f:
    f.write(file_data)

# AFTER: ChangeThisFile (Bearer token, file in response body)
import requests

response = requests.post(
    'https://changethisfile.com/v1/convert',
    headers={'Authorization': 'Bearer ctf_sk_your_key'},
    files={'file': open('report.docx', 'rb')},
    data={'target': 'pdf'}
)
with open('report.pdf', 'wb') as f:
    f.write(response.content)

Key changes: secret moves from query parameter to Authorization header, and the download URL step is eliminated (file comes back in the same response).

Auth and token migration

1. Get your CTF key: Visit changethisfile.com/v1/keys/free. Free, no card. Format: ctf_sk_....
2. Move auth out of the URL: ConvertAPI puts the secret in the query string (?Secret=...). ChangeThisFile uses an Authorization header: Authorization: Bearer ctf_sk_your_key. This keeps your secret out of server access logs and browser history.
3. Remove the SDK: If you use convertapi-python, convertapi-php, or another ConvertAPI SDK, uninstall it. ChangeThisFile requires no package.
4. Update env vars: Rename CONVERTAPI_SECRET to CTF_API_KEY.
5. Audit your URL history: ConvertAPI secrets in query parameters often end up in server logs. Consider rotating your ConvertAPI secret before cancelling, if logs are accessible to others.

Rollback plan

ConvertAPI credits don't expire mid-month, so your remaining credits are usable for rollback testing:

1. Abstract your conversion calls behind a function. During migration, route based on an env variable: CONVERTER=ctf or CONVERTER=convertapi.
2. ConvertAPI returns detailed error codes when a conversion fails. ChangeThisFile returns HTTP 4xx with a JSON body. Map these during parallel-run period.
3. If ChangeThisFile returns HTTP 400 (unsupported format), log the format pair and route back to ConvertAPI for that specific case.
4. After 30 days, cancel your ConvertAPI subscription before the next billing cycle.

Common migration questions

ConvertAPI supports HTML-to-PDF with full CSS rendering. Does ChangeThisFile match this?
ChangeThisFile converts HTML to PDF via LibreOffice, which handles basic CSS and layout. ConvertAPI's HTML→PDF engine (Chromium-based) handles complex CSS, JavaScript, and print media queries better. If CSS fidelity in PDF output matters, test both with your actual HTML templates before switching that route.

Does ChangeThisFile support ConvertAPI's chaining feature?
No — ChangeThisFile doesn't chain conversions in a single call. For chained workflows (e.g., DOCX→PDF→JPEG), make sequential CTF calls, writing the intermediate file to a temp buffer between calls.

What happens to my remaining ConvertAPI credits?
Credits expire at your billing cycle. Use them up during the parallel-run period to avoid wasting paid credits. Don't renew once you've confirmed ChangeThisFile works for your pipeline.

Does ChangeThisFile have a ConvertAPI-compatible API?
No — the API shape is different. The migration requires code changes. The BEFORE/AFTER above shows the full scope of changes per call.

The migration mostly removes code — the SDK import, the download URL fetch, and the secret-in-query-parameter pattern all go away. Auth becomes a standard Bearer header. Get your free API key and compare outputs for your most important format pair before committing.