Thin PowerShell wrapper for the ConvertAPI v2 REST endpoints.
Supports single-file conversions, URL-based conversions, and multi-file multi-part uploads (e.g., PDF → merge) with safe downloads.
Get your API token:https://www.convertapi.com/a/authentication
- 🔐 Token-based auth via
CONVERTAPI_API_TOKENorSet-ConvertApiToken - 📄 Single local file upload (raw bytes,
Content-Disposition) - 🌐 Single URL conversion (query param
Url=…) - 📦 Multi-input multipart/form-data (
Files[0],Files[1], …) when you pass multiple inputs - 📎 Extra file parameters: any parameter whose name ends with
File(e.g.,OverlayFile,BackgroundFile) is detected and uploaded as a file part automatically - ⚙️ Extra options via
-Parameters @{ Name = 'Value' } - 💾 Saves results to disk; preserves API‑provided filenames
- 🧪
-WhatIf/-Confirmsafety (SupportsShouldProcess) - 🖥 Works on Windows PowerShell 5.1 and PowerShell 7+
Once published to the Gallery, end users can install with:
Install-Module ConvertApi -Scope CurrentUser
Import-Module ConvertApi -Force
# later updatesUpdate-Module ConvertApiNotes: First-time installs may prompt to trust the PSGallery repo and to install the NuGet provider—this is normal.
Place the folder:
ConvertApi/
ConvertApi.psd1
ConvertApi.psm1
into your user modules path:
- Windows PowerShell 5.1 →
~/Documents/WindowsPowerShell/Modules/ConvertApi - PowerShell 7+ →
~/Documents/PowerShell/Modules/ConvertApi
Then:
Import-Module ConvertApi -ForceIf you downloaded a ZIP in a browser, Windows may mark files as “downloaded from internet.”
Run once to unblock (not needed when installing via PowerShell Gallery or git clone):Set-ExecutionPolicy-Scope Process Bypass -Force Unblock-File-Path '<repo>\*'-Recurse
Set your token once per machine/user (or via CI env var):
# Get your token at https://www.convertapi.com/a/authenticationSet-ConvertApiToken'YOUR_API_TOKEN'-Persist
# or (CI/CD)$env:CONVERTAPI_API_TOKEN='YOUR_API_TOKEN'Single file (DOCX → PDF):
Invoke-ConvertApi-From docx -To pdf `-File .\example.docx `-OutputPath .\out -StoreFile -VerboseURL input (PDF → JPG):
Invoke-ConvertApi-From pdf -To jpg `-Url 'https://example.com/sample.pdf'`-OutputPath .\out -StoreFileBatch a folder (pipeline):
Get-ChildItem .\docs -Filter *.docx |Invoke-ConvertApi-From docx -To pdf -OutputPath .\out -StoreFileLocal PDFs (order preserved):
Invoke-ConvertApi-From pdf -To merge `-File .\a.pdf, .\b.pdf, .\c.pdf `-OutputPath .\out -StoreFileBy URLs:
Invoke-ConvertApi-From pdf -To merge `-Url 'https://example.com/a.pdf','https://example.com/b.pdf'`-OutputPath .\out -StoreFileMix local + URL:
Invoke-ConvertApi-From pdf -To merge `-File .\local1.pdf `-Url 'https://example.com/remote2.pdf'`-OutputPath .\out -StoreFileMerge options (examples):
Invoke-ConvertApi-From pdf -To merge `-File .\a.pdf, .\b.pdf `-Parameters @{
PageSize='a4'# e.g., 'a4', 'letter'PageOrientation='portrait'# 'portrait' | 'landscape'BookmarksToc='filename'# toc from filenamesRemoveDuplicateFonts=$trueOpenPage=1# open page number
} `-OutputPath .\out -StoreFileWhen you pass multiple inputs (files and/or URLs), the module automatically uses multipart/form‑data and sends them as
Files[0],Files[1], …
Some converters accept additional files as parameters. Any parameter whose name ends with File is treated as a file part when the value is a local path.
PDF → watermark-overlay (overlay from local PDF):
Invoke-ConvertApi-From pdf -To watermark-overlay `-File .\a.pdf `-Parameters @{ OverlayFile='.\b.pdf'; Opacity=0.6 } `-OutputPath .\out -StoreFile -VerboseOverlay from a URL:
Invoke-ConvertApi-From pdf -To watermark-overlay `-File .\a.pdf `-Parameters @{ OverlayFile='https://example.com/b.pdf' } `-OutputPath .\out -StoreFile-From/-To
Route selector →POST https://v2.convertapi.com/convert/{From}/to/{To}-File[string[]]
One or more local files.- 1 file → raw bytes upload (octet‑stream + Content‑Disposition)
- 2+ files → multipart form with
Files[i]
-Url[string[]]
One or more remote files.- 1 URL → sent as
?Url=query parameter - 2+ URLs → multipart form with
Files[i]
- 1 URL → sent as
-Parameters[hashtable]
Additional API options (become query params or form fields).
Special rule: keys that end withFileand point to a local path are uploaded as file parts; URL strings remain as string fields.-StoreFile[switch]
AddsStoreFile=trueso the API returns downloadable URLs.-OutputPath[string]
Directory where results are saved.-Token[string]
Overrides the token for the current call.
“No API token found”
Set the token first:Set-ConvertApiToken'YOUR_API_TOKEN'-Persist
or:
$env:CONVERTAPI_API_TOKEN='YOUR_API_TOKEN'
Token portal: https://www.convertapi.com/a/authentication
Execution policy / blocked scripts
Not an issue when installing via PowerShell Gallery or git clone.
Only needed for ZIP downloads from the browser:Set-ExecutionPolicy-Scope Process Bypass -Force Unblock-File-Path '<repo>\*'-Recurse
AllSigned environments
Your org may require Authenticode‑signed scripts. Sign the module or ask your admin to trust your code‑signing certificate.Launching a new process with multiple
-Filevalues
Repeat the flag:pwsh -NoProfile -File .\examples\Convert-PdfToMerge.ps1-File .\a.pdf -File .\b.pdf -OutDir .\out
Filename collisions
If a target file exists and-Overwriteis not set, the module appends a random suffix.Progress / diagnostics
Add-Verbosefor download logs and basic tracing.
Choose a license appropriate for your distribution (e.g., MIT).
examples/Convert-PdfToMerge.ps1– Merge multiple PDFs (local files and/or URLs).examples/Convert-DocxToPdf.ps1– Batch DOCX → PDF for a folder.examples/Watermark-Overlay.ps1– Apply a PDF overlay usingOverlayFile.
Run with:
# PowerShell 7
pwsh .\examples\Convert-PdfToMerge.ps1-File .\a.pdf,.\b.pdf -OutDir .\out -StoreFile
# Windows PowerShell 5.1
powershell -File .\examples\Convert-DocxToPdf.ps1-InDir .\docs -OutDir .\out -RecurseA minimal workflow is included at .github/workflows/ci.yml:
- Lints the module with PSScriptAnalyzer
- Verifies the module can be imported
Add your ConvertAPI token as a repository secret later if you introduce integration tests.