cloudconvert

library2.1.0pypypi✓ verified 86d ago

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.

devops serialization http-networking

pip install cloudconvert

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CLOUDCONVERT

cloudconvert

devopspythonv2.1.0

Install

2.3s avg

Import

622ms

Disk

19MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.1.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.915 runs

installs and imports cleanly · install 0.0s · import 0.661s · 21.4MB

glibc

py 3.10–3.915 runs

installs and imports cleanly · install 2.3s · import 0.582s · 22MB

19MB installed

● package 19MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

cloudconvert

✓ import cloudconvert

Job

✓ import cloudconvert cloudconvert.Job.create(...)

✗ from cloudconvert import Job

Job and Task classes are attributes of the top-level `cloudconvert` module after configuration.

Task

✓ import cloudconvert cloudconvert.Task.wait(...)

✗ from cloudconvert import Task

Job and Task classes are attributes of the top-level `cloudconvert` module after configuration.

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.

import cloudconvert import os # Configure CloudConvert with your API key from environment variable # Get your API key at https://cloudconvert.com/dashboard/api/v2/keys CLOUDCONVERT_API_KEY = os.environ.get('CLOUDCONVERT_API_KEY', 'YOUR_API_KEY') if CLOUDCONVERT_API_KEY == 'YOUR_API_KEY' or not CLOUDCONVERT_API_KEY: print("Warning: CLOUDCONVERT_API_KEY not set. Using a placeholder. Set the environment variable or replace 'YOUR_API_KEY'.") # For demonstration, proceed with placeholder; in production, exit or raise error. # For actual usage, ensure a valid API key is present. cloudconvert.configure(api_key=CLOUDCONVERT_API_KEY, sandbox=False) try: # Create a job to convert a URL to PDF job = cloudconvert.Job.create(payload={ "tasks": { 'import-from-url': { 'operation': 'import/url', 'url': 'https://www.example.com/sample.html' }, 'convert-to-pdf': { 'operation': 'convert', 'input': ['import-from-url'], 'output_format': 'pdf' }, 'export-to-url': { 'operation': 'export/url', 'input': ['convert-to-pdf'] } } }) # Wait for the job to complete job = cloudconvert.Job.wait(id=job['id']) # Download the output file for task in job["tasks"]: if task.get("name") == "export-to-url" and task.get("status") == "finished": export_task = task # Assuming a single file is exported for simplicity file = export_task["result"]["files"][0] # Create a 'downloads' directory if it doesn't exist os.makedirs('downloads', exist_ok=True) # Download the file to the 'downloads' directory download_path = os.path.join('downloads', file['filename']) cloudconvert.download(filename=download_path, url=file['url']) print(f"Successfully converted and downloaded to: {download_path}") break except cloudconvert.exceptions.CloudConvertClientError as e: print(f"CloudConvert API Error: {e.message}") except Exception as e: print(f"An unexpected error occurred: {e}")

cloudconvert --version

Debug

Known issues

breakingCloudConvert 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.

fix

Migrate your code to use CloudConvert API v2 logic and endpoints. Refer to the official API v2 documentation and SDK examples.

affects: < 2.0.0

gotchaIncorrectly 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.

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'])`.

affects: 2.0.0+

gotchaThe `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.

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.

affects: 2.0.0+

gotchaAlthough 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.

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.

affects: All versions

Errors

Common errors & fixes

KeyError: 'tasks'

Attempting to access `job['tasks']` from a job object created with an incorrect payload structure or a malformed API response.

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.

KeyError: 'id' (when calling Task.wait)

Attempting to call `cloudconvert.Task.wait()` with a job ID instead of a task ID.

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'])`.

CloudConvertClientError: Invalid API Key or missing API Key

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.

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()`.

CloudConvertClientError: Unable to convert (various error codes like 86, 87, 88, 91)

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.

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.

Upgrade

Version history

2.1.0latest on PyPI · released Mar 30, 2022

Audit

Dependencies

No dependency data recorded yet.

Agent activity

23 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/cloudconvert/cloudconvert-python ↗

packagehttps://pypi.org/project/cloudconvert/ ↗

homepagehttps://cloudconvert.com ↗