Como usar o lyria-3.5 pela API do hiapi: curl, Python e uma requisição que funciona

lyria-3.5 é o modelo de geração de música a partir de texto do hiapi: envie uma descrição musical, uma letra, ou ambos, e receba uma faixa pronta — com título, orientação de andamento e controle de duração opcionais. Este guia explica por completo o schema de entrada, uma requisição que retorna uma faixa real e os detalhes necessários para ir do teste pontual à produção.

Do que você precisa

• Uma API key do hiapi. Obtenha-a no dashboard — a key começa com sk-.
• curl ou o requests do Python. Nenhum SDK é necessário; o hiapi usa REST puro.

O lyria-3.5 roda sobre a API de tarefas assíncronas unificada do hiapi: você envia uma tarefa com POST, recebe imediatamente um taskId e então consulta o resultado ou recebe um callback quando a faixa estiver pronta.

Schema de entrada completo

O lyria-3.5 aceita muito mais do que um prompt cru. Exceto por ser obrigatório fornecer ao menos um entre prompt ou lyrics, todos os campos são opcionais:

Campo	Tipo	Descrição
prompt	string	Gênero, instrumentos, clima, vocais, estrutura da música. Forneça prompt ou lyrics.
lyrics	string	Uma frase por linha. Tags de seção — [Intro], [Verse], [Chorus], [Bridge], [Outro] — cada uma em sua própria linha, seguida pela letra. Numere seções repetidas com [Verse 1], [Verse 2].
title	string	Título da música gerada.
bpm	string	Orientação de andamento; deve ser uma string numérica, por exemplo "90".
length	integer	Duração solicitada em segundos, 1–240. Serve como orientação de duração; a duração real pode variar. Omita para não especificar.
seed	string	Seed em formato de string numérica, por exemplo "00123". Mesmo com a mesma seed, não há garantia de obter exatamente o mesmo áudio.

Dois avisos antecipados: bpm e seed são strings e não números — envie "90", não 90, ou a API retornará 400 (got number, want string). E o schema é estrito: qualquer campo fora da tabela acima (duration, style, genre, negative_prompt etc.) retornará 400 com additional properties '...' not allowed.

Exemplo mínimo funcional

1. Criar a tarefa

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "lyria-3.5",
    "input": {
      "prompt": "Warm instrumental indie folk, fingerpicked acoustic guitar, soft brushed drums, quiet morning",
      "bpm": "90",
      "length": 30
    }
  }'

Uma resposta bem-sucedida retorna imediatamente, antes de a faixa ser realmente renderizada:

{
  "code": 200,
  "message": "success",
  "data": { "taskId": "tk-hiapi-01M2HCSKAP77MTH1ANKQXE1DT2" }
}

2. Consultar o resultado

curl "https://api.hiapi.ai/v1/tasks/tk-hiapi-01M2HCSKAP77MTH1ANKQXE1DT2" \
  -H "Authorization: Bearer sk-YOUR_API_KEY"

Espere alguns segundos antes da primeira consulta e depois verifique a cada 3–5 segundos. O status passa primeiro por handling e então chega ao estado final. A seguir está a resposta real da requisição acima após cerca de 100 segundos:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M2HCSKAP77MTH1ANKQXE1DT2",
    "model": "lyria-3.5",
    "status": "success",
    "created": 1789437730,
    "completed": 1789437829,
    "output": [
      {
        "type": "audio",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M2HCSKAP77MTH1ANKQXE1DT2-0.m4a",
        "expireAt": 1790042629
      }
    ]
  }
}

Observe que o formato de contêiner de saída pode variar conforme a requisição (aqui é .m4a; outros modelos de música no hiapi retornam .mp3) — leia output[0].type/URL em vez de codificar a extensão fixa. Baixe output[0].url prontamente: a camada de armazenamento temp padrão expira em cerca de 7 dias (expireAt é um timestamp Unix). Em caso de falha, status é fail e data.error contém { code, message } em vez de output.

3. Enviar uma requisição baseada em letra com Python

import time
import requests

API_KEY = "sk-YOUR_API_KEY"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

payload = {
    "model": "lyria-3.5",
    "input": {
        "title": "Carry the Morning",
        "lyrics": (
            "[Verse 1]\n"
            "Light through the window, coffee still warm\n"
            "[Chorus]\n"
            "Carry the morning, carry it slow\n"
        ),
        "bpm": "96",
        "length": 45,
    },
}

create = requests.post("https://api.hiapi.ai/v1/tasks", headers=HEADERS, json=payload)
task_id = create.json()["data"]["taskId"]

status = None
while status not in ("success", "fail"):
    time.sleep(4)
    poll = requests.get(f"https://api.hiapi.ai/v1/tasks/{task_id}", headers=HEADERS).json()
    status = poll["data"]["status"]

if status == "success":
    print(poll["data"]["output"][0]["url"])
else:
    print(poll["data"]["error"])

Conforme você precise de uma faixa instrumental ou vocal, troque lyrics por prompt (ou envie ambos).

Considerações para produção

• Use callback em vez de polling. Adicione um objeto callback de nível superior: {"url": "https://yourapp.com/hook", "when": "final"}. O when aceita apenas "final" — você recebe uma chamada quando a tarefa atinge o estado final, em vez de atualizações de progresso.
• Idempotência. A API de tarefas não aceita chaves de idempotência fornecidas pelo cliente, então previna problemas de retry na camada da aplicação: persista o taskId imediatamente após recebê-lo e verifique o status da tarefa antes de tentar novamente, evitando requisições duplicadas.
• Erros. API key ausente ou inválida retorna HTTP 401 e error_code: "permission_denied". Violar o schema retorna HTTP 400 e error_code: "INVALID_REQUEST", com a mensagem indicando o campo problemático — isso ajuda a detectar um duration supérfluo ou um bpm numérico antes de ir para produção.
• Armazenamento. Após um polling bem-sucedido ou o recebimento do callback, transfira imediatamente output[0].url para o seu próprio armazenamento; não dependa da camada temp além do seu expireAt.

Leituras relacionadas

• Tutorial da API lyria-3-pro — outro modelo Lyria do hiapi; se você não precisa de letra nem controle de andamento, o schema dele é mais simples e exige apenas um prompt.
• Guia da API MiniMax Music — outro modelo de geração de música a partir de texto no hiapi, com seu próprio conjunto de opções de letra e amostragem.
• Referência do modelo lyria-3.5 — a documentação autoritativa dos parâmetros.
• Preços do hiapi — tarifas atuais de cada modelo.

FAQ

Preciso enviar prompt e lyrics ao mesmo tempo?Não — a API exige apenas que ao menos um dos dois seja fornecido. Enviar só prompt gera uma faixa instrumental; enviar só lyrics gera uma faixa totalmente guiada pela letra; ou envie ambos.

Qual formato de áudio o lyria-3.5 retorna?Varia conforme a requisição — verifique output[0].type e a extensão da URL; não presuma .mp3 nem .m4a.

Posso forçar um andamento exato?O bpm é orientativo, não uma restrição rígida, e deve ser enviado como string ("90", não 90).

Qual o comprimento máximo da faixa gerada?length aceita de 1 a 240 segundos, mas apenas orienta o modelo e não garante a duração exata — verifique a duração real do arquivo retornado.

Usar o mesmo seed me dá a mesma faixa duas vezes?Não. O seed é uma string numérica usada para ajustar a geração, mas a documentação do hiapi afirma explicitamente que não há garantia de áudio idêntico.

O que acontece se eu enviar um campo não reconhecido, como genre ou duration?O schema é estrito — você recebe 400 e additional properties '<field>' not allowed, em vez de o campo ser silenciosamente ignorado.