{"id":8034,"library":"convertapi","title":"ConvertAPI Python Client","description":"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.","status":"active","version":"2.0.0","language":"en","source_language":"en","source_url":"https://github.com/ConvertAPI/convertapi-python","tags":["file-conversion","document-processing","pdf","image-processing","api-client"],"install":[{"cmd":"pip install convertapi","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Used for making HTTP requests to the ConvertAPI service.","package":"requests","optional":false},{"reason":"HTTP client library, a dependency of requests.","package":"urllib3","optional":false}],"imports":[{"note":"The primary interface is directly through the `convertapi` module, not a class named `ConvertApi`.","wrong":"from convertapi import ConvertApi","symbol":"convertapi","correct":"import convertapi"}],"quickstart":{"code":"import os\nimport convertapi\n\n# Get your API secret from https://www.convertapi.com/a/dashboard\n# It's highly recommended to use environment variables for secrets.\nconvertapi.api_secret = os.environ.get('CONVERTAPI_SECRET', 'YOUR_CONVERTAPI_SECRET')\n\ntry:\n    # Example: Convert a Word document (DOC) to PDF\n    # The 'File' parameter can be a local path, URL, or bytes.\n    result = convertapi.convert('pdf', {\n        'File': 'https://cdn.convertapi.com/example.doc' # Example URL\n    }, from_format='doc')\n\n    # Save the resulting files (e.g., to the current directory)\n    result.save_files('./')\n    print(\"Conversion successful! Files saved.\")\n\nexcept convertapi.client.ConvertApiError as e:\n    print(f\"Conversion failed: {e}\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"< 2.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":"< 2.0.0"},{"fix":"For critical operations, consider explicitly setting timeouts. You can configure `convertapi.default_timeout` or pass `timeout` parameter to `convertapi.convert` for individual calls.","message":"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.","severity":"gotcha","affected_versions":">= 2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"The API secret is either missing, incorrect, or expired. The ConvertAPI service rejected the request.","error":"convertapi.client.ConvertApiError: Unauthorized. Check your API secret."},{"fix":"The correct attribute to set the API secret is `convertapi.api_secret`. Change `convertapi.secret = '...'` or `convertapi.api_key = '...'` to `convertapi.api_secret = '...'`.","cause":"Attempting to set the API secret using an incorrect attribute name.","error":"AttributeError: module 'convertapi' has no attribute 'secret' (or 'api_key')"},{"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'}`.","cause":"The input file for conversion was not provided in the `parameters` dictionary when calling `convertapi.convert()`.","error":"convertapi.client.ConvertApiError: The 'File' parameter is required."}]}