Skip to main content
GET
https://huntapi.com
/
api
/
v1
/
audio
/
download
Audio Download
curl --request GET \
  --url https://huntapi.com/api/v1/audio/download \
  --header 'x-api-key: <x-api-key>'
{
    "job_id": "0193443f-fb80-9d19-29ba-82bc77c7cd84"
}
​
x-api-key
string
required
This parameter specifies the private key you’ll need for HuntAPI.com access.

​
Parameters

​
Search Query

​
query
string
required
URL to download audio from

​
Download options

​
download_type
string
default:"audio"
Desired download type.
  • audio: Downloads only the audio (default option)
​
max_duration
number
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. Useful for limiting file sizes or extracting specific portions.
​
audio_quality
string
default:"best"
Desired audio quality. Available options:
  • best: Best available quality (default)
  • 320kbps: High quality
  • 256kbps: Standard quality
  • 128kbps: Low quality
​
audio_format
string
default:"mp3"
Desired output format for the audio. Available options:
  • mp3: MP3 format (default option)
  • m4a: MPEG-4 Audio format
  • wav: Waveform Audio File Format
Note: This is a format preference. While we will do our best to provide the requested format, due to technical limitations or conversion issues, the final output format may differ from the requested one.
​
webhook_url
string
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.The payload will be sent in JSON format with one of the following structures:On success:
{
    "id": "string", // the job id,
    "status": "CompletedJob", // the job status,
    "result": {
        "metadata": {
            // filtered metadata object
        },
        "response": "https://s3.huntapi.com/audios/audio_id.mp3"
    }
}
On error:
{
    "id": "string", // the job id,
    "status": "Error", // the job status,
    "error": "string" // the error message (private, unavailable, age restricted, etc.)
}
​
webhook_authorization
string
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. Example:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

​
Notes

Some audios cannot be downloaded for the following reasons:
  • Private content: If the content is set as private by its owner
  • Unavailable content: If the content has been deleted or is no longer accessible
  • Age restricted content: If the content is age restricted In these cases, the API will return an explanatory error message.

​
Security Considerations

When using webhooks, it’s recommended to:
  • Always use HTTPS URLs for your webhook endpoints
  • Implement webhook authentication using the webhook_authorization parameter
  • Validate the incoming webhook requests on your server
  • Consider implementing webhook signing for additional security

​
Response

​
job_id
string
The ID of the job. Use this ID to check the status of the job.
{
    "job_id": "0193443f-fb80-9d19-29ba-82bc77c7cd84"
}