API ElevenLabs Music no HiAPI: gerar música com curl, Python e receitas de prompts

Por que chamar elevenlabs/music-v2.5 através do HiAPI

Se você quer adicionar geração de música ao seu produto, o caminho mais rápido raramente é o mais limpo. Conectar o backend diretamente ao provedor do modelo significa que você é responsável pela configuração de conta, esquema de autenticação, semântica de retentativa e estrutura de requisição desse provedor. Cada novo modelo adotado adiciona mais um conjunto dessas decisões, e cada experimento deixa um ramo de integração para trás.

Chamar elevenlabs/music-v2.5 através do HiAPI muda a forma desse trabalho. Você precisa apenas de uma URL base, um cabeçalho de autenticação e uma convenção de requisição que permanece estável ao alternar entre modelos. O identificador do modelo (elevenlabs/music-v2.5) é apenas uma string no corpo da requisição, então alternar entre modelos de música, ou testar um segundo modelo para comparação, exige mudar uma linha em vez de importar um novo SDK.

Para desenvolvedores que escolhem como integrar, três benefícios práticos merecem atenção:

• Uma superfície unificada de gerenciamento de credenciais. Gerenciamento de chaves, rotação e isolamento de ambientes (desenvolvimento/staging/produção) ficam concentrados em um só lugar, em vez de se multiplicarem por provedor.
• Padrões de requisição portáveis. Os trechos de curl e Python abaixo são consistentes com o que você usa para outros modelos no HiAPI. Aprender o padrão uma vez é suficiente.
• Uso concentrado em um só lugar. A geração de música é cobrada pela duração da saída; colocá-la junto com o uso de outros modelos significa acompanhar custos em um único painel, em vez de lidar com cobranças espalhadas.

O custo é passar por uma camada de abstração, então peculiaridades específicas do provedor são normalizadas. Para a primeira integração e para a maioria dos casos de produção, essa normalização é exatamente o que você quer. Quando precisar entender o comportamento específico do modelo, a página de detalhes no site é a fonte autoritativa.

Preparação antes da primeira requisição de música

Confirme quatro coisas antes de escrever código, para que a primeira chamada retorne áudio em vez de um 401 ou erro de validação.

1. Chave de API

Você precisa de uma chave de API da sua conta HiAPI. Trate-a como qualquer outra chave: mantenha-a em uma variável de ambiente, nunca a envie para o código-fonte e use chaves diferentes para desenvolvimento local e produção, para que você possa revogar uma sem afetar a outra.

export HIAPI_API_KEY="your_key_here"

2. URL base e convenção de endpoint

Todas as chamadas de modelo usam a mesma URL base, e o modelo é identificado dentro da requisição, não no caminho. Mantenha uma constante para a URL base no seu projeto, para que, se seu ambiente for diferente, você só precise mudar um lugar.

3. Um prompt escrito em linguagem natural

elevenlabs/music-v2.5 aceita um prompt de texto que descreve a música que você quer. Você não precisa de partitura nem de arquivo MIDI. Uma ou duas frases indicando gênero, instrumentação, humor e duração desejada são suficientes para começar. As seções seguintes trazem receitas reutilizáveis.

4. Expectativa correta sobre a saída

A geração de música retorna áudio, não uma partitura em JSON. Planeje como lidar com o payload de resposta: gravar em arquivo durante o desenvolvimento, fazer streaming ou armazenar em produção. Decida antecipadamente quão longa você espera que a faixa seja, pois a duração afeta tanto a requisição quanto a cobrança.

Mais uma coisa antes da primeira requisição: consulte o painel de preços do site para ver os limites de taxa e o preço atuais de elevenlabs/music-v2.5, em vez de codificar suposições no código. Preços e limites mudam, e sua integração deve lê-los como configuração, não como constantes embutidas no script.

Fazendo a primeira chamada com curl

Comece com curl, porque ele remove todas as camadas entre você e a requisição HTTP. Se a chamada curl funcionar, qualquer falha na aplicação é problema da própria aplicação, não da API.

curl -sS https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "elevenlabs/music-v2.5",
    "messages": [
      {
        "role": "user",
        "content": "Instrumental lo-fi hip hop, warm vinyl texture, mellow electric piano, soft brushed drums, 80 BPM, relaxed late-night mood, about 30 seconds."
      }
    ]
  }'

O papel de cada parte:

• -sS mantém a saída de progresso silenciosa, mas ainda mostra erros. Útil quando você redireciona a saída para um arquivo.
• A URL é o endpoint unificado. Observe que o nome do modelo não aparece no caminho, mas no corpo da requisição.
• Authorization: Bearer $HIAPI_API_KEY lê a chave do ambiente, para que ela não fique em texto claro no histórico do shell. No Windows, defina a variável com set ou com a sintaxe $env: do PowerShell, conforme apropriado.
• Content-Type: application/json é obrigatório; o endpoint não aceita formulário codificado.
• model é o identificador exato elevenlabs/music-v2.5. Um erro de digitação aqui gera um erro de modelo não encontrado em vez de uma falha genérica, o que ajuda na depuração.
• messages passa seu prompt como conteúdo de mensagem do usuário. Coloque o prompt em uma única mensagem; prompts longos e estruturados funcionam melhor do que vários prompts separados.

O corpo da resposta contém o áudio gerado e metadados sobre a requisição. Durante o desenvolvimento, redirecione a saída para um arquivo para poder ouvir o resultado imediatamente:

curl -sS https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json -o response.json

Colocar o payload em request.json e lê-lo com -d @request.json é um hábito que vale a pena adquirir cedo. Ele torna a requisição comparável, revisável e fácil de reexecutar ao alterar um parâmetro por vez.

Repetindo a chamada em Python

Assim que a chamada curl retornar áudio, porte-a para Python. O objetivo não é apenas um script que funcione, mas uma função que possa ser chamada de uma fila de tarefas, de um handler de API ou de um notebook sem desvios de copiar e colar.

import json
import os
import urllib.request

BASE_URL = "https://api.hiapi.ai/v1/chat/completions"
MODEL = "elevenlabs/music-v2.5"

def generate_music(prompt: str, timeout: int = 120) -> dict:
    """Envia um prompt de música para elevenlabs/music-v2.5 através do HiAPI."""
    api_key = os.environ.get("HIAPI_API_KEY")
    if not api_key:
        raise RuntimeError("HIAPI_API_KEY is not set")

    payload = {
        "model": MODEL,
        "messages": [{"role": "user", "content": prompt}],
    }

    request = urllib.request.Request(
        BASE_URL,
        data=json.dumps(payload).encode("utf-8"),
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        },
        method="POST",
    )

    with urllib.request.urlopen(request, timeout=timeout) as response:
        return json.loads(response.read().decode("utf-8"))

if __name__ == "__main__":
    result = generate_music(
        "Cinematic orchestral swell, strings and low brass, hopeful build, "
        "no percussion, about 20 seconds."
    )
    print(json.dumps(result, indent=2)[:500])

À medida que a função cresce, algumas decisões merecem ser mantidas:

• Prefira a biblioteca padrão. urllib evita variações de dependências no tutorial. Se seu projeto já usa requests ou httpx, a conversão é mecânica: passe json=payload, headers=headers e timeout.
• O timeout é obrigatório. A geração de música leva mais tempo que completions de chat. Defina um timeout explícito e não dependa do padrão. Escolha um valor maior que o tempo esperado de geração da faixa mais longa que você solicita.
• Leia a chave no momento da chamada, não no momento do import, para que o mesmo módulo funcione localmente e em um contêiner que injeta variáveis de ambiente em tempo de execução.
• Retorne dados estruturados, não imprima uma string. Cabe ao chamador decidir se grava o áudio em disco, envia para armazenamento de objetos ou repassa ao cliente.

Antes de construir qualquer coisa com base neles, confirme que a função Python e a chamada curl produzem resultados equivalentes para o mesmo prompt. Essa consistência é sua linha de base de regressão.

Receitas de prompts para estilo, humor e duração

Prompts de música funcionam melhor quando respondem a três perguntas em ordem: qual gênero e instrumentação, qual tom emocional, e por quanto tempo. Prompts vagos produzem saídas genéricas; prompts longos demais diluem os descritores importantes. O objetivo é uma frase densa, ou três orações curtas.

Use estes como pontos de partida prontos para copiar e colar, ajustando apenas uma dimensão por vez.

Receitas com foco em estilo

• Solo piano, felt hammers, close-miked, slow arpeggios in the style of a modern film score.
• Upbeat synthwave, analog bass, gated reverb drums, arpeggiated lead, 120 BPM.
• Acoustic folk ensemble, fingerpicked guitar, upright bass, light tambourine, organic room sound.
• Ambient drone, layered pads, no rhythm section, slowly evolving texture.

Receitas com foco em humor

• Warm and nostalgic, like a summer evening, major key, gentle dynamics.
• Tense and minimal, low pulsing bass, sparse percussion, unresolved harmony.
• Playful and bright, staccato strings, bouncy rhythm, light-hearted.
• Melancholic and spacious, reverb-heavy, sparse piano, slow tempo.

Receitas com foco em duração

A duração deve ser escrita no prompt como um objetivo explícito e deve ser coerente com o arranjo. Uma solicitação de 15 segundos com uma introdução lenta e um longo fade final será cortada abruptamente.

• ... about 15 seconds, short intro, no outro, ends cleanly.
• ... about 30 seconds, one clear section, loopable ending.
• ... about 60 seconds, intro, main section, and a natural fade.

Exemplo combinado

Lo-fi hip hop for focus, dusty vinyl crackle, soft electric piano, brushed drums, 80 BPM, calm and unhurried, about 30 seconds, loopable.

Quando a saída não corresponde ao esperado

Ajuste apenas uma variável por tentativa, para que você saiba exatamente o que mudou o resultado.

• Genérico demais: substitua palavras de humor por instrumentação e andamento específicos. "Energetic" é menos eficaz que "driving 16th-note bass at 128 BPM".
• Ocupado ou confuso demais: remova instrumentos explicitamente (no drums, no vocals, sparse arrangement) em vez de adicionar mais descritores positivos.
• A duração parece errada: se a faixa termina abruptamente, peça um alvo mais curto e um final explícito; se parecer apressada, reduza o número de seções solicitadas.
• Desvio de estilo: mova gênero e instrumentação para o início do prompt. Tokens no início têm maior peso.

Mantenha um pequeno arquivo de prompts no repositório registrando as receitas que funcionaram. Esse arquivo vale mais que qualquer faixa individual gerada, porque transforma a escrita de prompts em um artefato de engenharia reproduzível.

Erros comuns e como corrigi-los

A maioria das primeiras integrações falha de algumas maneiras previsíveis. Percorra esta lista antes de começar a adivinhar.

Falhas de autenticação

Um 401 quase sempre significa cabeçalho de requisição malformado ou chave ausente no ambiente do processo. Verifique se há espaços extras depois de Bearer, se a chave foi carregada do arquivo .env errado, ou se o export foi executado em uma sessão diferente da que executa o script. Imprima o comprimento da chave (não a chave em si) para confirmar que ela está preenchida.

Identificador de modelo incorreto

Erros de modelo não encontrado ou de validação geralmente significam que a string model não é uma correspondência exata. elevenlabs/music-v2.5 diferencia maiúsculas de minúsculas e inclui uma barra. Se você copiou de uma janela de chat, verifique se há aspas tipográficas ou restos de quebra de linha.

Corpo de requisição malformado

Se curl funciona mas Python não, a diferença quase sempre é de serialização. Passar um dict Python onde se espera uma string JSON, codificar duas vezes com json.dumps, ou esquecer Content-Type: application/json, todos produzem erros de parsing no servidor que parecem não ter relação com a causa real. Registre o corpo exato da requisição que o código envia e compare caractere por caractere com o payload curl que funciona.

Timeouts em faixas mais longas

Durações maiores exigem mais tempo de geração. Um timeout de cliente adequado para requisições de chat truncará solicitações de música mais longas. Aumente o timeout especificamente para este endpoint e adicione retentativas com backoff apenas para falhas de nível de conexão, nunca retentando cegamente requisições que podem já ter sido cobradas.

Tamanho e conteúdo do prompt

Prompts extremamente longos, ou prompts que contêm instruções sobre a própria API, tendem a produzir música pior. Mantenha o prompt apenas sobre música. Se um prompt que funcionava ontem parar de funcionar, reduza-o ao esqueleto estilo/humor/duração e reconstrua.

Tratar a resposta como texto

O endpoint retorna dados de áudio, não texto transcrito legível. Gravar o corpo bruto da resposta em um arquivo .txt e depois se perguntar por que ele não toca é um erro comum no primeiro dia. Salve com a extensão de áudio correta e verifique se o arquivo abre em um player antes de construir mais.

Quando um erro não estiver claro, reproduza-o com a menor requisição curl possível. Isso isola se o problema está no contrato da API ou no seu código.

De uma chamada de teste para um fluxo de trabalho repetível

Uma chamada de teste bem-sucedida é um ponto de partida, não uma integração. Use esta lista para transformá-la em algo com que a equipe possa contar.

• Configuração externalizada. URL base, identificador do modelo, timeouts e alvos de duração padrão vão para configuração, não para literais de string espalhados. Valores específicos de ambiente vêm do ambiente.
• Cliente centralizado. Uma função ou classe de cliente leve é responsável pela requisição. Nenhum módulo deve construir sua própria chamada HTTP ao endpoint de música, ou vocês vão divergir em cabeçalhos e tratamento de erros.
• Tratamento de erros por categoria. Distinga autenticação, validação, timeout e erros do servidor. Retente apenas erros transitórios, com backoff e limite. Nunca retente uma requisição que pode já ter produzido saída e sido cobrada.
• Armazene o áudio corretamente. Grave no armazenamento de objetos com chaves determinísticas, mantenha o prompt junto ao ativo gerado e registre o identificador do modelo. Reproduzir resultados depois depende de saber exatamente o que foi solicitado na época.
• Acompanhe a duração como parâmetro de primeira classe. Como a cobrança segue a duração de saída, deixe a duração alvo explícita nos templates de prompt e registre-a por requisição, para que relatórios de custo se alinhem ao uso.
• Construa uma biblioteca de prompts. Versione as receitas validadas e anote brevemente para que serve cada uma. Novos membros da equipe começam com prompts que funcionam, em vez de adivinhar.
• Separe os caminhos síncrono e assíncrono. A geração pode ser lenta. Para recursos voltados ao usuário, envie o job, persista a requisição e deixe um worker chamar o modelo. Um handler HTTP não deve permanecer aberto durante toda a geração.
• Valide com smoke tests. Um teste que envia um prompt curto fixo e verifica se a resposta de áudio está no formato correto detecta desvios de credencial e de contrato cedo.

Quando você estiver pronto para se aprofundar em parâmetros e limites, a página do modelo elevenlabs/music-v2.5 no HiAPI é o lugar para consultar as capacidades atuais antes de codificar suposições.