API Reference

API de Download de Áudio

A API de Download de Áudio permite extrair e descarregar faixas de áudio de vídeos ou fontes só de áudio. Esta é uma API assíncrona: inicia um job e depois faz polling para obter o resultado.

x-api-key:stringobrigatório

Este header especifica a chave privada necessária para aceder ao Hunt.

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

query:stringobrigatório

URL de onde descarregar o áudio.

download_type:stringopc

Tipo de download desejado.

  • audio: descarrega apenas áudio (por defeito)
padrão:audio
audio_quality:stringopc

Qualidade de áudio desejada.

  • best: melhor qualidade disponível (por defeito)
  • 320kbps: alta qualidade
  • 256kbps: qualidade standard
  • 128kbps: baixa qualidade
padrão:best
audio_format:stringopc

Formato de saída desejado para o áudio.

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

Nota: isto é uma preferência de formato. Faremos o possível para fornecer o formato pedido, mas por limitações técnicas ou problemas de conversão, o formato final pode diferir do solicitado.

padrão:mp3
max_duration:numberopc

Duração máxima do conteúdo descarregado em segundos. Se o áudio for maior que este valor, apenas o conteúdo até essa duração será descarregado. Útil para limitar tamanhos de ficheiro ou extrair partes específicas.

webhook_url:stringopc

URL do webhook para onde os resultados serão enviados. Quando especificado, o sistema tentará enviar a resposta até 3 vezes com um atraso de 5 segundos entre tentativas. Os resultados serão enviados como um pedido POST.

webhook_authorization:stringopc

Header Authorization para o webhook. Este parâmetro permite adicionar autenticação ao seu endpoint de webhook.

Resposta

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

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

Verifique o estado do job usando o job_id devolvido no Passo 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 é um número de 0 a 100 enquanto o job corre (Queued → 0, Running → 1–99, terminal → 100). Valores de status: Queued, Running, CompletedJob, Error, NotFound, BadRequest.

Precisa só dos metadados sem descarregar o ficheiro? Use a Media Metadata API (GET https://api.huntapi.com/v1/media/metadata) - síncrona, 1 crédito.

Relacionado

Notas

Alguns áudios não podem ser descarregados pelos seguintes motivos:

  • Conteúdo privado: se o conteúdo estiver definido como privado pelo proprietário
  • Conteúdo indisponível: se o conteúdo foi apagado ou já não está acessível
  • Conteúdo com restrição de idade: se o conteúdo estiver restrito por idade

Nestes casos, a API devolverá uma mensagem de erro explicativa.

Obter API Key

VIDEO API

Discover why Hunt is the preferred API provider for developers.

Implante a sua API de download de vídeoVer preços