Pdf4me.Client 2.0.0

Pdf4me.Client

.NET client for the PDF4me API. Convert, optimize, merge, split, stamp, OCR and extract content from documents with async methods and typed results.

Targets .NET 8, 9 and 10, and .NET Standard 2.0 for .NET Framework 4.6.2 and later. Requires a PDF4me API key.

Upgrading from 1.x? Version 2.0 is a rewrite on the PDF4me API v2 and nothing from 1.x keeps working. See Migrating from 1.x.

Installation

dotnet add package Pdf4me.Client

Quick start

Set your API key in the environment:

export PDF4ME_API_KEY="your-api-key"

This program uploads input.pdf for optimization and saves the result as optimized.pdf:

using Pdf4me.Client;

var apiKey = Environment.GetEnvironmentVariable("PDF4ME_API_KEY")
    ?? throw new InvalidOperationException("Set PDF4ME_API_KEY first.");

using var client = new Pdf4meClient(apiKey);
var result = await client.OptimizeAsync(
    File.ReadAllBytes("input.pdf"), docName: "input.pdf", profile: OptimizeProfile.Max);
File.WriteAllBytes("optimized.pdf", result);

Create one client and reuse it for every call: it keeps a pooled connection, so a client per call would set up TLS every time. Dispose it when you are done.

Using actions

Every action is an async method on Pdf4meClient, named after its endpoint: /api/v2/ConvertOcrPdf is ConvertOcrPdfAsync. The first parameters are what the action works on; everything else is optional, so pass it by name:

var searchable = await client.ConvertOcrPdfAsync(
    scan, language: "English", qualityType: QualityType.Draft);

var numbered = await client.AddPageNumberAsync(
    pdf, pageNumberFormat: "Page # of {1}", alignX: AddPageNumberAlignX.Center);

Documents are a DocumentSource: the file's bytes, or a string the API fetches itself - a pdf4meblobid://<id> for an uploaded blob, or an https URL. Both convert implicitly, so pass either straight in. A string is never read as a local path; read the file and pass its bytes.

Results. Actions that produce a document return its byte[]. Actions that answer with data return a typed model, such as DocMetadata from GetPdfMetadataAsync or ReadBarcodesRes from ReadBarcodesAsync.

Options that are objects - ConvertToPdfAction, ImageAction, the result models - are generated from the API description and live in Pdf4me.Client.Generated.Models. Enums an action takes have short names in Pdf4me.Client (QualityType, AlignX, SplitAction, ...); the few enums whose generated name is already short (DocType, ImageTypeExtract, ...) are used straight from Pdf4me.Client.Generated.Models.

using Pdf4me.Client;
using Pdf4me.Client.Generated.Models;

var pages = await client.CreateImagesAsync(
    pdf, new ImageAction { ImageExtension = ImageExtension.Png }, pageNrs: "1");

Every action also takes:

• extra - additional request fields, for options the API description does not list yet. They are sent as they are, next to the action's own.
• maxWait - how long to wait for this call's queued job; see below.
• cancellationToken - cancels the request and any polling.

Examples

Each snippet assumes using Pdf4me.Client;, using Pdf4me.Client.Generated.Models; and a client created as in the quick start.

A document in, a document out - most actions:

byte[] pdf = File.ReadAllBytes("input.pdf");

byte[] compressed = await client.OptimizeAsync(pdf, profile: OptimizeProfile.Web);
byte[] protectedPdf = await client.ProtectAsync(pdf, password: "secret", pdfPermission: ProtectPdfPermission.All);
byte[] wordFile = await client.ConvertPdfToWordAsync(pdf, docName: "input.pdf");

A blob or URL instead of bytes - the API fetches it itself:

byte[] fromUrl = await client.OptimizeAsync("https://example.com/report.pdf");
byte[] fromBlob = await client.OptimizeAsync("pdf4meblobid://<id>");

Several documents - merged in the order given:

byte[] merged = await client.MergeAsync([File.ReadAllBytes("a.pdf"), File.ReadAllBytes("b.pdf")]);

No document - the input is text or a URL:

byte[] qrCode = await client.CreateBarcodeAsync("https://pdf4me.com", barcodeType: CreateBarcodeBarcodeType.QRCode);
byte[] webPage = await client.ConvertUrlToPdfAsync("https://example.com");

Data instead of a file - the result is a typed model:

DocMetadata metadata = await client.GetPdfMetadataAsync(pdf);
Console.WriteLine($"{metadata.PageCount} pages, PDF {metadata.PdfVersion}");

ReadBarcodesRes scan = await client.ReadBarcodesAsync(pdf);
foreach (var barcode in scan.Barcodes ?? [])
    Console.WriteLine($"page {barcode.Page}: {barcode.Value}");

Some answers have no fixed shape - the AI document parser decides its own - so everything they return is in the model's AdditionalData:

var parsed = await client.AiDocumentParserAsync(File.ReadAllBytes("invoice.pdf"), "invoice parser");
foreach (var (field, value) in parsed.AdditionalData)
    Console.WriteLine($"{field}: {value}");

Long jobs and cancelling - wait longer for one call, and stop it from your side:

using var cancel = new CancellationTokenSource(TimeSpan.FromMinutes(20));
byte[] searchable = await client.ConvertOcrPdfAsync(
    File.ReadAllBytes("scan.pdf"), language: "English",
    maxWait: TimeSpan.FromMinutes(20), cancellationToken: cancel.Token);

An option the API description does not list yet - send it through extra:

byte[] result = await client.OptimizeAsync(pdf, extra: new Dictionary<string, object> { ["someNewOption"] = true });

Client configuration and errors

using var client = new Pdf4meClient(apiKey, new Pdf4meClientOptions
{
    BaseUrl = Pdf4meClient.DefaultBaseUrl,       // https://api.pdf4me.com
    Timeout = TimeSpan.FromSeconds(100),         // each HTTP request
    MaxWait = TimeSpan.FromMinutes(5),           // waiting for one queued job
    Logger = loggerFactory.CreateLogger<Pdf4meClient>(),
});

Every action is submitted as an asynchronous job: a call returns the finished result whether the server answered at once or queued the work, polling it in between as the server suggests. MaxWait limits that wait; pass maxWait: to an action to change it for that call. The OCR actions (ConvertOcrPdfAsync, ImageExtractTextAsync) wait at least 10 minutes (DefaultOcrMaxWait), or longer if MaxWait is higher.

Errors. A refused or failed request throws Pdf4meException (in Pdf4me.Client.Generated.Models) with:

A job still running when the wait runs out throws TimeoutException. Invalid arguments, such as an empty document, throw ArgumentException before any request is sent.

try
{
    byte[] result = await client.OptimizeAsync(pdf);
}
catch (Pdf4meException e)
{
    // The API refused or failed the request: say what it said.
    Console.Error.WriteLine($"PDF4me returned {e.ResponseStatusCode}: {e.Message} (trace {e.TraceId})");
}
catch (TimeoutException e)
{
    // The job was still running when maxWait ran out.
    Console.Error.WriteLine(e.Message);
}

Logging. Give the client an ILogger (from Microsoft.Extensions.Logging) to see every request, response, queued job and poll at Debug. Nothing logged carries the API key or a document's content. In a console app, with the Microsoft.Extensions.Logging.Console package:

using Microsoft.Extensions.Logging;

using var loggerFactory = LoggerFactory.Create(logging => logging
    .AddSimpleConsole(console => console.SingleLine = true)
    .SetMinimumLevel(LogLevel.Debug));
using var client = new Pdf4meClient(apiKey, new Pdf4meClientOptions
{
    Logger = loggerFactory.CreateLogger<Pdf4meClient>(),
});

In ASP.NET Core, or any app using dependency injection, register one client for the whole app; the logger comes from the app's own logging setup:

builder.Services.AddSingleton(services => new Pdf4meClient(
    builder.Configuration["Pdf4me:ApiKey"]!,
    new Pdf4meClientOptions { Logger = services.GetRequiredService<ILogger<Pdf4meClient>>() }));

Available sections

The client provides 106 actions, grouped by the sections of the API documentation; each section's actions live in their own file.

The same actions, with the same names and defaults, are in the Python and JavaScript clients.

All actions

Every action, by section. The method links to its documentation page where the docs have one; hover over a method in your editor for its parameters.

AI Document Extraction (14)

Barcode (7)

Convert (13)

Edit (7)

Excel (1)

Extract (8)

Find Search (2)

Forms (2)

Generate (6)

Image (13)

Merge & Split (5)

Optimize (1)

Organize (5)

PDF (16)

PDF4me (1)

Security (2)

Word (2)

ZUGFeRD (1)

Migrating from 1.x

Version 2.0 replaces the whole library. Upgrading is not a drop-in change:

• It talks to API v2. 1.x called the v1 endpoints (/Optimize/OptimizeByProfile and so on); 2.0 calls /api/v2/..., with the options the v2 documentation describes.
• The singleton and the per-area clients are gone. Pdf4me.Instance.Init(token) and Pdf4me.Instance.OptimizeClient become one new Pdf4meClient(apiKey) with every action as a method on it.
• The namespace is Pdf4me.Client, not Pdf4meClient.
• Newtonsoft.Json is no longer a dependency. The vulnerable 12.0.3 that 1.x pulled in goes with it.
• Errors are one type. Pdf4meApiException and Pdf4meBackendException become Pdf4meException.
• .NET Framework 4.5.2 and 4.6.1 are no longer supported. The minimum is 4.6.2, through .NET Standard 2.0.

Step by step:

1. Update the package: dotnet add package Pdf4me.Client --version 2.0.0. Your API key stays the same.
2. Replace using Pdf4meClient; with using Pdf4me.Client;, and add using Pdf4me.Client.Generated.Models; where you use option or result models or catch Pdf4meException.
3. Replace Pdf4me.Instance.Init(token) with one Pdf4meClient created at start-up and reused; dispose it on shutdown.
4. Change each call to the client method from the table, passing options by name.
5. Change catch (Pdf4meApiException) and catch (Pdf4meBackendException) to catch (Pdf4meException); the status code is ResponseStatusCode.

Before, with 1.x:

using Pdf4meClient;

Pdf4me.Instance.Init(token);
try
{
    byte[] optimized = await Pdf4me.Instance.OptimizeClient
        .OptimizeByProfileAsync(File.ReadAllBytes("input.pdf"), PdfOptimizationProfile.Max);
    byte[] merged = await Pdf4me.Instance.MergeClient
        .Merge2PdfsAsync(File.ReadAllBytes("a.pdf"), File.ReadAllBytes("b.pdf"));
}
catch (Pdf4meBackendException e)
{
    Console.Error.WriteLine(e.Message);
}

After, with 2.0:

using Pdf4me.Client;
using Pdf4me.Client.Generated.Models;

using var client = new Pdf4meClient(token);
try
{
    byte[] optimized = await client.OptimizeAsync(File.ReadAllBytes("input.pdf"), profile: OptimizeProfile.Max);
    byte[] merged = await client.MergeAsync([File.ReadAllBytes("a.pdf"), File.ReadAllBytes("b.pdf")]);
}
catch (Pdf4meException e)
{
    Console.Error.WriteLine($"{e.ResponseStatusCode}: {e.Message}");
}

The table covers the common calls; the sections table above says where to find everything else, and each method's documentation summary matches its docs page.

Contributing

Issues and pull requests are welcome on GitHub.

src/Pdf4me.Client/Generated/ is generated by Kiota from the PDF4me OpenAPI description and is replaced whole on every regeneration, so please open an issue for anything wrong in that tree rather than patching it. The client and the section files around it are hand-written and are the right place for a pull request.

dotnet build                 # the library for every target, and the tests
dotnet test                  # against a stub server: no API key, no network
dotnet pack -c Release src/Pdf4me.Client   # the NuGet package, into src/Pdf4me.Client/bin/Release

The tests call every action once against a stub server and check what it sends, so a new action is covered as soon as it exists. They also check that each short-named enum still matches the generated enum it mirrors, which a regeneration can change.

Support

• API documentation: https://docs.pdf4me.com/pdf4me-api/
• Issues: https://github.com/pdf4me/pdf4me-clientapi-dotnet/issues
• Email: support-dev@pdf4me.com

Quote the TraceId from a Pdf4meException when reporting an API failure.

License

MIT