ConvertAPI Python Client

2.0.0 · active · verified Thu Apr 16

The `convertapi` Python Client provides an interface to ConvertAPI's file conversion and manipulation services. It allows users to convert documents, images, videos, and more between various formats programmatically. The current version is 2.0.0, and the library is actively maintained with releases addressing features and breaking changes.

Common errors

```
convertapi.client.ConvertApiError: Unauthorized. Check your API secret.
```
cause The API secret is either missing, incorrect, or expired. The ConvertAPI service rejected the request.

fix Double-check your `convertapi.api_secret` value. Ensure it matches the secret found on your ConvertAPI dashboard (https://www.convertapi.com/a/dashboard). Make sure environment variable `CONVERTAPI_SECRET` is set if you are loading it from there.
```
AttributeError: module 'convertapi' has no attribute 'secret' (or 'api_key')
```
cause Attempting to set the API secret using an incorrect attribute name.

fix The correct attribute to set the API secret is `convertapi.api_secret`. Change `convertapi.secret = '...'` or `convertapi.api_key = '...'` to `convertapi.api_secret = '...'`.
```
convertapi.client.ConvertApiError: The 'File' parameter is required.
```
cause The input file for conversion was not provided in the `parameters` dictionary when calling `convertapi.convert()`.

fix Ensure that the `parameters` dictionary passed to `convertapi.convert()` includes a key named 'File' with the path, URL, or bytes of the file you intend to convert, e.g., `{'File': 'path/to/file.docx'}`.

Warnings

breaking Version 2.0.0 switches to using an 'Authorization' header for API authentication instead of query parameters. Older versions (pre-v2.0.0) might have implicitly or explicitly used query parameters.
Fix: Ensure your client library is updated to v2.0.0 or later. No explicit code change is usually required if you set `convertapi.api_secret`, as the library handles the header internally.
breaking Version 2.0.0 removes support for 'alternative converters'. If your application relied on specific, non-default conversion engines, those options are no longer available.
Fix: Review your conversion calls and remove any parameters that specified an 'alternative converter'. Test existing conversions thoroughly as the default converter might behave differently or lack certain features.
gotcha In v2.0.0, default upload and download timeouts were changed from a fixed value (e.g., 1800 seconds in v1.5.0) to `None`. This means operations will now effectively have no client-side timeout unless explicitly configured, potentially leading to processes hanging indefinitely for very long conversions or network issues.
Fix: For critical operations, consider explicitly setting timeouts. You can configure `convertapi.default_timeout` or pass `timeout` parameter to `convertapi.convert` for individual calls.
gotcha The `File` parameter in `convertapi.convert` can accept various types (local path string, URL string, or bytes-like object). Mismatching the format (e.g., providing a URL for a file expected locally) can lead to conversion errors.
Fix: Always ensure the value passed to the `File` parameter matches the expected input type for your specific conversion scenario. For local files, ensure the path is accessible; for URLs, ensure it's a valid and publicly accessible link.

Install

pip install convertapi Install stable version

Imports

convertapi
wrong:
```
from convertapi import ConvertApi
```
correct:
```
import convertapi
```
The primary interface is directly through the `convertapi` module, not a class named `ConvertApi`.

Quickstart

This quickstart demonstrates how to initialize the ConvertAPI client with your API secret and perform a simple file conversion from a URL. It converts a DOC file to PDF and saves the output locally. Error handling for API-specific and general exceptions is included.

import os
import convertapi

# Get your API secret from https://www.convertapi.com/a/dashboard
# It's highly recommended to use environment variables for secrets.
convertapi.api_secret = os.environ.get('CONVERTAPI_SECRET', 'YOUR_CONVERTAPI_SECRET')

try:
    # Example: Convert a Word document (DOC) to PDF
    # The 'File' parameter can be a local path, URL, or bytes.
    result = convertapi.convert('pdf', {
        'File': 'https://cdn.convertapi.com/example.doc' # Example URL
    }, from_format='doc')

    # Save the resulting files (e.g., to the current directory)
    result.save_files('./')
    print("Conversion successful! Files saved.")

except convertapi.client.ConvertApiError as e:
    print(f"Conversion failed: {e}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

view raw JSON →