HuntAPI Python SDK

The official Python 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 methods, one per documented endpoint, with blocking and asyncio clients built on HTTPX, plus a generic request().

Requirements

• Python 3.11 or newer

Installation

pip install huntapi

Get your API key

Sign up for HuntAPI or sign in, then copy your API key from the dashboard. The client reads the HUNTAPI_API_KEY environment variable when no key is passed.

Quick start

import os

from huntapi import HuntApiClient

with HuntApiClient(os.environ["HUNTAPI_API_KEY"]) as client:
    response = client.media_metadata(query="https://www.youtube.com/watch?v=Z5YP8kznWZs")
    print(response.data)

Keyword arguments mirror the API reference. Python keywords get a trailing underscore (from_=), and the wire name is used on the request.

Async jobs

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

submitted = client.video_download(query="https://www.youtube.com/watch?v=Z5YP8kznWZs", video_quality="720p")
job = client.wait_for_job(
    submitted.data["job_id"],
    on_progress=lambda j: print(j["status"], j.get("progress")),
)
print(job.data)

Async I/O

import asyncio

from huntapi import AsyncHuntApiClient


async def main() -> None:
    async with AsyncHuntApiClient() as client:
        response = await client.media_metadata(query="https://www.youtube.com/watch?v=Z5YP8kznWZs")
        print(response.data)


asyncio.run(main())

GET or POST

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

from huntapi import RequestOptions

client.audio_download(query="test", request_options=RequestOptions(method="POST"))

None values are omitted, False and 0 are sent, and sequences repeat the parameter name.

Any endpoint

response = client.request("GET", "/v1/usage")

Errors

from huntapi import HuntApiAPIError

try:
    client.media_metadata(query="https://www.youtube.com/watch?v=Z5YP8kznWZs")
except HuntApiAPIError as error:
    print(error.status, error, error.response_body)

All of them extend HuntApiError.

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.

client = HuntApiClient(max_retries=5, retry_delay=0.5)

# or for one request
client.media_metadata(query="https://www.youtube.com/watch?v=Z5YP8kznWZs", request_options=RequestOptions(max_retries=0))

Batch requests

batch() runs a function per item on 10 threads (concurrency) and returns one BatchResult per item, in input order. A failing item never stops the others. AsyncHuntApiClient.batch() does the same with asyncio.

inputs = ["https://www.youtube.com/watch?v=Z5YP8kznWZs", "https://www.youtube.com/watch?v=jNQXAC9IVRw"]
results = client.batch(inputs, lambda query: client.media_metadata(query=query), concurrency=5)

for result in results:
    if result.ok:
        print(result.value.data)
    else:
        print(inputs[result.index], result.error)

Timeouts and custom HTTPX clients

import httpx

from huntapi import HuntApiClient, RequestOptions

client = HuntApiClient(timeout=60)  # seconds, default 120, None disables
client.media_metadata(query="https://www.youtube.com/watch?v=Z5YP8kznWZs", request_options=RequestOptions(timeout=30))

# Bring your own HTTPX client (proxies, limits, event hooks…). You keep ownership of it.
http_client = httpx.Client(proxy="http://localhost:8080")
client = HuntApiClient(http_client=http_client)

Endpoints

6 methods, generated from the OpenAPI document.

License

MIT — see LICENSE.