HuntApi 0.1.0

HuntAPI .NET SDK

The official .NET SDK for the HuntAPI media download API.

Download video and audio from public media URLs, or extract their metadata, with one async REST API.

The SDK exposes 6 typed async methods, one per documented endpoint (with required properties checked at compile time), plus a generic RequestAsync.

Requirements

• .NET 8 or newer

Installation

dotnet add package HuntApi

Get your API key

Sign up for HuntAPI or sign in, then copy your API key from the dashboard. new HuntApiClient() reads the HUNTAPI_API_KEY environment variable.

Quick start

using HuntApi;

using var client = new HuntApiClient();
var response = await client.MediaMetadataAsync(new MediaMetadataParams { Query = "https://www.youtube.com/watch?v=Z5YP8kznWZs" });
Console.WriteLine(response.Json);

Parameter classes mirror the API reference. Use response.Deserialize<MyType>() to map the JSON onto your own types.

Async jobs

Download endpoints are asynchronous: they return a job_id, and jobs can run for up to 12 hours. WaitForJobAsync polls GET /v1/jobs/{id} until a terminal status (CompletedJob, Error, NotFound, BadRequest):

var submitted = await client.VideoDownloadAsync(new VideoDownloadParams { Query = "https://www.youtube.com/watch?v=Z5YP8kznWZs", VideoQuality = "720p" });
var job = await client.WaitForJobAsync(
    submitted.Json.GetProperty("job_id").GetString()!,
    onProgress: j => Console.WriteLine($"{j.GetProperty("status")} {j.GetProperty("progress")}%"));

GET or POST

Methods use GET when the endpoint supports it (query string). POST sends the same parameters as JSON:

await client.AudioDownloadAsync(new AudioDownloadParams { Query = "test" }, new RequestOptions { Method = "POST" });

Any endpoint

var response = await client.RequestAsync("GET", "/v1/usage");

Errors

try
{
    await client.MediaMetadataAsync(new MediaMetadataParams { Query = "https://www.youtube.com/watch?v=Z5YP8kznWZs" });
}
catch (HuntApiApiException exception)
{
    Console.Error.WriteLine($"{exception.StatusCode}: {exception.Message}");
}

All of them derive from HuntApiException. Caller cancellation surfaces as OperationCanceledException.

Retries

Requests are retried up to 3 times after a network error, a 408, 500, 502, 503 or 504, or a rate limit — which the API returns as 401 (or 429) with a Rate limit exceeded message. Per-key quota errors (…: quota daily) are not retried, nor are 400, 402, 404 or client-side timeouts. The delay starts at 1 second and grows 1.5× per retry (capped at 30 seconds); a Retry-After header wins.

using var client = new HuntApiClient(new HuntApiClientOptions { MaxRetries = 5, RetryDelay = TimeSpan.FromMilliseconds(500) });
await client.MediaMetadataAsync(new MediaMetadataParams { Query = "https://www.youtube.com/watch?v=Z5YP8kznWZs" }, new RequestOptions { MaxRetries = 0 }); // one request without retries

Batch requests

BatchAsync runs a function per item with at most 10 in flight (concurrency) and returns one BatchResult per item, in input order. A failing item never stops the others.

string[] inputs = { "https://www.youtube.com/watch?v=Z5YP8kznWZs", "https://www.youtube.com/watch?v=jNQXAC9IVRw" };
var results = await client.BatchAsync(inputs, (value, ct) =>
    client.MediaMetadataAsync(new MediaMetadataParams { Query = value }, cancellationToken: ct), concurrency: 5);
foreach (var result in results)
{
    if (result.Ok)
    {
        Console.WriteLine(result.Value!.Json);
    }
    else
    {
        Console.Error.WriteLine($"{inputs[result.Index]}: {result.Error!.Message}");
    }
}

Configuration

using var client = new HuntApiClient(new HuntApiClientOptions
{
    ApiKey = Environment.GetEnvironmentVariable("HUNTAPI_API_KEY"),
    Timeout = TimeSpan.FromSeconds(60), // default 120 s
    HttpClient = myHttpClient,           // optional, you keep ownership
});

Endpoints

6 methods, generated from the OpenAPI document.

License

MIT — see LICENSE.