.NET SDK
Convert files between 240+ formats from C# and .NET. One call uploads your file, converts it, waits and downloads the result; jobs, webhooks and the format list are there when you need more. .NET 8+, no dependencies, async with CancellationToken throughout.
Installing
Install it with your package manager. .NET 8+.
$ dotnet add package RunConvert$ <PackageReference Include="RunConvert" Version="0.1.0" />Initializing
new RunConvertClient(string? apiKey = null, string baseUrl = …, TimeSpan? timeout = null, int maxRetries = 2, HttpClient? httpClient = null)Create one client and reuse it. Without an API key it reads the RUNCONVERT_API_KEY environment variable. Get a key in Dashboard → API Keys, and keep it on your server: never put it in browser or mobile app code. With dependency injection, register one client as a singleton, or pass an HttpClient from IHttpClientFactory.
Example
using RunConvert;
using var rc = new RunConvertClient(); // reads RUNCONVERT_API_KEYusing var rc = new RunConvertClient(
apiKey: Environment.GetEnvironmentVariable("RUNCONVERT_API_KEY"),
timeout: TimeSpan.FromSeconds(60),
maxRetries: 2);builder.Services.AddSingleton(_ => new RunConvertClient());Parameters
apiKeystring?Your API key. Defaults to the RUNCONVERT_API_KEY environment variable.baseUrlstringDefaults to https://api.runconvert.com/v3.timeoutTimeSpan?Time limit per API request. Default 60 s. Uploads and downloads have none.maxRetriesintRetries for network errors, 429 and 5xx. Default 2.httpClientHttpClient?Your own HttpClient, e.g. from IHttpClientFactory.
Quick start
Convert a file in one call: the SDK uploads it, converts it, waits for the job and saves the result.
Example
using RunConvert;
using var rc = new RunConvertClient();
var result = await rc.ConvertAsync("report.docx", new ConvertOptions { To = "pdf", OutDir = "out" });
Console.WriteLine(string.Join(", ", result.Saved)); // out/report.pdfout/report.pdfConvert
Convert a file
rc.ConvertAsync(string fileOrUrl, ConvertOptions o, CancellationToken ct = default) → Task<ConvertResult>Converts one file in one call: uploads a local file (or imports a URL), converts it, waits for the job and, when an output folder is given, downloads the result. Uses credits.
Example
var result = await rc.ConvertAsync("report.docx", new ConvertOptions { To = "pdf", OutDir = "out" });
Console.WriteLine(string.Join(", ", result.Saved));// Imported by RunConvert: nothing to upload
await rc.ConvertAsync("https://example.com/talk.mp4", new ConvertOptions { To = "mp3", OutDir = "out" });await rc.ConvertAsync("talk.mp4", new ConvertOptions
{
To = "mp3",
Options = new() { ["audioBitrate"] = "192k" },
OutDir = "out",
});await rc.ConvertAsync("movie.mov", new ConvertOptions
{
To = "mp4",
OutDir = "out",
Timeout = TimeSpan.FromMinutes(10),
OnUpdate = job => Console.WriteLine(job.Status),
});out/report.pdfout/talk.mp3waiting
processing
finishedParameters
fileOrUrlstringA local path or an http(s) URL (imported by RunConvert).RequiredTostringThe target format, e.g. "pdf" or "mp3".RequiredFromstring?The source format. Read from the file name or URL when left out; needed for bytes or streams without a filename.OptionsDictionary<string, object?>?Engine options for the conversion, e.g. audioBitrate or image_quality. List them with Formats → engines for a pair.OutDirstring?Save the results in this folder (created if needed). Without it nothing is downloaded; use the result's files.Tagstring?A label to find the job later, e.g. "invoices".TimeoutTimeSpan?How long to wait for the job before giving up.OnUpdateAction<Job>?Called with the job after every check, e.g. to show progress.
Returns
ConvertResult(Job, Files, Saved): the finished job, its result files (Filename, Url, Size) and the local paths when OutDir is set.
Jobs
Create a job
rc.Jobs.CreateAsync(IDictionary<string, object?> tasks, string? tag = null, IDictionary<string, object?>? metadata = null, CancellationToken ct = default) → Task<Job>Creates a job from named tasks that run in order: import → convert → export. Tasks refer to each other by name in input. The job comes back with its tasks; an upload task carries the upload_url to send your file to. Build tasks with Tasks.ImportUrl, ImportUpload, Convert and ExportUrl.
Example
var job = await rc.Jobs.CreateAsync(new Dictionary<string, object?>
{
["a"] = Tasks.ImportUrl("https://example.com/cover.pdf"),
["b"] = Tasks.ImportUrl("https://example.com/body.pdf"),
["merge"] = Tasks.Convert("pdf", "pdf", new[] { "a", "b" }),
["export"] = Tasks.ExportUrl("merge"),
}, tag: "merge");var job = await rc.Jobs.CreateAsync(new Dictionary<string, object?>
{
["upload"] = Tasks.ImportUpload(),
["convert"] = Tasks.Convert("png", "webp", "upload", new Dictionary<string, object?> { ["image_quality"] = 80 }),
["export"] = Tasks.ExportUrl("convert"),
});
await rc.Files.UploadAsync(job.Task("upload")!.UploadUrl!, "image.png");Parameters
tasksIDictionary<string, object?>Named task definitions. Names use letters, digits, - or _ (up to 64 characters).Requiredtagstring?A label to find the job later, e.g. "invoices".metadataIDictionary<string, object?>?Your own key-value data, returned with the job and in webhooks.
Returns
The job, with its tasks.
Get a job
rc.Jobs.GetAsync(string id, CancellationToken ct = default) → Task<Job>Gets one job with its tasks: status, credits used, and the result files of its export tasks.
Example
var job = await rc.Jobs.GetAsync("job_01hx4k9m2p7w");
Console.WriteLine(job.Status);{
"id": "job_01hx4k9m2p7w",
"status": "finished",
"tag": "invoices",
"credits_used": 2,
"created_at": "2026-11-16T09:12:04Z",
"ended_at": "2026-11-16T09:12:09Z",
"tasks": [
{ "name": "import-1", "operation": "import/direct/upload", "status": "finished" },
{ "name": "convert-1", "operation": "convert", "status": "finished" },
{ "name": "export-1", "operation": "export/url", "status": "finished",
"result": { "files": [
{ "filename": "report.pdf", "size": 72841, "url": "https://storage.runconvert.com/…/report.pdf" }
] } }
]
}Parameters
idstringThe job's ID.Required
Returns
The job, with its tasks.
List jobs
rc.Jobs.ListAsync(string? status = null, string? tag = null, int page = 0, int perPage = 0, CancellationToken ct = default) → Task<JobPage>One page of jobs, newest first, with paging details. Filter by status or tag.
Example
var page = await rc.Jobs.ListAsync(status: "finished", perPage: 20);
foreach (var job in page.Data) Console.WriteLine(job.Id);{
"data": [ { "id": "job_01hx4k9m2p7w", "status": "finished", … } ],
"meta": { "page": 1, "per_page": 20, "total": 42, "total_pages": 3 }
}Parameters
statusstring?Only jobs with this status: waiting, processing, finished, error or canceled.tagstring?A label to find the job later, e.g. "invoices".pageintPage number, from 1. 0 for the first.perPageintJobs per page (max 100). 0 for the default.
Returns
JobPage(Data, Page, TotalPages, Total).
Every job
rc.Jobs.AllAsync(string? status = null, string? tag = null, int perPage = 0, CancellationToken ct = default) → IAsyncEnumerable<Job>Every job, page by page, so you can loop over all of them without handling pages yourself.
Example
await foreach (var job in rc.Jobs.AllAsync(tag: "invoices"))
Console.WriteLine($"{job.Id} {job.Status}");Parameters
statusstring?Only jobs with this status: waiting, processing, finished, error or canceled.tagstring?A label to find the job later, e.g. "invoices".perPageintJobs per page (max 100).
Wait for a job
rc.Jobs.WaitAsync(string id, TimeSpan? timeout = null, Action<Job>? onUpdate = null, CancellationToken ct = default) → Task<Job>Polls a job until it finishes (every 0.7 s, slowing to 3 s). Fails with the task's code and reason if the job fails, and stops after the timeout if you give one.
Example
var done = await rc.Jobs.WaitAsync(job.Id, TimeSpan.FromMinutes(5));
foreach (var f in done.ExportedFiles()) await rc.Files.DownloadAsync(f, "out");try
{
await rc.Jobs.WaitAsync(job.Id);
}
catch (JobFailedException e)
{
Console.WriteLine($"{e.Task?.Code} {e.Task?.Reason} {e.Task?.Message}");
}Parameters
idstringThe job's ID.RequiredtimeoutTimeSpan?How long to wait; throws WaitTimeoutException after it.onUpdateAction<Job>?Called with the job after every check, e.g. to show progress.
Returns
The finished job.
Cancel a job
rc.Jobs.CancelAsync(string id, CancellationToken ct = default) → Task<Job>Cancels a job's pending tasks. Credits for tasks that didn't finish are refunded.
Example
await rc.Jobs.CancelAsync("job_01hx4k9m2p7w");Parameters
idstringThe job's ID.Required
Returns
The canceled job.
Delete a job
rc.Jobs.DeleteAsync(string id, CancellationToken ct = default) → TaskDeletes a job and its files.
Example
await rc.Jobs.DeleteAsync("job_01hx4k9m2p7w");Parameters
idstringThe job's ID.Required
Result files
job.ExportedFiles() → List<ResultFile>The files produced by a finished job's export tasks: file name, a temporary download URL and size.
Example
foreach (var f in job.ExportedFiles())
Console.WriteLine($"{f.Filename} {f.Url}");[
{ "filename": "report.pdf", "size": 72841, "url": "https://storage.runconvert.com/…/report.pdf" }
]Files
Upload a file
rc.Files.UploadAsync(string uploadUrl, string path | Stream stream, string? filename, CancellationToken ct = default) → TaskSends a file to an import/direct/upload task before its deadline. Use it with a job you created yourself.
Example
await rc.Files.UploadAsync(job.Task("upload")!.UploadUrl!, "image.png");Parameters
uploadUrlstringThe upload task's UploadUrl: job.Task("upload")!.UploadUrl.Requiredpath / streamstring | StreamA local path or a stream.Requiredfilenamestring?The file's name when you pass bytes or a stream.
Download a result
rc.Files.DownloadAsync(ResultFile file, string dir, CancellationToken ct = default) → Task<string>Saves a result file into a folder, keeping its name, and returns the path. Streams, so big files use little memory. DownloadAsync(url, dir, filename) saves a URL under a name you choose.
Example
foreach (var f in job.ExportedFiles())
Console.WriteLine(await rc.Files.DownloadAsync(f, "out"));out/report.pdfParameters
fileResultFileA result file from a job's export task, or its URL.RequireddirstringThe folder to save into.Required
Returns
The saved file's path.
Formats
List formats
rc.Operations.ListAsync(string? category = null, CancellationToken ct = default) → Task<JsonNode?>Every input format and what it converts to. Public: no API key needed.
Example
var catalog = await rc.Operations.ListAsync("audio");
Console.WriteLine(catalog!["formats"]!.AsArray().Count);Parameters
categorystring?Only one category: document, image, video, audio, ebook, archive, font, cad, …
Targets for a format
rc.Operations.ForInputAsync(string input, CancellationToken ct = default) → Task<JsonNode?>What one format converts to, with the credit cost of each conversion. Public.
Example
var mp4 = await rc.Operations.ForInputAsync("mp4");
foreach (var o in mp4!["outputs"]!.AsArray())
Console.WriteLine($"{o!["format"]} {o["credits"]}");{
"format": "mp4",
"category": "video",
"outputs": [
{ "format": "mp3", "category": "audio", "engine": "ffmpeg", "credits": 1 },
{ "format": "gif", "category": "image", "engine": "ffmpeg", "credits": 4 },
…
]
}Parameters
inputstringThe input format, e.g. "mp4".Required
Engines for a pair
rc.Operations.ForPairAsync(string input, string output, CancellationToken ct = default) → Task<JsonNode?>The engines for one conversion and the options its convert task accepts, e.g. bitrate or quality. Public.
Example
var pair = await rc.Operations.ForPairAsync("mp4", "mp3");
foreach (var opt in pair!["engines"]![0]!["options"]!.AsArray())
Console.WriteLine(opt!["name"]);{
"input": "mp4",
"output": "mp3",
"engines": [
{ "name": "ffmpeg", "credits": 1,
"options": [
{ "name": "audioBitrate", "type": "string",
"description": "Target audio bitrate in kbps.",
"supported_values": ["32k", "48k", "64k", "80k", …] },
…
] }
]
}Parameters
inputstringThe input format, e.g. "mp4".RequiredoutputstringThe output format, e.g. "mp3".Required
Account
Credits and team
rc.MeAsync(CancellationToken ct = default) → Task<JsonNode?>The account, team and credit balance behind the API key.
Example
var me = await rc.MeAsync();
Console.WriteLine(me!["credits"]!["total_remaining"]);{
"user": { "email": "[email protected]", "full_name": "Ada Lovelace" },
"team": { "name": "Acme" },
"credits": { "mode": "wallet", "total_remaining": 4820 }
}Webhooks
Verify a signature
Webhooks.Verify(byte[] | string rawBody, string? signature, string secret) → boolChecks that a webhook delivery really came from RunConvert: an HMAC-SHA256 of the raw request body with your webhook secret, compared with the X-RunConvert-Signature header in constant time.
Example
bool ok = Webhooks.Verify(body, request.Headers["X-RunConvert-Signature"], secret);Parameters
rawBodybyte[] | stringThe raw request body, exactly as received (not parsed JSON).Requiredsignaturestring?The X-RunConvert-Signature header.RequiredsecretstringYour webhook's signing secret.Required
Parse an event
Webhooks.ConstructEvent(byte[] rawBody, string? signature, string secret) → JsonNodeVerifies the signature and parses the event in one step. Fails if the signature is wrong.
Throws ArgumentException when the signature doesn't match: answer 400 and ignore the request.
Example
app.MapPost("/webhooks/runconvert", async (HttpRequest req) =>
{
using var ms = new MemoryStream();
await req.Body.CopyToAsync(ms);
try
{
var ev = Webhooks.ConstructEvent(ms.ToArray(), req.Headers["X-RunConvert-Signature"],
Environment.GetEnvironmentVariable("RUNCONVERT_WEBHOOK_SECRET")!);
if ((string?)ev["event"] == "job.finished") Console.WriteLine($"done {ev["job"]!["id"]}");
return Results.Ok();
}
catch (ArgumentException) { return Results.BadRequest(); }
});{
"event": "job.finished",
"job": { "id": "job_01hx4k9m2p7w", "status": "finished", … }
}Parameters
rawBodybyte[]The raw request body, exactly as received (not parsed JSON).Requiredsignaturestring?The X-RunConvert-Signature header.RequiredsecretstringYour webhook's signing secret.Required
More
Errors
Every failure is a typed error. The API's code tells you what happened, for example BILLING_INSUFFICIENT_CREDITS, UNAUTHORIZED or INVALID_DATA.
Example
try
{
await rc.ConvertAsync("report.docx", new ConvertOptions { To = "pdf", OutDir = "out" });
}
catch (JobFailedException e)
{
Console.WriteLine($"conversion failed: {e.Task?.Reason}");
}
catch (RunConvertException e)
{
Console.WriteLine($"{e.Status} {e.Code} {e.Message}");
}422 BILLING_INSUFFICIENT_CREDITS Insufficient credits.Error types
RunConvertExceptionclassThe API said no: Status (HTTP status), Code (e.g. BILLING_INSUFFICIENT_CREDITS), Message.JobFailedExceptionclassThe job ended in error: Job, and Task with Code, Reason and Message.WaitTimeoutExceptionclassWaitAsync ran past its timeout: Job is the job as last seen.
Retries and timeouts
Network errors, rate limits (429) and server errors (5xx) are retried twice with backoff, honouring Retry-After. Creating a job is only retried when the request never reached the API, so a job is never created twice.
Example
using var rc = new RunConvertClient(maxRetries: 4, timeout: TimeSpan.FromSeconds(30));