Build a Media Converter in Wix Velo with CloudConvert

Updated: Nov 2
A Wix media converter needs a frontend, a backend request and a conversion service that processes the file. Keep credentials on the backend and treat conversion as an asynchronous job.
This example creates an MP3 from a direct MP4 file that you own or are authorized to process. It uses CloudConvert’s documented job workflow. A source URL must point to the actual supported file, not merely a webpage containing a video.
Define the example’s scope
The reference implementation is an admin-only prototype. It creates a job and checks its status; it is not an unlimited public download service.
You need a CloudConvert account, an API key with the required task permissions, a supported input file and an appropriate allowance for processing costs. Verify the provider’s current limits and supported conversion before using a large file.
CloudConvert’s Jobs API describes jobs containing import, conversion and export tasks. Its Import documentation explains direct URL and upload workflows.
Configure the source and secret
Store the API key as CLOUDCONVERT_API_KEY in Wix Secrets Manager. Replace the example source URL with a direct MP4 asset you control and permit CloudConvert to retrieve.
For the first test, use a small, non-sensitive file. Do not let visitors turn an unrestricted URL input into a general-purpose fetch or conversion proxy.
Create and inspect the job
Create backend/media-converter.web.js:
// backend/media-converter.web.js
import { webMethod, Permissions } from "@wix/web-methods";
import { secrets } from "@wix/secrets";
import { auth } from "@wix/essentials";
import { fetch } from "wix-fetch";
const readSecret = auth.elevate(secrets.getSecretValue);
// Replace with a direct MP4 file that you own and permit the service to download.
const sourceUrl = "https://YOUR_MEDIA_DOMAIN.example/authorized-demo.mp4";
export const createMp3Job = webMethod(Permissions.Admin, async () => {
const { value } = await readSecret("CLOUDCONVERT_API_KEY");
const body = {
tasks: {
"import-source": {
operation: "import/url",
url: sourceUrl,
filename: "authorized-demo.mp4"
},
"convert-audio": {
operation: "convert",
input: "import-source",
input_format: "mp4",
output_format: "mp3"
},
"export-audio": {
operation: "export/url",
input: "convert-audio"
}
}
};
const response = await fetch("https://api.cloudconvert.com/v2/jobs", {
method: "POST",
headers: {
Authorization: "Bearer " + value,
"Content-Type": "application/json"
},
body: JSON.stringify(body)
});
if (!response.ok) throw new Error("The conversion job could not be created.");
const result = await response.json();
if (!result.data?.id || !result.data?.status) {
throw new Error("The service returned an unexpected job response.");
}
return { jobId: result.data.id, status: result.data.status };
});
export const getMp3Job = webMethod(Permissions.Admin, async (jobId) => {
if (typeof jobId !== "string" || !/^[A-Za-z0-9-]{1,80}$/.test(jobId)) {
throw new Error("A valid job ID is required.");
}
const { value } = await readSecret("CLOUDCONVERT_API_KEY");
const response = await fetch(
"https://api.cloudconvert.com/v2/jobs/" + encodeURIComponent(jobId),
{ headers: { Authorization: "Bearer " + value } }
);
if (!response.ok) throw new Error("The conversion status could not be read.");
const result = await response.json();
const job = result.data;
if (!job?.status) throw new Error("The service returned no job status.");
if (job.status === "error") throw new Error("The conversion failed.");
const exportTask = (job.tasks ?? []).find(
task => task.operation === "export/url" && task.status === "finished"
);
const downloadUrl = exportTask?.result?.files?.[0]?.url;
return {
status: job.status,
...(job.status === "finished" && typeof downloadUrl === "string" &&
downloadUrl.startsWith("https://") ? { downloadUrl } : {})
};
});The create function returns a job ID and status. It does not claim that the download is ready immediately. The status method returns a download URL only after the job is finished and a completed export task provides an HTTPS result.
Connect an admin test page
Use a Wix web method with Permissions.Admin while evaluating the integration. Import createMp3Job and getMp3Job from backend/media-converter.web.
After creating one job, retain its returned jobId and check that job at a modest interval. Stop checking when it finishes, fails or exceeds your chosen deadline. Do not create a new job each time you refresh the status.
Show separate interface states: ready to start, processing, finished and failed. Prevent accidental repeated submissions.
Design a public version separately
A visitor-facing service needs authentication or another appropriate access control, usage limits, file-size limits and a job record tied to its owner. Every status request must verify that the caller can access that job.
Decide how long files and job records should remain available. Make any upload, storage and third-party processing terms understandable before a visitor submits a file.
For files uploaded by visitors, use the provider’s documented upload flow rather than requiring publicly readable private files.
Avoid misleading implementation promises
A generic RapidAPI key and a copied endpoint do not establish that an unrelated provider still supports the same operation or response format. Nor should Express server instructions be presented as code that can be pasted directly into Wix page code.
Keep one provider and one supported workflow in the example, then adapt it deliberately.
Prepare an authorized source file and a small test
Choose a short MP4 file you own or have permission to process. The sourceUrl in the example must be replaced with a direct, accessible file URL that CloudConvert is permitted to download. A normal web page containing a video is not equivalent to the media file itself.
Create backend/media-converter.web.js and store the API credential under CLOUDCONVERT_API_KEY. Keep the administrator-only permission for this controlled example. Confirm the provider account’s current conversion support, limits and costs before starting real jobs.
The old tutorial artwork referred to a YouTube-to-MP3 converter. This updated implementation processes an authorized direct media file; it does not extract media from a YouTube watch page. That distinction affects both the request format and whether the source can be used.
Understand the three tasks in the job
The import-source task retrieves the permitted file. The convert-audio task depends on that imported input and requests an MP3 output. The export-audio task makes the completed result available through the provider’s export mechanism.
Task names are references inside the job definition. If you rename one, update the tasks that refer to it. A misspelled input reference is different from an unsupported file or an account authorization problem.
Use the CloudConvert jobs documentation when changing the workflow. Keep the first version limited to one known input format and output format so the relationship between tasks remains clear.
Treat creation and completion as different states
Call createMp3Job and retain the returned jobId. A returned identifier means a job was created; it does not mean a downloadable file already exists. Use getMp3Job to inspect that specific job and render the returned state appropriately.
Show a processing message while the job is unfinished. Show a download action only when the inspected result includes the expected completed export. If the job fails, provide a useful failure state rather than leaving a spinner running indefinitely.
Choose a bounded status-checking policy for a real interface. Avoid a new status request on every animation frame or an endless loop after the user leaves the page. For a production workflow, review the provider’s supported asynchronous notification options and verify their authenticity before trusting them.
Keep a public tool’s responsibilities explicit
A public upload feature adds work beyond this administrator test. It needs a defined set of permitted file types and sizes, ownership rules, storage handling, job ownership checks and limits on repeated requests. A user should not be able to inspect someone else’s job merely by supplying an identifier.
Explain where the file is processed and how the user obtains the result. Review the handling of temporary exports rather than treating a provider URL as permanent storage. Do not promise that a converted file remains available indefinitely unless the application actually stores and serves it under a defined policy.
Verify the output as media
Download an authorized test result and play it in the intended environment. Check that it contains the expected audio and that the output format is appropriate. A successful API status does not establish that the selected source contained a useful audio track.
Record the input used, the workflow configuration and the resulting behavior. Test an inaccessible source and an invalid job identifier as well as the successful path. These checks turn the example into an inspectable integration rather than an unexplained conversion button.
Follow the asynchronous conversion pipeline
Stage | Task or method | What the interface should do |
Import | import-source | Retrieve the permitted direct MP4 source |
Convert | convert-audio | Produce the requested MP3 from the imported input |
Export | export-audio | Make the completed output available through the provider |
Inspect | getMp3Job(jobId) | Show processing, a usable export or an understandable failure |
The stages describe this job definition, not four independent button clicks. See the CloudConvert Jobs reference when changing task dependencies. A database-backed project list can use a separate Wix and Google Sheets integration, but that read-only example is not a job-ownership system.
What was tested?
Local tests checked the task dependencies, backend-only credential use, job-status handling and error paths with simulated provider responses. No billable conversion or customer file processing was performed during this article review.
Is the example ready for an unrestricted public tool?
It is an admin-only reference. Add caller authorization, usage controls and project-specific integration testing before making a public service.
For help building a business-specific tool, contact CodeMasters. Our Google Sheets integration guide demonstrates a different backend integration.


