{"id":8898,"library":"cloudconvert","title":"CloudConvert Python SDK","description":"The `cloudconvert` library is the official Python SDK for the CloudConvert API v2, providing a convenient wrapper to convert, optimize, and manipulate various file formats programmatically. As of version 2.1.0, it supports features like Signed URLs and improved synchronous API endpoints for job and task waiting. The library is under active development, with major releases often coinciding with updates to the underlying CloudConvert API.","status":"active","version":"2.1.0","language":"en","source_language":"en","source_url":"https://github.com/cloudconvert/cloudconvert-python","tags":["api-wrapper","file-conversion","cloudconvert","sdk"],"install":[{"cmd":"pip install cloudconvert","lang":"bash","label":"Install latest stable version"}],"dependencies":[],"imports":[{"symbol":"cloudconvert","correct":"import cloudconvert"},{"note":"Job and Task classes are attributes of the top-level `cloudconvert` module after configuration.","wrong":"from cloudconvert import Job","symbol":"Job","correct":"import cloudconvert\ncloudconvert.Job.create(...)"},{"note":"Job and Task classes are attributes of the top-level `cloudconvert` module after configuration.","wrong":"from cloudconvert import Task","symbol":"Task","correct":"import cloudconvert\ncloudconvert.Task.wait(...)"}],"quickstart":{"code":"import cloudconvert\nimport os\n\n# Configure CloudConvert with your API key from environment variable\n# Get your API key at https://cloudconvert.com/dashboard/api/v2/keys\nCLOUDCONVERT_API_KEY = os.environ.get('CLOUDCONVERT_API_KEY', 'YOUR_API_KEY')\n\nif CLOUDCONVERT_API_KEY == 'YOUR_API_KEY' or not CLOUDCONVERT_API_KEY:\n    print(\"Warning: CLOUDCONVERT_API_KEY not set. Using a placeholder. Set the environment variable or replace 'YOUR_API_KEY'.\")\n    # For demonstration, proceed with placeholder; in production, exit or raise error.\n    # For actual usage, ensure a valid API key is present.\n\ncloudconvert.configure(api_key=CLOUDCONVERT_API_KEY, sandbox=False)\n\ntry:\n    # Create a job to convert a URL to PDF\n    job = cloudconvert.Job.create(payload={\n        \"tasks\": {\n            'import-from-url': {\n                'operation': 'import/url',\n                'url': 'https://www.example.com/sample.html'\n            },\n            'convert-to-pdf': {\n                'operation': 'convert',\n                'input': ['import-from-url'],\n                'output_format': 'pdf'\n            },\n            'export-to-url': {\n                'operation': 'export/url',\n                'input': ['convert-to-pdf']\n            }\n        }\n    })\n\n    # Wait for the job to complete\n    job = cloudconvert.Job.wait(id=job['id'])\n\n    # Download the output file\n    for task in job[\"tasks\"]:\n        if task.get(\"name\") == \"export-to-url\" and task.get(\"status\") == \"finished\":\n            export_task = task\n            # Assuming a single file is exported for simplicity\n            file = export_task[\"result\"][\"files\"][0]\n            \n            # Create a 'downloads' directory if it doesn't exist\n            os.makedirs('downloads', exist_ok=True)\n            \n            # Download the file to the 'downloads' directory\n            download_path = os.path.join('downloads', file['filename'])\n            cloudconvert.download(filename=download_path, url=file['url'])\n            print(f\"Successfully converted and downloaded to: {download_path}\")\n            break\n\nexcept cloudconvert.exceptions.CloudConvertClientError as e:\n    print(f\"CloudConvert API Error: {e.message}\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\n","lang":"python","description":"This quickstart example demonstrates how to configure the CloudConvert SDK, create a job to convert a file from a URL to PDF, wait for the conversion to complete, and then download the resulting PDF. It uses an environment variable for the API key for secure handling."},"warnings":[{"fix":"Migrate your code to use CloudConvert API v2 logic and endpoints. Refer to the official API v2 documentation and SDK examples.","message":"CloudConvert API v1 reached End of Life (EOL) on January 1, 2022. All existing integrations using API v1 must be migrated to API v2. The API v2 has a completely different design and requires significant code changes.","severity":"breaking","affected_versions":"< 2.0.0"},{"fix":"When waiting for a specific task within a job, ensure you extract the `id` of the *task* you want to wait for. For example, `task_id = job['tasks'][0]['id']` or iterate through `job['tasks']` to find the relevant task ID. To wait for a full job, use `cloudconvert.Job.wait(id=job['id'])`.","message":"Incorrectly attempting to wait for a job using `cloudconvert.Task.wait(id=job['id'])` will result in a `KeyError: 'id'` if `job` is the full job object. The `wait` methods expect a task ID, not a job ID directly.","severity":"gotcha","affected_versions":"2.0.0+"},{"fix":"Always construct your `payload` with `{'tasks': {...}}` where `...` defines your import, convert, and export tasks. Consult the CloudConvert API v2 documentation's Job Builder for correct payload structures.","message":"The `cloudconvert.Job.create()` method requires a `payload` dictionary with a specific structure, including a top-level `\"tasks\"` key containing task definitions. Missing or incorrectly structuring this payload will lead to errors like `KeyError: 'tasks'` or invalid job creation.","severity":"gotcha","affected_versions":"2.0.0+"},{"fix":"If encountering `INPUT_TASK_FAILED` errors for files with spaces, try renaming files to use hyphens or underscores instead of spaces as a workaround, or ensure that file paths are properly URL-encoded if constructing URLs manually.","message":"Although the SDK is designed to handle filenames with spaces, some users have reported `ERROR INPUT_TASK_FAILED` when uploading files with spaces in their names. This can be an elusive issue.","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":"Ensure the `payload` argument to `cloudconvert.Job.create()` is correctly formatted, always including a top-level `'tasks'` key. If iterating a job response, ensure the job has been properly fetched and contains the 'tasks' key.","cause":"Attempting to access `job['tasks']` from a job object created with an incorrect payload structure or a malformed API response.","error":"KeyError: 'tasks'"},{"fix":"The `Task.wait()` method expects the ID of a specific task. If you have a job object, extract the relevant task's ID (e.g., `task_id = job['tasks'][0]['id']`) before passing it to `Task.wait()`. For waiting on the entire job, use `cloudconvert.Job.wait(id=job['id'])`.","cause":"Attempting to call `cloudconvert.Task.wait()` with a job ID instead of a task ID.","error":"KeyError: 'id' (when calling Task.wait)"},{"fix":"Verify your API key on the CloudConvert dashboard and ensure it's correctly passed to `cloudconvert.configure(api_key='YOUR_API_KEY')` or set as the `CLOUDCONVERT_API_KEY` environment variable for `cloudconvert.default()`.","cause":"The API key provided is invalid, expired, or not set. This can also happen if the `CLOUDCONVERT_API_KEY` environment variable is not set and `cloudconvert.configure()` is not called explicitly.","error":"CloudConvertClientError: Invalid API Key or missing API Key"},{"fix":"Check the specific error message for details. For V1 error codes, ensure you have fully migrated to API v2. Verify the input file path, format, and size. Increase conversion timeout if possible or simplify the conversion.","cause":"These generic 'Unable to convert' errors, especially with V1 error codes, often indicate issues with the input file, exceeding conversion time limits, or attempting to use a deprecated API v1 feature.","error":"CloudConvertClientError: Unable to convert (various error codes like 86, 87, 88, 91)"}]}