xconvert · Python

Python 3.9+ · httpx-based · sync + async.

Install

Shell
pip install xconvert

End-to-end: upload a file and convert it

Python
import os, httpx
from xconvert.v1 import Xconvert, ClientOptions
from xconvert.v1.generated.api.uploads import create_upload, complete_upload
from xconvert.v1.generated.models.create_upload_request import CreateUploadRequest
from xconvert.v1.generated.models.upload_file_request import UploadFileRequest
from xconvert.v1.generated.models.create_job_request import CreateJobRequest

xc = Xconvert(ClientOptions(api_key=os.environ["XCONVERT_API_KEY"]))

# 1. Read the file you want to convert.
with open("song.mp3", "rb") as f:
    data = f.read()

# 2. Create an upload session.
upload = create_upload.sync(
    client=xc.http,
    body=CreateUploadRequest(
        feature_id="convert-mp3-to-aac",
        files=[UploadFileRequest(name="song.mp3", size_bytes=len(data), content_type="audio/mpeg")],
    ),
)
handoff = upload.uploads[0]

# 3. PUT the bytes to the edge chunk endpoint.
httpx.put(
    f"{handoff.chunk_endpoint}?totalChunks=1",
    headers={
        "Content-Range": f"bytes 0-{len(data)-1}/{len(data)}",
        "Content-Type": "application/octet-stream",
    },
    content=data,
).raise_for_status()

done = complete_upload.sync(client=xc.http, upload_id=upload.upload_id)
file_id = done.files[0].file_id

# 4. Submit the conversion.
job = xc.submit_job(CreateJobRequest(
    feature_id="convert-mp3-to-aac",
    file_ids=[file_id],
    from_type="mp3",
    to_type="aac",
    process_type="convert",
))

# 5. Poll until terminal.
final = xc.poll_until_done(job.id)
print(final.outputs[0].download_url)

Configuration

Python
Xconvert(ClientOptions(
    api_key="xck_live_...",                          # required
    base_url="https://api.staging.xconvert.com",     # optional
    headers={"X-Request-Id": "..."},                 # optional
    timeout=30.0,                                    # seconds
))

What's on the client

Options field — why it's an attrs model

The generated CreateJobRequest.options field is a typed CreateJobRequestOptions model (an attrs class), not a plain dict. To pass per-feature options:

Python
from xconvert.v1.generated.models.create_job_request_options import CreateJobRequestOptions

opts = CreateJobRequestOptions()
opts.additional_properties["bitrate"] = 192
opts.additional_properties["channels"] = 2

job = xc.submit_job(CreateJobRequest(
    feature_id="convert-mp3-to-aac",
    file_ids=[file_id], from_type="mp3", to_type="aac", process_type="convert",
    options=opts,
))

Passing a plain dict raises 'dict' object has no attribute 'to_dict' when the SDK serializes. Empty options is fine: leave options off entirely and the server applies baselines + defaults.

Common operations

List your jobs

Python
from xconvert.v1.generated.api.jobs import list_jobs
page = list_jobs.sync(client=xc.http, limit=20, status="complete")

Caller introspection

Python
from xconvert.v1.generated.api.caller_introspection import get_me
me = get_me.sync(client=xc.http)
print(me.api_tier, me.credits_.payg_remaining)

Webhook endpoint

Python
from xconvert.v1.generated.api.webhooks_customer import create_webhook_endpoint
from xconvert.v1.generated.models.create_webhook_endpoint_request import CreateWebhookEndpointRequest

endpoint = create_webhook_endpoint.sync(
    client=xc.http,
    body=CreateWebhookEndpointRequest(
        url="https://yoursite.com/hooks/xconvert",
        events=["job.completed", "job.failed"],
    ),
)
print(endpoint["secret"])  # shown ONCE

Async

Every operation has an asyncio counterpart (the generated client provides both). Use it when you're inside an async context:

Python
from xconvert.v1.generated.api.jobs import get_job as get_job_op
job = await get_job_op.asyncio(id=job_id, client=xc.http)

Submodule versioning

Python
from xconvert.v1 import Xconvert         # current
# from xconvert.v2 import Xconvert        # when it ships