huntapi

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 6, 2026 License: MIT Imports: 18 Imported by: 0

README

HuntAPI Go SDK

The official Go 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, plus a generic Request(). It has no dependencies outside the standard library.

Requirements

  • Go 1.22 or newer

Installation

go get github.com/huntapi/huntapi-go

Get your API key

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

Quick start

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/huntapi/huntapi-go"
)

func main() {
	client, err := huntapi.NewClient("", nil) // reads HUNTAPI_API_KEY
	if err != nil {
		log.Fatal(err)
	}
	ctx := context.Background()
	response, err := client.MediaMetadata(ctx, &huntapi.MediaMetadataParams{Query: "https://www.youtube.com/watch?v=Z5YP8kznWZs"})
	if err != nil {
		log.Fatal(err)
	}
	data, err := response.Map()
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(data)
}

Parameter structs mirror the API reference. Required fields are plain values; optional fields are pointers — use huntapi.String, huntapi.Float, huntapi.Int and huntapi.Bool.

Decode into your own types with response.Decode(&value).

Async jobs

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

submitted, err := client.VideoDownload(ctx, &huntapi.VideoDownloadParams{Query: "https://www.youtube.com/watch?v=Z5YP8kznWZs", VideoQuality: huntapi.String("720p")})
if err != nil {
	log.Fatal(err)
}
var accepted struct{ JobID string `json:"job_id"` }
if err := submitted.Decode(&accepted); err != nil {
	log.Fatal(err)
}
job, err := client.WaitForJob(ctx, accepted.JobID, &huntapi.WaitForJobOptions{
	OnProgress: func(job map[string]any) { fmt.Println(job["status"], job["progress"]) },
})

GET or POST

Methods use GET when the endpoint supports it (parameters in the query string); WithMethod("POST") sends them as a JSON body.

response, err := client.AudioDownload(ctx, &huntapi.AudioDownloadParams{Query: "test"}, huntapi.WithMethod("POST"))

Any endpoint

response, err := client.Request(ctx, "GET", "/v1/usage", nil)

Errors

response, err := client.MediaMetadata(ctx, &huntapi.MediaMetadataParams{Query: "https://www.youtube.com/watch?v=Z5YP8kznWZs"})
if apiError, ok := huntapi.IsAPIError(err); ok {
	log.Printf("HTTP %d: %s", apiError.StatusCode, apiError.Message)
}
Error When
*ConfigurationError Missing API key, invalid options or unsupported method.
*SerializationError A required parameter is missing or a value can't be sent.
*TransportError Network failure, timeout or cancelled context (errors.Is(err, context.DeadlineExceeded)).
*APIError Non-2xx status (StatusCode, Message, Response).
*ResponseDecodingError A success response could not be decoded.

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, err := huntapi.NewClient("", &huntapi.ClientOptions{
	MaxRetries: 5,                      // negative disables retries
	RetryDelay: 500 * time.Millisecond,
})

// or for one request
response, err := client.MediaMetadata(ctx, &huntapi.MediaMetadataParams{Query: "https://www.youtube.com/watch?v=Z5YP8kznWZs"}, huntapi.WithMaxRetries(0))

Batch requests

huntapi.Batch runs a function per item with at most 10 calls in flight and returns one BatchResult per item, in input order. A failing item never stops the others.

inputs := []string{"https://www.youtube.com/watch?v=Z5YP8kznWZs", "https://www.youtube.com/watch?v=jNQXAC9IVRw"}
results := huntapi.Batch(ctx, inputs, 5, func(ctx context.Context, value string) (*huntapi.Response, error) {
	return client.MediaMetadata(ctx, &huntapi.MediaMetadataParams{Query: value})
})
for _, result := range results {
	if result.Err != nil {
		log.Printf("%s: %v", inputs[result.Index], result.Err)
		continue
	}
	fmt.Println(string(result.Value.Body))
}
Constant Default Description
DefaultConcurrency 10 Tasks run at the same time by batch
DefaultTimeout 120 * time.Second Request timeout
MaxRetries 3 Retry attempts after a network error, a 408/5xx or a rate limit
RetryBackoffFactor 1.5 Exponential backoff multiplier
DefaultRetryDelay time.Second Delay before the first retry

Timeouts and custom HTTP clients

client, err := huntapi.NewClient("", &huntapi.ClientOptions{
	Timeout:    60 * time.Second, // default 120 s; negative disables
	HTTPClient: &http.Client{Transport: myTransport},
})

Every method also honours the deadline and cancellation of the context.Context you pass.

Endpoints

6 methods, generated from the OpenAPI document.

Method HTTP Description
AudioDownload GET / POST /v1/audio/download Download audio from a URL via HuntAPI and receive a job id.
Jobs GET /v1/jobs/{id} Poll status, progress (0–100), and result of an async HuntAPI job.
MediaMetadata GET /v1/media/metadata Extract metadata from a media URL without downloading the file.
Stats GET /v1/stats Infrastructure health for an engine or endpoint over the last hour. Not scoped to your account or tenant. Enabled per account: HTTP 403 mea…
Usage GET /v1/usage Retrieve real-time usage statistics and credit balance for your Huntapi account.
VideoDownload GET / POST /v1/video/download Video Download

License

MIT — see LICENSE.

Documentation

Overview

Package huntapi is the official Go SDK for the HuntAPI API (https://www.huntapi.com).

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

Create one client and reuse it: 

client, err := huntapi.NewClient("", nil) // reads HUNTAPI_API_KEY
response, err := client.MediaMetadata(ctx, ...)

Every documented endpoint has a typed method; Client.Request reaches any other path.

Index

Constants

View Source 
const (
	// DefaultBaseURL is the production API origin.
	DefaultBaseURL = "https://api.huntapi.com"
	// DefaultTimeout bounds every request unless ClientOptions.Timeout says otherwise.
	DefaultTimeout = 120 * time.Second
	// APIKeyEnvironmentVariable is read when NewClient receives an empty API key.
	APIKeyEnvironmentVariable = "HUNTAPI_API_KEY"
	// DefaultConcurrency is the number of tasks Batch runs at the same time.
	DefaultConcurrency = 10
	// MaxRetries is the default number of retries after a network error or a 408, 429, 500, 502, 503 or 504.
	MaxRetries = 3
	// RetryBackoffFactor multiplies the delay before each new retry (a Retry-After header wins).
	RetryBackoffFactor = 1.5
	// DefaultRetryDelay is the delay before the first retry.
	DefaultRetryDelay = time.Second
	// MaxRetryDelay caps the delay between two attempts.
	MaxRetryDelay = 30 * time.Second
)
View Source 
const Version = "0.1.0"

Version is the SDK version sent in the User-Agent header.

Variables

View Source 
var JobTerminalStatuses = []string{"CompletedJob", "Error", "NotFound", "BadRequest"}

JobTerminalStatuses are the job statuses WaitForJob stops on.

Functions

func Bool 

func Bool(v bool) *bool

Bool returns a pointer to v, for optional boolean parameters.

func Float 

func Float(v float64) *float64

Float returns a pointer to v, for optional number parameters.

func Int 

func Int(v int64) *int64

Int returns a pointer to v, for optional integer parameters.

func String 

func String(v string) *string

String returns a pointer to v, for optional parameters.

Types

type APIError 

type APIError struct {
	StatusCode int
	// Message is the "error" (or "message") field of the JSON body, when present.
	Message  string
	Response *Response
}

APIError is returned for non-2xx responses.

func IsAPIError 

func IsAPIError(err error) (*APIError, bool)

IsAPIError reports whether err is an *APIError and returns it.

func (*APIError) Error 

func (e *APIError) Error() string

type AudioDownloadParams 

type AudioDownloadParams struct {
	// URL to download audio from.
	Query string `json:"query" api:"query,required"`
	// Desired download type. Supported values: audio (default). Default: "audio".
	DownloadType *string `json:"download_type" api:"download_type"`
	// Maximum duration of the downloaded content in seconds. If the audio is longer than this value, only the content up to this duration will be downloaded.
	MaxDuration *float64 `json:"max_duration" api:"max_duration"`
	// Desired audio quality. Default: "best".
	AudioQuality *string `json:"audio_quality" api:"audio_quality"`
	// Desired output format for the audio. Default: "mp3".
	AudioFormat *string `json:"audio_format" api:"audio_format"`
	// URL of the webhook where results will be sent. When specified, the system will attempt to send the response to this URL up to 3 times with a 5-second delay between each attempt. The results will be sent as a POST request.
	WebhookURL *string `json:"webhook_url" api:"webhook_url"`
	// Authorization header for the webhook. This parameter allows you to add authentication to your webhook endpoint.
	WebhookAuthorization *string `json:"webhook_authorization" api:"webhook_authorization"`
	// Comma-separated list of fields to keep in the response, with dot notation for nested fields (e.g. name,location.city). Does not change the credit cost.
	Fields *string `json:"fields" api:"fields"`
	// Process the request asynchronously: the response is a job_id to poll on /v1/jobs/{id} (see waitForJob). Default: false.
	IsAsync *bool `json:"is_async" api:"is_async"`
	// Return HTTP 200 even when an error occurs; the error is then in the response body. Default: false.
	SoftFail *bool `json:"soft_fail" api:"soft_fail"`
}

AudioDownloadParams holds the parameters of AudioDownload (GET / POST /v1/audio/download). Required fields are plain values; optional fields are pointers (use huntapi.String, huntapi.Float, huntapi.Bool) or nil slices and maps.

type BatchResult 

type BatchResult[T any] struct {
	Index int
	Value T
	Err   error
}

BatchResult is the outcome of one Batch item.

func Batch 

func Batch[I, T any](ctx context.Context, items []I, concurrency int, task func(ctx context.Context, item I) (T, error)) []BatchResult[T]

Batch runs task for every item with at most concurrency calls in flight (DefaultConcurrency when concurrency <= 0) and returns one result per item, in input order. A failing item never stops the others; items not started when ctx is done get ctx.Err().

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is a reusable, concurrency-safe HuntAPI API client.

func NewClient 

func NewClient(apiKey string, options *ClientOptions) (*Client, error)

NewClient creates a client. An empty apiKey falls back to the HUNTAPI_API_KEY environment variable.

func (*Client) AudioDownload 

func (c *Client) AudioDownload(ctx context.Context, params *AudioDownloadParams, options ...RequestOption) (*Response, error)

AudioDownload — Audio Download. Download audio from a URL via HuntAPI and receive a job id. Credit cost: 1 credit per call.

GET / POST /v1/audio/download

func (*Client) Jobs 

func (c *Client) Jobs(ctx context.Context, params *JobsParams, options ...RequestOption) (*Response, error)

Jobs — Jobs. Poll status, progress (0–100), and result of an async HuntAPI job.

GET /v1/jobs/{id}

func (*Client) MediaMetadata 

func (c *Client) MediaMetadata(ctx context.Context, params *MediaMetadataParams, options ...RequestOption) (*Response, error)

MediaMetadata — Media Metadata. Extract metadata from a media URL without downloading the file. Credit cost: 1 credit per call.

GET /v1/media/metadata

func (*Client) Request 

func (c *Client) Request(ctx context.Context, method, path string, params map[string]any, options ...RequestOption) (*Response, error)

Request sends any request, including endpoints released after this SDK version. GET parameters travel in the query string; POST parameters travel in a JSON body.

func (*Client) Stats 

func (c *Client) Stats(ctx context.Context, params *StatsParams, options ...RequestOption) (*Response, error)

Stats — Stats. Infrastructure health for an engine or endpoint over the last hour. Not scoped to your account or tenant. Enabled per account: HTTP 403 means contact support to activate it.

GET /v1/stats

func (*Client) Usage 

func (c *Client) Usage(ctx context.Context, options ...RequestOption) (*Response, error)

Usage — Usage. Retrieve real-time usage statistics and credit balance for your Huntapi account.

GET /v1/usage

func (*Client) VideoDownload 

func (c *Client) VideoDownload(ctx context.Context, params *VideoDownloadParams, options ...RequestOption) (*Response, error)

VideoDownload — Video Download. Credit cost: 1 credit per call.

GET / POST /v1/video/download

func (*Client) WaitForJob 

func (c *Client) WaitForJob(ctx context.Context, jobID string, options *WaitForJobOptions) (*Response, error)

WaitForJob polls GET /v1/jobs/{id} until the job reaches a terminal status and returns the last response.

type ClientOptions 

type ClientOptions struct {
	// BaseURL overrides DefaultBaseURL.
	BaseURL string
	// Timeout bounds each request. Zero uses DefaultTimeout; a negative value disables it.
	Timeout time.Duration
	// HTTPClient is copied and used for requests. Redirects are never followed.
	HTTPClient *http.Client
	// Headers are sent with every request.
	Headers map[string]string
	// MaxRetries overrides the number of retries. Zero uses MaxRetries; a negative value disables retries.
	MaxRetries int
	// RetryDelay is the delay before the first retry. Zero uses DefaultRetryDelay.
	RetryDelay time.Duration
}

ClientOptions configures a Client. The zero value is valid.

type ConfigurationError 

type ConfigurationError struct {
	Message string
	Err     error
}

ConfigurationError reports a missing or unusable client configuration.

func (*ConfigurationError) Error 

func (e *ConfigurationError) Error() string

func (*ConfigurationError) Unwrap 

func (e *ConfigurationError) Unwrap() error

type JobTimeoutError 

type JobTimeoutError struct {
	JobID        string
	LastResponse *Response
}

JobTimeoutError reports an async job that did not finish before the deadline.

func (*JobTimeoutError) Error 

func (e *JobTimeoutError) Error() string

type JobsParams 

type JobsParams struct {
	// Job UUID returned as job_id by async endpoints such as /v1/video/download and /v1/audio/download.
	ID string `json:"id" api:"id,required"`
}

JobsParams holds the parameters of Jobs (GET /v1/jobs/{id}). Required fields are plain values; optional fields are pointers (use huntapi.String, huntapi.Float, huntapi.Bool) or nil slices and maps.

type MediaMetadataParams 

type MediaMetadataParams struct {
	// Media URL to inspect (YouTube, Instagram, TikTok, Vimeo, X, Facebook, Twitch, Reddit, etc.).
	Query string `json:"query" api:"query,required"`
	// Comma-separated list of fields to keep in the response, with dot notation for nested fields (e.g. name,location.city). Does not change the credit cost.
	Fields *string `json:"fields" api:"fields"`
	// Process the request asynchronously: the response is a job_id to poll on /v1/jobs/{id} (see waitForJob). Default: false.
	IsAsync *bool `json:"is_async" api:"is_async"`
	// Return HTTP 200 even when an error occurs; the error is then in the response body. Default: false.
	SoftFail *bool `json:"soft_fail" api:"soft_fail"`
}

MediaMetadataParams holds the parameters of MediaMetadata (GET /v1/media/metadata). Required fields are plain values; optional fields are pointers (use huntapi.String, huntapi.Float, huntapi.Bool) or nil slices and maps.

type RequestOption 

type RequestOption func(*requestOptions)

RequestOption customizes one request.

func WithHeader 

func WithHeader(name, value string) RequestOption

WithHeader adds a header to one request.

func WithMaxRetries 

func WithMaxRetries(n int) RequestOption

WithMaxRetries overrides the number of retries for one request (0 disables them).

func WithMethod 

func WithMethod(method string) RequestOption

WithMethod selects GET or POST. Operations default to GET when they support it.

type Response 

type Response struct {
	StatusCode  int
	Header      http.Header
	ContentType string
	// Body holds the raw bytes: JSON text, or a file such as an image or PDF.
	Body []byte
	// IsJSON reports whether the body is JSON (Content-Type application/json or +json).
	IsJSON bool
}

Response is a buffered, successful API response.

func (*Response) Decode 

func (r *Response) Decode(v any) error

Decode unmarshals a JSON body into v.

func (*Response) Map 

func (r *Response) Map() (map[string]any, error)

Map decodes a JSON object body.

type ResponseDecodingError 

type ResponseDecodingError struct {
	Message  string
	Response *Response
	Err      error
}

ResponseDecodingError reports a success response that could not be decoded.

func (*ResponseDecodingError) Error 

func (e *ResponseDecodingError) Error() string

func (*ResponseDecodingError) Unwrap 

func (e *ResponseDecodingError) Unwrap() error

type SerializationError 

type SerializationError struct {
	Param   string
	Message string
	Err     error
}

SerializationError reports a parameter that is missing or cannot be sent.

func (*SerializationError) Error 

func (e *SerializationError) Error() string

func (*SerializationError) Unwrap 

func (e *SerializationError) Unwrap() error

type StatsParams 

type StatsParams struct {
	// API family to check, for example video. Provide at least engine or path.
	Engine *string `json:"engine" api:"engine"`
	// Specific endpoint to check, for example /v1/video/download. If you also pass engine, use an endpoint from that API.
	Path *string `json:"path" api:"path"`
}

StatsParams holds the parameters of Stats (GET /v1/stats). Required fields are plain values; optional fields are pointers (use huntapi.String, huntapi.Float, huntapi.Bool) or nil slices and maps.

type TransportError 

type TransportError struct {
	Message string
	Err     error
}

TransportError reports a failure before a complete HTTP response was received, including client-side timeouts and context cancellation (see Unwrap).

func (*TransportError) Error 

func (e *TransportError) Error() string

func (*TransportError) Unwrap 

func (e *TransportError) Unwrap() error

type VideoDownloadParams 

type VideoDownloadParams struct {
	// Video URL to download.
	Query string `json:"query" api:"query,required"`
	// Desired download type. You have three options: Default: "audio_video".
	DownloadType *string `json:"download_type" api:"download_type"`
	// Maximum duration of the downloaded content in seconds. If the video/audio is longer than this value, only the content up to this duration will be downloaded.
	MaxDuration *float64 `json:"max_duration" api:"max_duration"`
	// Desired video quality. Available options: Default: "best".
	VideoQuality *string `json:"video_quality" api:"video_quality"`
	// Desired output format for the video. Available options: Default: "mp4".
	VideoFormat *string `json:"video_format" api:"video_format"`
	// URL of the webhook where results will be sent. When specified, the system will attempt to send the response to this URL up to 3 times with a 5-second delay between each attempt. The results will be sent as a POST request.
	WebhookURL *string `json:"webhook_url" api:"webhook_url"`
	// Authorization header for the webhook. This parameter allows you to add authentication to your webhook endpoint. This value will be included in the Authorization header when making the webhook request to your server.
	WebhookAuthorization *string `json:"webhook_authorization" api:"webhook_authorization"`
	// Comma-separated list of fields to keep in the response, with dot notation for nested fields (e.g. name,location.city). Does not change the credit cost.
	Fields *string `json:"fields" api:"fields"`
	// Process the request asynchronously: the response is a job_id to poll on /v1/jobs/{id} (see waitForJob). Default: false.
	IsAsync *bool `json:"is_async" api:"is_async"`
	// Return HTTP 200 even when an error occurs; the error is then in the response body. Default: false.
	SoftFail *bool `json:"soft_fail" api:"soft_fail"`
}

VideoDownloadParams holds the parameters of VideoDownload (GET / POST /v1/video/download). Required fields are plain values; optional fields are pointers (use huntapi.String, huntapi.Float, huntapi.Bool) or nil slices and maps.

type WaitForJobOptions 

type WaitForJobOptions struct {
	Interval   time.Duration
	Timeout    time.Duration
	OnProgress func(job map[string]any)
}

WaitForJobOptions configures WaitForJob. The zero value polls after 3 s, then 1.5x longer each time up to 60 s, for up to 12 hours.

Source Files

View all Source files

Directories

Path Synopsis
examples
json command
request command
wait-for-job command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.