Como usar lyria-3-pro pela API hiapi: exemplos de requisições executáveis com curl e Python

lyria-3-pro é um modelo de geração de música disponibilizado pela API hiapi: envie um prompt de texto e receba uma faixa de áudio completa. Este guia conduz você pelo fluxo de requisição que realmente retorna um taskId, explica o schema de entrada completo (bastante enxuto) e traz os detalhes de produção de que você precisa depois de sair do teste pontual.

O que você precisa

• Uma chave de API hiapi. Obtenha-a no console — a chave começa com sk-.
• curl ou o requests do Python. Nenhum SDK é necessário; a hiapi usa REST padrão.

O lyria-3-pro roda sobre a API unificada de tarefas assíncronas da hiapi: você faz um POST de uma tarefa, recebe um taskId imediatamente e depois consulta o resultado ou recebe um callback quando a faixa ficar pronta.

Exemplo mínimo executável

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-pro",
    "input": {
      "prompt": "Warm lo-fi piano loop with soft vinyl crackle, relaxed tempo, calm evening mood"
    }
  }'

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

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

2. Consultar o resultado

curl "https://api.hiapi.ai/v1/tasks/tk-hiapi-01M0T17T7RERV481QJC3DRZCRS" \
  -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 por estados intermediários, como archiving, até chegar a um estado terminal:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M0T17T7RERV481QJC3DRZCRS",
    "model": "lyria-3-pro",
    "status": "success",
    "created": 1787580115,
    "completed": 1787580157,
    "output": [
      {
        "type": "audio",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M0T17T7RERV481QJC3DRZCRS-0.mp3",
        "expireAt": 1788184956
      }
    ]
  }
}

Baixe output[0].url o quanto antes — a camada de armazenamento temp padrão expira em cerca de 7 dias (expireAt é um timestamp Unix). Em caso de falha, o status é fail e data.error contém { code, message } em vez de output.

3. A mesma requisição em 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-pro",
    "input": {
        "prompt": "Warm lo-fi piano loop with soft vinyl crackle, relaxed tempo, calm evening mood",
    },
}

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

while True:
    time.sleep(3)
    detail = requests.get(f"https://api.hiapi.ai/v1/tasks/{task_id}", headers=HEADERS).json()
    status = detail["data"]["status"]
    if status == "success":
        print(detail["data"]["output"][0]["url"])
        break
    if status == "fail":
        raise RuntimeError(detail["data"]["error"])

Schema de entrada completo

input aceita exatamente dois campos — qualquer conteúdo fora desta lista é rejeitado com 400 INVALID_REQUEST:

Campo	Tipo	Obrigatório	Descrição
prompt	string	Sim	Descreva o gênero, a instrumentação, o clima e o andamento — quanto mais específico, mais consistentes serão os resultados.
seed	integer	Não	Valor mínimo 0. Reutilizar o mesmo seed com o mesmo prompt gera resultados mais reproduzíveis.

prompt é obrigatório — se você o omitir, a tarefa nem chega a ser criada:

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: prompt: missing required field \"prompt\""}

Enviar qualquer outro campo — duration, negative_prompt, sample_count e campos semelhantes aceitos por outros modelos de música — faz com que a requisição seja rejeitada de imediato:

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: <root>: additional properties 'negative_prompt' not allowed"}

A duração da faixa de saída é fixada pelo próprio modelo; não há parâmetro duration para configurá-la.

Considerações para produção

Callback é melhor que polling. Fora de testes rápidos, passe um callback de nível superior em vez de consultar em loop:

{
  "model": "lyria-3-pro",
  "callback": { "url": "https://your-domain.com/hiapi/callback", "when": "final" },
  "input": { "prompt": "..." }
}

Quando a tarefa atinge um estado terminal (success ou fail), a hiapi envia um único POST para callback.url — não é preciso manter um loop de consulta ativo. Ainda assim, mantenha o polling como contingência, caso a entrega do callback falhe.

Idempotência. Se o chamador puder tentar novamente a mesma requisição, envie o cabeçalho Idempotency-Key (até 255 bytes) — novas tentativas com a mesma chave na mesma conta retornam o taskId original em vez de criar (e cobrar) uma faixa duplicada.

Reter a saída por mais de 7 dias. O armazenamento de saída é temp por padrão (cerca de 7 dias). Defina "storage": "persistent" no nível superior na criação para manter a faixa por longo prazo (cobrado por tamanho), ou promova a saída temp depois.

Tratamento de erros. Uma chave inválida ou não autorizada retorna HTTP 401:

{"error":{"code":"permission_denied","message":"This API key cannot use the selected model. Please check permissions or use another key.","type":"hiapi_error"}}

Entradas malformadas retornam 400 com error_code: INVALID_REQUEST (como mostrado acima); saldo insuficiente retorna 402; um Content-Type que não seja JSON retorna 415. Se você encontrar um 503 intermitente, tente novamente com backoff — ele indica indisponibilidade temporária da plataforma, não erro na sua requisição.

Os preços do lyria-3-pro (e de todos os outros modelos da plataforma) estão listados na página de preços da hiapi, e não fixados aqui, pois as faixas podem mudar.

Recursos relacionados

• Referência do modelo lyria-3-pro — preços e playground desse modelo.
• Criar tarefa / Obter detalhes da tarefa (API assíncrona unificada) — o contrato compartilhado de requisição/resposta usado por todos os modelos na hiapi.
• API minimax-music-3: guia com curl e Python — outro modelo de texto para música, útil para comparar estilos de saída.
• Como usar a API MiniMax Music (minimax-music-1.5) — um modelo de geração de música MiniMax mais antigo, adequado para comparações de custo/qualidade.

Perguntas frequentes

É possível definir a duração da faixa gerada? Não. O schema de input do lyria-3-pro aceita apenas prompt e seed — não há campo duration, e a duração da faixa é determinada pelo próprio modelo.

O lyria-3-pro suporta prompts negativos ou áudio de referência de estilo? Não. Diferentemente de alguns outros modelos da plataforma, o schema do lyria-3-pro é estritamente limitado a prompt e seed; enviar negative_prompt ou qualquer campo de áudio de referência retorna 400 INVALID_REQUEST.

Qual é o formato do arquivo de saída? MP3, retornado em output[0].url, com type igual a "audio". A URL é um link temporário e expira conforme output[0].expireAt, a menos que "storage": "persistent" seja definido.

Como obter resultados reproduzíveis? Use o mesmo prompt e passe o mesmo seed (inteiro não negativo). Se o seed for omitido, cada chamada pode produzir resultados diferentes.

Qual é a forma mais rápida de depurar requisições que retornam 400 repetidamente? Leia o message — ele indica o campo específico ausente ou inválido. O schema é rigoroso: enviar campos que este modelo não aceita (como duration, que outros modelos de música da plataforma de fato aceitam) retorna 400 com o erro "additional properties not allowed".