JavaScript SDK

@convertmepls/sdk is a zero-dependency client for the conversion API. It works in Node 18+ and the browser (anywhere fetch exists).

#Install

npm install @convertmepls/sdk

#Quick start

import { ConvertMePls } from '@convertmepls/sdk';

const gc = new ConvertMePls({ apiKey: process.env.CONVERTMEPLS_KEY });

// Convert bytes and wait for the result
const bytes = await fetch('https://example.com/cat.png').then((r) => r.arrayBuffer());
const job = await gc.convert(bytes, { filename: 'cat.png', target: 'webp', options: { quality: 82 } });

console.log(job.status);       // "done"
console.log(job.downloadUrl);  // presigned URL to the converted file

// Download the converted bytes
const out = await gc.download(job.downloadUrl);

convert() runs the whole flow for you: it requests an upload URL, uploads the bytes, creates the conversion, and polls until it finishes. The source format is inferred from the filename — pass source to override it.

#Batch — many files, each to its own format

const jobs = await gc.convertBatch([
  { data: pngBytes,  filename: 'logo.png',   target: 'webp' },
  { data: movBytes,  filename: 'clip.mov',   target: 'mp3'  },
  { data: heicBytes, filename: 'photo.heic', target: 'jpeg' }
]);

for (const job of jobs) {
  if (job.status === 'done') console.log(job.downloadUrl);
}

convertBatch() uploads every input, submits a single batch request, and waits for all jobs. Source formats are inferred from filenames unless you pass source.

#Lower-level methods

await gc.formats();                       // the full format + pair catalog (cached)
await gc.targetsFor('mp4');               // ['mp3', 'webm', 'gif', …]
const { inputKey, uploadUrl } = await gc.createUpload('a.mov', 'video/quicktime', size);
const { jobId } = await gc.createConversion(inputKey, 'mov', 'mp4');
const job = await gc.waitForConversion(jobId);

#Configuration

new ConvertMePls({
  apiKey: 'gck_live_…',                    // from your dashboard
  baseUrl: 'https://api.convertmepls.com',  // override for self-hosting
  fetch: customFetch                       // optional (proxy / testing)
});

Errors throw a ConvertMePlsError with a .status for HTTP failures.