C# SDK

Needs .NET 10. Create one EtchvClient and reuse it; it is safe to use from many threads at once. Dispose of it when your app shuts down. MIT licensed.

Install

# From your project folder: clone next to it, not inside it
git clone --branch v1.0.0 https://github.com/etchv-labs/csharp-sdk.git ../etchv-csharp-sdk
dotnet add reference ../etchv-csharp-sdk/src/Etchv/Etchv.csproj

Install from the tagged source on GitHub. There is no official NuGet package.

Embed a file

Set ETCHV_API_KEY on your server. This example needs an API key with the watermarks:embed and watermarks:detect scopes, an active plan and available credits.

using Etchv;

using var client = new EtchvClient(Environment.GetEnvironmentVariable("ETCHV_API_KEY")!);
var key = await client.GetApiKeyInfoAsync(); // OrganizationId, KeyId, Scopes; no credits used
var result = await client.EmbedImageAsync(await File.ReadAllBytesAsync("photo.jpg"),
    new Dictionary<string, object?> { ["asset"] = "photo-123" },
    new RequestOptions(Filename: "photo.jpg"));
await File.WriteAllBytesAsync(result.Filename, result.Bytes);
var detection = await client.DetectImageAsync(result.Bytes, new RequestOptions(Filename: result.Filename));
Console.WriteLine($"{detection.Watermarked} {detection.WatermarkId} {detection.Confidence:P0}");

GetApiKeyInfoAsync checks your API key and uses no credits. Save the output bytes as they are. Do not re-encode the file.

Images, documents and video

For every media type, result.Bytes holds the watermarked file in its original format. Embedding also returns WatermarkId, RequestId, ContentType, Filename, AssetId, SourceAssetId and StorageDeliveryId.

Detection returns the watermark it found, a confidence score, and results for each frame or page. It does not return the JSON you sent when you embedded the file. Result fields · Credits.

Retries and recovery

Embedding and video detection retry and check job status for you. Image and PDF detection do not. Before you upload, save an idempotency key (a value you choose so a retry isn't run twice). With it, you can recover the request even after your program restarts.

try
{
    var output = await client.GetEmbedResultAsync(requestId);
}
catch (EtchvException e) when (e.StatusCode == 410)
{
    // The saved result expired or its asset was deleted (e.ErrorStatus).
}
catch (EtchvException e)
{
    logger.LogError("Etchv {Status} request {RequestId}", e.StatusCode, e.RequestId);
}

Asset library

These calls use no credits. Downloads need the assets:read scope, and edits need assets:write. Deleting needs assets:delete and the owner or admin role.

var page = await client.ListAssetsAsync(new AssetListOptions(Kind: "watermarked"));
foreach (var item in page.Items) {
    var asset = await client.GetAssetAsync(item.Id);
    var updated = await client.UpdateAssetAsync(asset.Id, asset.Version,
        new Dictionary<string, object?> { ["metadata"] = new { campaign = "spring" } });
    if (updated.FileAvailable) {
        byte[] bytes = await client.DownloadAssetAsync(updated.Id);
    }
}
// Use NextCursor with the same filters to continue listing.

Async jobs and webhooks

To start a job without waiting for the result, call SubmitEmbedAsync or SubmitDetectionAsync. Set the media type to images, documents or videos. These calls return a JobReceipt. On other methods, the Async suffix only means C# async I/O. It does not mean a background job on the server.

Check an embedding job with GetJobAsync(requestId) and a detection job with GetJobAsync(requestId, detect: true).

var job = await client.SubmitEmbedAsync("documents", pdfBytes,
    new Dictionary<string, object?> { ["delivery"] = "delivery_001" },
    new RequestOptions("document.pdf", "delivery_001"), webhookId);
var status = await client.GetJobAsync(job.RequestId);
if (status.Status == "succeeded")
{
    var output = await client.GetEmbedResultAsync(job.RequestId);
}

using var buffer = new MemoryStream();
await request.Body.CopyToAsync(buffer);
if (!WebhookSignature.Verify(buffer.ToArray(), request.Headers["X-Etchv-Timestamp"],
        request.Headers["X-Etchv-Signature"], signingSecret))
    return Results.Unauthorized();
// Parse JSON, check id == X-Etchv-Event-ID, deduplicate, enqueue work, then return 2xx.

GPU processing

On Business or Enterprise plans, pass new RequestOptions(Accelerator: Accelerator.Gpu). GPU processing uses 3× the credits. If processing falls back to CPU, it uses normal credits. result.Accelerator shows which one was used. See GPU processing.

Choose where results are stored

Connect your bucket. Then pass its destination ID and, if you like, an object key (the file's path in the bucket). Leave both out to use Etchv storage.

var job = await client.SubmitEmbedAsync("documents", pdfBytes,
    new Dictionary<string, object?> { ["recipient"] = "customer-123" },
    new RequestOptions(Filename: "report.pdf", IdempotencyKey: "report-export-001",
        StorageDestinationId: destinationId, StorageKey: "reports/watermarked.pdf"));
// After the watermark job reports succeeded:
var delivery = await client.GetStorageDeliveryAsync((await client.GetJobAsync(job.RequestId)).StorageDeliveryId!);
if (delivery.Status == "failed") await client.RetryStorageDeliveryAsync(delivery.Id);