Crate cloudconvert_sdk

Expand description

Async Rust SDK primitives for the CloudConvert API v2.

This crate exposes typed request and response models for CloudConvert jobs and tasks, plus a CloudConvertClient for calling the API from async Rust applications. Operation-specific drift is handled through option(...) builder methods, extra maps, and TaskRequest::custom.

§Build jobs

Use JobCreateRequest::linear when each task feeds into the next task.

use cloudconvert_sdk::{FileExtension, JobCreateRequest};

let request = JobCreateRequest::linear()
    .import_url("https://example.test/input.docx")
    .convert(FileExtension::Pdf)?
    .export_url()?
    .build();

let payload = serde_json::to_value(request).unwrap();
assert_eq!(payload["tasks"]["import-url"]["operation"], "import/url");
assert_eq!(payload["tasks"]["convert"]["input"], "import-url");
assert_eq!(payload["tasks"]["export-url"]["input"], "convert");

Use *_with(...) methods to configure task-specific options while keeping a serial pipeline.

use cloudconvert_sdk::{FileExtension, JobCreateRequest};

let request = JobCreateRequest::linear()
    .import_url_with("https://example.test/input.docx", |task| {
        task.filename("input.docx")
    })
    .convert_with(FileExtension::Pdf, |task| {
        task.input_format(FileExtension::Docx)
    })?
    .export_url()?
    .build();

let payload = serde_json::to_value(request).unwrap();
assert_eq!(payload["tasks"]["import-url"]["filename"], "input.docx");
assert_eq!(payload["tasks"]["convert"]["input_format"], "docx");

Use JobCreateRequest::graph when a job branches, joins multiple inputs, or needs to reference a non-adjacent task.

use cloudconvert_sdk::{FileExtension, JobCreateRequest};

let request = JobCreateRequest::graph(|job| {
    let import = job.import_url("https://example.test/input.docx");
    let pdf = job.convert(&import, FileExtension::Pdf);
    let png = job.convert(&import, FileExtension::Png);
    job.export_url([&pdf, &png]);
})
.build();

let payload = serde_json::to_value(request).unwrap();
assert_eq!(payload["tasks"]["convert"]["input"], "import-url");
assert_eq!(payload["tasks"]["convert-2"]["input"], "import-url");
assert_eq!(
    payload["tasks"]["export-url"]["input"],
    serde_json::json!(["convert", "convert-2"])
);

§Call the API

Live API calls need a CloudConvert API key. ApiKey::from_env() reads CLOUDCONVERT_API_KEY.

use cloudconvert_sdk::{ApiKey, CloudConvertClient, FileExtension, JobCreateRequest};

let client = CloudConvertClient::builder(ApiKey::from_env()?).build()?;
let request = JobCreateRequest::linear()
    .import_url("https://example.test/input.docx")
    .convert(FileExtension::Pdf)?
    .export_url()?
    .build();

let job = client.jobs().create(request).await?;
let finished = client.jobs().wait(&job.id).await?;
for file in finished.export_urls() {
    if let Some(url) = &file.url {
        let bytes = client.download(url).await?;
        println!("downloaded {} bytes as {}", bytes.len(), file.filename);
    }
}

Structs§

ApiError: Borrowed view of a CloudConvert HTTP error body and rate-limit headers.
ApiKey: CloudConvert API key used as a bearer token.
ApiResponse: A non-paginated API response that preserves envelope metadata.
ArchiveTask
AzureBlobExportTask
AzureBlobImportTask
Base64ImportTask
CaptureWebsiteTask
ClientBuilder: Configures credentials, base URLs, transport, and optional retry before build.
CloudConvertClient: Entry point for authenticated CloudConvert API calls and file transfer.
CloudConvertConfig: Resolved client settings produced by ClientBuilder::build.
CommandTask
ConvertTask
ExportUploadTask
ExportUrlTask
FileResult: One exported file entry, usually from an export/url task.
GenericTask: Builder for a custom CloudConvert task operation.
GoogleCloudStorageExportTask
GoogleCloudStorageImportTask
ImportUploadTask
ImportUrlTask
InvalidBuilderState: Error returned when a job builder method is called in an invalid state.
Job: CloudConvert job returned by create, get, wait, and list endpoints.
JobBuilder: Builder for serial JobCreateRequest pipelines.
JobCreateRequest: Request body for POST /v2/jobs.
JobGetQuery: Query parameters for GET /v2/jobs/{id} and sync wait endpoints.
JobGraphBuilder: Builder for branched CloudConvert job graphs.
JobListQuery: Query parameters for GET /v2/jobs.
JobTask: Task snapshot embedded in a Job response.
JobsResource: Job REST endpoints, including sync wait and optional Socket.IO wait helpers.
MergeTask
MetadataTask
MetadataWriteTask
OAuthAccessToken: OAuth access token used as a bearer token for API calls.
OAuthClient: OAuth client used to start authorization flows and exchange tokens.
OAuthClientSecret: OAuth client secret used during authorization-code and refresh flows.
OAuthRefreshToken: OAuth refresh token exchanged for a new access token.
OAuthTokenResponse: Token payload returned by CloudConvert OAuth token endpoints.
OpenStackExportTask
OpenStackImportTask
Operation: One supported CloudConvert operation with engines, options, and alternatives.
OperationEngineVersion: Engine version entry attached to an Operation metadata record.
OperationListQuery: Query parameters for GET /v2/operations.
OperationOption: Documented option schema for a CloudConvert operation.
OperationValidationError: Validation failure describing which operation field or option was rejected.
OperationsResource: Operations metadata listing engines, formats, and documented options.
OptimizeTask
Page: A paginated API response.
PaginationLinks: Pagination links returned by CloudConvert list endpoints.
PaginationMeta: Pagination metadata returned by CloudConvert list endpoints.
ParseFileExtensionError: Error returned when parsing a string into FileExtension fails.
PdfATask
PdfDecryptTask
PdfEncryptTask
PdfExtractPagesTask
PdfOcrTask
PdfRotatePagesTask
PdfSplitPagesTask
PdfXTask
RateLimit: Rate limit information extracted from CloudConvert response headers.
RawImportTask
S3ExportTask
S3ImportTask
SftpExportTask
SftpImportTask
SigningSecret: Shared secret for signing job URLs and webhook payloads.
SocketSubscription: Bearer-authenticated subscribe payload sent to the Socket.IO server.
Task: Standalone CloudConvert task returned by task endpoints.
TaskGetQuery: Query parameters for GET /v2/tasks/{id}.
TaskListQuery: Query parameters for GET /v2/tasks.
TaskName: Name assigned to a task in a CloudConvert job request.
TaskRequest: Serialized task request used by job and standalone task APIs.
TaskResult: Task output payload containing exported files or an upload form.
TasksResource: Standalone task REST endpoints and optional Socket.IO wait helpers.
ThumbnailTask
TransportConfig: Optional reqwest timeouts and user agent applied when building HTTP clients.
UploadForm: Presigned multipart upload target for an import/upload task.
User: Authenticated CloudConvert account returned by GET /v2/users/me.
UsersResource: Account endpoints and helpers that resolve user-scoped Socket.IO channels.
WatermarkTask
Webhook: Registered webhook subscription, including optional signing secret metadata.
WebhookCreateRequest: Request body for POST /v2/webhooks.
WebhookListQuery: Query parameters for listing registered webhooks.
WebhooksResource: Webhook registration endpoints for the authenticated account.

Enums§

Error: Top-level failure type for API, transport, builder, and validation errors.
FileExtension: Supported CloudConvert file extension tokens.
FontAlign
Input: Input dependency for a CloudConvert task.
InvalidBuilderStateKind: Specific reason a job builder rejected the current call sequence.
JobSocketEvent: Job lifecycle event names emitted over Socket.IO.
JobStatus: Lifecycle status returned for a CloudConvert job.
Layer
OAuthScope: OAuth scope token requested during authorization.
OperationOptionKind: Declared value type for an operation option in metadata responses.
OperationValidationErrorKind: Specific validation failure category for an operation or option check.
OperationValidationMode: Controls whether undocumented task options are accepted during validation.
PositionHorizontal
PositionVertical
Region: Regional API hostname prefix for non-sandbox clients.
SocketChannel: Socket.IO channel selector for job, task, or user-scoped event streams.
SocketEventKind: Parsed Socket.IO event name, including unknown custom events.
TaskSocketEvent: Task lifecycle event names emitted over Socket.IO.
TaskStatus: Lifecycle status returned for a CloudConvert task.
WebhookEvent: Event name CloudConvert can deliver to a registered webhook URL.

Traits§

TaskPayload: Sealed trait implemented by SDK-owned typed task builders.

Functions§

sign_job_url: Builds a signed job URL that embeds the serialized job request in the query string.
sign_payload: Computes the HMAC-SHA256 hex digest CloudConvert uses for webhook payloads.
socket_base_url: Socket.IO base URL for production or sandbox environments.
verify_signature: Returns true when signature_hex matches the HMAC-SHA256 digest of payload.

Type Aliases§

ExtraOptions: Open-ended operation options serialized beside typed task fields.
OperationValidationResult: Result of validating a TaskRequest against an Operation record.
Result: Convenience result alias used throughout the crate.