API Reference

API di download audio

La Audio Download API ti consente di estrarre e scaricare tracce audio da video o da sorgenti solo-audio. Questa è un’API asincrona: avvii un job e poi fai polling per ottenere il risultato.

x-api-key:stringrichiesto

Questo header specifica la chiave privata necessaria per l’accesso a Hunt.

Endpoint: GET https://api.huntapi.com/v1/audio/download

query:stringrichiesto

URL da cui scaricare l’audio.

download_type:stringopz

Tipo di download desiderato.

audio: scarica solo audio (opzione predefinita)

default:audio

audio_quality:stringopz

Qualità audio desiderata.

best: migliore qualità disponibile (default)
320kbps: alta qualità
256kbps: qualità standard
128kbps: bassa qualità

default:best

audio_format:stringopz

Formato di output desiderato per l’audio.

mp3: formato MP3 (default)
m4a: formato MPEG-4 Audio
wav: Waveform Audio File Format

Nota: questa è una preferenza di formato. Faremo del nostro meglio per fornire il formato richiesto ma, per limitazioni tecniche o problemi di conversione, il formato finale potrebbe differire da quello richiesto.

default:mp3

max_duration:numberopz

Durata massima del contenuto scaricato in secondi. Se l’audio è più lungo di questo valore, verrà scaricato solo fino a questa durata. Utile per limitare le dimensioni del file o estrarre porzioni specifiche.

webhook_url:stringopz

URL del webhook a cui inviare i risultati. Quando specificato, il sistema tenterà di inviare la risposta fino a 3 volte con un ritardo di 5 secondi tra i tentativi. I risultati vengono inviati come richiesta POST.

webhook_authorization:stringopz

Header Authorization per il webhook. Questo parametro consente di aggiungere autenticazione al tuo endpoint webhook.

Response

{
    "job_id": "0193443f-fb80-9d19-29ba-82bc77c7cd84"
}

Endpoint: GET https://api.huntapi.com/v1/jobs/{job_id}

Verifica lo stato del job usando il job_id restituito dallo Step 1.

Response Example (Running)

{
    "id": "019ff14c-49fe-09b5-0cd5-e6c575481a6b",
    "status": "Running",
    "success": null,
    "endpoint": "/api/audio/download",
    "progress": 47,
    "created_at": "2026-08-11T14:48:56.574227Z",
    "started_at": "2026-08-11T14:48:56.577590Z",
    "completed_at": null,
    "duration_ms": null,
    "args": {
        "query": "https://www.youtube.com/watch?v=Z5YP8kznWZs",
        "download_type": "audio"
    },
    "result": null
}

Response Example (Completed)

{
    "id": "0193443f-fb80-9d19-29ba-82bc77c7cd84",
    "status": "CompletedJob",
    "success": true,
    "endpoint": "/api/audio/download",
    "progress": 100,
    "duration_ms": 42110,
    "args": {
        "query": "https://www.youtube.com/watch?v=example"
    },
    "result": {
        "metadata": {
            "title": "Example Audio Title",
            "duration": 180,
            "upload_date": 1729641600
        },
        "response": "https://s3.huntapi.com/audios/audio_id.mp3"
    }
}

progress è un numero da 0 a 100 mentre il job è in esecuzione (Queued → 0, Running → 1–99, terminale → 100). Valori di status: Queued, Running, CompletedJob, Error, NotFound, BadRequest.

Serve solo i metadati senza scaricare il file? Usa la Media Metadata API (GET https://api.huntapi.com/v1/media/metadata) - sincrona, 1 credito.

Correlati

Note

Alcuni audio non possono essere scaricati per i seguenti motivi:

Contenuto privato: se il contenuto è impostato come privato dal proprietario
Contenuto non disponibile: se il contenuto è stato eliminato o non è più accessibile
Contenuto con restrizioni di età: se il contenuto è soggetto a limitazioni di età

In questi casi, l’API restituirà un messaggio di errore esplicativo.

Ottieni API Key

Response

Response Example (Running)

Response Example (Completed)

Correlati

Note

VIDEO API