Skip to content

.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

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_KEY

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

Convert a file
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.pdf
out/report.pdf

Convert

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));
out/report.pdf

Parameters

  • fileOrUrlstringA local path or an http(s) URL (imported by RunConvert).Required
  • TostringThe target format, e.g. "pdf" or "mp3".Required
  • Fromstring?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");

Parameters

  • tasksIDictionary<string, object?>Named task definitions. Names use letters, digits, - or _ (up to 64 characters).Required
  • tagstring?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

Get a job
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

Finished jobs
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

Loop over all jobs
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");

Parameters

  • idstringThe job's ID.Required
  • timeoutTimeSpan?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

Cancel
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) → Task

Deletes a job and its files.

Example

Delete
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

List results
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) → Task

Sends a file to an import/direct/upload task before its deadline. Use it with a job you created yourself.

Example

Upload
await rc.Files.UploadAsync(job.Task("upload")!.UploadUrl!, "image.png");

Parameters

  • uploadUrlstringThe upload task's UploadUrl: job.Task("upload")!.UploadUrl.Required
  • path / streamstring | StreamA local path or a stream.Required
  • filenamestring?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

Download
foreach (var f in job.ExportedFiles())
    Console.WriteLine(await rc.Files.DownloadAsync(f, "out"));
out/report.pdf

Parameters

  • fileResultFileA result file from a job's export task, or its URL.Required
  • dirstringThe 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

Audio formats
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

What MP4 converts to
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

MP4 → MP3 options
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".Required
  • outputstringThe 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

Credits left
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) → bool

Checks 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

Verify
bool ok = Webhooks.Verify(body, request.Headers["X-RunConvert-Signature"], secret);

Parameters

  • rawBodybyte[] | stringThe raw request body, exactly as received (not parsed JSON).Required
  • signaturestring?The X-RunConvert-Signature header.Required
  • secretstringYour webhook's signing secret.Required

Parse an event

Webhooks.ConstructEvent(byte[] rawBody, string? signature, string secret) → JsonNode

Verifies 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

Minimal API
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).Required
  • signaturestring?The X-RunConvert-Signature header.Required
  • secretstringYour 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

Handle errors
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

Tune retries
using var rc = new RunConvertClient(maxRetries: 4, timeout: TimeSpan.FromSeconds(30));

Like RunConvert? Set us as a preferred source on Google.

Add to Preferred Sources