API Reference

API de descarga de audio

La API de descarga de audio te permite extraer y descargar pistas de audio desde videos o fuentes solo-audio. Es una API asíncrona: inicias un job y luego haces polling para obtener el resultado.

x-api-key:stringrequerido

Este header especifica la clave privada que necesitarás para acceder a Hunt.

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

query:stringrequerido

URL desde la cual descargar el audio.

download_type:stringopc

Tipo de descarga deseado.

  • audio: descarga únicamente audio (opción por defecto)
defecto:audio
audio_quality:stringopc

Calidad de audio deseada.

  • best: mejor calidad disponible (por defecto)
  • 320kbps: alta calidad
  • 256kbps: calidad estándar
  • 128kbps: baja calidad
defecto:best
audio_format:stringopc

Formato de salida deseado para el audio.

  • mp3: formato MP3 (por defecto)
  • m4a: formato MPEG-4 Audio
  • wav: Waveform Audio File Format

Nota: esto es una preferencia de formato. Haremos lo posible por entregar el formato solicitado, pero por limitaciones técnicas o problemas de conversión, el formato final puede diferir del solicitado.

defecto:mp3
max_duration:numberopc

Duración máxima del contenido descargado en segundos. Si el audio es más largo que este valor, solo se descargará hasta esta duración. Útil para limitar el tamaño de archivos o extraer partes específicas.

webhook_url:stringopc

URL del webhook donde se enviarán los resultados. Cuando se especifica, el sistema intentará enviar la respuesta hasta 3 veces con un retraso de 5 segundos entre intentos. Los resultados se enviarán como una solicitud POST.

webhook_authorization:stringopc

Header Authorization para el webhook. Este parámetro te permite añadir autenticación a tu endpoint de webhook.

Respuesta

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

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

Comprueba el estado del job usando el job_id devuelto en el Paso 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 es un número de 0 a 100 mientras el job se ejecuta (Queued → 0, Running → 1–99, terminal → 100). Valores de status: Queued, Running, CompletedJob, Error, NotFound, BadRequest.

¿Solo necesitas metadatos sin descargar el archivo? Usa la Media Metadata API (GET https://api.huntapi.com/v1/media/metadata) - síncrona, 1 crédito.

Relacionado

Notas

Algunos audios no se pueden descargar por las siguientes razones:

  • Contenido privado: si el propietario lo marcó como privado
  • Contenido no disponible: si el contenido se eliminó o ya no es accesible
  • Contenido con restricción de edad: si el contenido está restringido por edad

En estos casos, la API devolverá un mensaje de error explicativo.

Obtener API Key

VIDEO API

Discover why Hunt is the preferred API provider for developers.

Despliega tu API de descarga de videoVer precios