Guia de uso
Gerar BGM com letras personalizadas para vídeos de produtos de e-commerce usando mureka-9.5 no HiAPI
Guia para desenvolvedores: transformar texto de produto em música utilizável em anúncios e mixá-la no vídeo
Nesta página
Por que uma música personalizada supera a BGM pronta para vídeos de produto
Música pronta é um problema resolvido no sentido de ser barata e imediata, mas para e-commerce ela resolve o problema errado. Faixas licenciadas são, por definição, genéricas: foram escritas antes de seu produto existir, não contêm o nome do produto, não contêm o argumento de venda e não contêm uma chamada para ação. Em um vídeo de feed de 15 segundos, o espectador talvez ouça apenas os três primeiros segundos; música genérica é preenchimento, não persuasão.
Modelos de letra para música como mureka-9.5/lyrics-to-song mudam a economia dessa decisão. Você fornece a letra e o modelo retorna uma faixa cantada que nomeia o produto e enuncia a oferta. A diferença crucial em relação à música de fundo: a faixa em si se torna um canal de copy, funcionando mesmo que o espectador nunca leia as legendas.
Use BGM pronta quando:
- o vídeo for uma vitrine puramente visual, com o texto na tela;
- você precisar de dezenas de variações por dia e o tom da marca não for uma restrição;
- o produto não tiver um nome, argumento de venda ou oferta que valha a pena cantar.
Use faixas geradas com letra quando:
- o nome do produto ou um argumento curto for o gancho;
- você produz criativos reutilizáveis para cada SKU e quer uma identidade sonora reconhecível;
- você precisa de um ativo parecido com um jingle que possa iterar editando texto em vez de relicenciar música;
- você quer controlar ritmo e humor por prompt em vez de busca em catálogo musical.
O trade-off é honesto: a geração adiciona uma etapa de requisição e renderização, e vocais cantados exigem mais controle de qualidade do que uma base instrumental. O restante deste guia trata esse trade-off como um problema de engenharia e apresenta um pipeline reutilizável.
Uma estrutura prática para desenvolvedores: trate a faixa com letra como mais um ativo gerado no pipeline de mídia do produto, ao lado de thumbnails e vídeos curtos. Ela tem entradas (atributos do produto), uma etapa de renderização (chamada de API) e uma saída que precisa passar por verificações antes da entrega.
Transformar o texto do produto em letras cantáveis
A falha mais comum em anúncios com letra para música é enviar o texto de marketing. Um modelo que canta vai cantar o que você entregar, inclusive uma lista de recursos com 40 palavras, e o resultado não caberá em um corte de 15 segundos. A correção acontece antes da chamada de API: comprimir o texto do produto em frases curtas com estrutura fixa.
Estrutura de quatro slots
Mapeie cada produto para quatro slots:
- Identidade — nome do produto mais uma dica de categoria ("caneca de cerâmica que mantém o calor").
- Benefício — um resultado concreto, não uma lista ("o café continua quente até o meio-dia").
- Prova ou diferenciação — um único detalhe sensorial ou de material.
- Chamada para ação — um imperativo curto ligado à loja.
Cada slot vira uma ou duas linhas de letra. Mantenha as frases curtas: cerca de 5 a 9 sílabas por linha é uma meta segura de cantabilidade e mantém as frases cantadas dentro de poucos segundos de áudio. Evite números em preços, evite avisos legais, evite orações entre parênteses, porque tudo isso é difícil de cantar e costuma sair embolado.
Derivar letras programaticamente
Armazene os slots como campos estruturados no registro do produto e depois monte com template, em vez de concatenação livre de strings:
[verse]
{identity_line}
{benefit_line}
[chorus]
{product_name}, {benefit_short}
{cta_line}
O template é o contrato entre os dados do seu catálogo e o modelo. Quando um redator reescreve uma linha, apenas o campo muda; o template permanece estável, então o comprimento e a estrutura da saída permanecem previsíveis entre SKUs.
Orçamento de duração
Estime a duração pelo número de linhas antes de renderizar. Um anúncio de 15 segundos acomoda confortavelmente um verso mais um refrão curto; um anúncio de 30 segundos permite repetir o refrão uma segunda vez. Se a letra montada estourar o orçamento, corte primeiro o slot de prova, não a chamada para ação. Escreva a verificação de orçamento como asserção no gerador, para que descrições de produto prolixas não produzam silenciosamente faixas inutilizáveis.
Por fim, coloque o texto original do produto e a letra derivada lado a lado. Quando uma palavra for pronunciada errado na faixa retornada, você precisa saber se foi o campo de origem ou a formulação que causou isso.
Construir a requisição HiAPI para mureka-9.5/lyrics-to-song
Todo acesso a modelo passa pela interface unificada do HiAPI, então o formato da requisição é o mesmo que você usa para outros modelos de mídia: autentique com sua chave HiAPI, especifique o identificador de modelo mureka-9.5/lyrics-to-song e envie a carga de letra e a orientação de estilo.
Estrutura da requisição
Uma requisição mínima contém:
- model —
mureka-9.5/lyrics-to-song. - lyrics — o texto com tags de seção montado na etapa anterior. Mantenha as tags
[verse]/[chorus]; elas dizem ao modelo como organizar a estrutura da música. - prompt de estilo — gênero, humor, andamento e instrumentação, expressos com adjetivos ou frases (por exemplo, "bright indie pop, mid tempo, acoustic guitar, clean female vocal").
- flag instrumental — mantenha false quando você quer vocais com letra; defina true apenas quando precisar de acompanhamento puramente instrumental.
{
"model": "mureka-9.5/lyrics-to-song",
"lyrics": "[verse]\nHand-thrown stoneware, morning light\n[chorus]\nKeep the heat till the afternoon\nShop the stoneware line today",
"style": "warm indie pop, mid tempo, clean vocal",
"instrumental": false
}
Tratar a resposta
Na maioria dos fluxos de trabalho, a chamada retorna uma referência ao ativo de áudio em vez de bytes inline. Trate-a como tarefa assíncrona: envie, faça polling ou aguarde um sinal de conclusão e depois baixe o áudio para seu próprio bucket, com chave {sku}/{variant}/{hash-of-lyrics-and-style}. O hash importa porque torna a renderização idempotente; reexecutar um lote não cria ativos duplicados.
Encapsule a chamada em um cliente fino com três responsabilidades: repetir com backoff em falhas transitórias, validar que a duração retornada está dentro do seu orçamento e registrar a carga da requisição junto com o ativo para reprodução. Não deixe uma renderização com falha bloquear a montagem do vídeo; ao verificar o erro, faça fallback para uma faixa em cache daquela linha de produto.
Coloque o prompt de estilo no arquivo de configuração de cada campanha, em vez de codificá-lo no construtor de requisições. Assim, atualizações sazonais são mudanças de configuração, não mudanças de código, e todo SKU da campanha mantém consistência sonora.
Mixar a faixa gerada no seu pipeline de vídeo
A faixa gerada é um ativo criativo bruto; o corte final precisa de duração e nível previsíveis. A maioria dos problemas aparece aqui, não na geração.
Ajustar a duração ao corte
Meça a duração do áudio retornado e compare com a linha de tempo do vídeo. Duas estratégias seguras:
- Cortar em fronteiras musicais — corte no fim de uma frase cantada e aplique um fade-out de cerca de 300–500 ms para que a cauda não produza clique.
- Loop em pontos alinhados à batida — se a faixa for mais curta que o vídeo, faça loop em fronteiras de refrão, não em timestamps arbitrários, para evitar costuras audíveis.
Se a faixa for claramente mais longa que o vídeo, não corte simplesmente; re-renderize com um orçamento de letra mais curto. Cortar no meio de uma palavra é a falha mais óbvia em anúncios cantados.
Níveis antes da mixagem
Normalize a música para um alvo de loudness consistente em relação à locução (se houver) e comprima a música sob a voz com sidechain ou uma curva simples de automação de volume. Se o vídeo não tiver narração, a faixa pode ficar mais alta, mas deixe margem para que a normalização de loudness da plataforma não a achate. Aplique um fade-in curto no início do vídeo para que o áudio não comece abruptamente no autoplay.
Mixagem
Use seu pipeline de codificação existente — ffmpeg ou um transcoder gerenciado — e trate o áudio como mais um stream de entrada:
ffmpeg -i product.mp4 -i track.wav \
-filter_complex "[1:a]afade=t=in:st=0:d=0.4,afade=t=out:st=14.6:d=0.4[a]" \
-map 0:v -map "[a]" -c:v copy -c:a aac -shortest out.mp4
A disciplina importante é que o stream de vídeo seja copiado, não recodificado, para que substituir a música não degrade a qualidade da imagem. Mantenha a etapa de mixagem parametrizada pelos pontos de fade e marcadores de loop, para que variações de 15 e 30 segundos venham do mesmo caminho de código.
Armazene a faixa gerada separadamente do vídeo mixado. Quando atualizar o criativo, remixe em vez de re-renderizar a música.
Verificações de qualidade antes da entrega à loja
Automatize o que puder e confie na escuta para o resto. Uma lista curta de verificação pré-lançamento captura quase todos os modos de falha.
Portões automáticos
- Duração — dentro da janela alvo do posicionamento (por exemplo, limite do slot de anúncio).
- Loudness — loudness integrado dentro da faixa esperada pela plataforma; fora dela, a build falha.
- Silêncio e clipping — nenhum trecho silencioso inesperado e nenhum pico em escala máxima.
- Vinculação de ativos — hash da faixa, carga de letra e registro do produto documentados para a saída.
Portões humanos
- Clareza da letra — um ouvinte de primeira viagem consegue entender o nome do produto em uma única escuta? Se não, simplifique as frases; não desacelere o andamento.
- Pronúncia — nomes de marca e palavras incomuns são as vítimas habituais; verifique uma a uma contra uma lista conhecida.
- Adequação à marca — gênero e timbre vocal combinam com a categoria. Uma faixa de alta energia em um produto premium ou discreto será percebida como erro.
- Timing — a chamada para ação aparece enquanto o produto ainda está na tela, não depois que ele desaparece.
- Áudio — monte o áudio no gráfico de mixagem.
Execute esses portões por variante, não por lote. Uma pronúncia ruim em um lote entre cem é exatamente o caso que escapa para a loja. Mantenha uma pequena ferramenta de audição que busca as últimas renderizações de uma linha de produto e as reproduz em sequência; leva só alguns minutos e captura problemas estruturais que as métricas não encontram.
Quando uma verificação falhar, corrija a entrada — linha da letra, prompt de estilo ou orçamento de duração — e re-renderize com a mesma chave de cache, para que o novo ativo substitua o antigo de forma limpa.
Escalar para o catálogo de produtos
Um único vídeo principal é uma demonstração; o catálogo é o sistema. A meta é consistência em escala sem ouvir cada faixa novamente.
Agrupar por linha de produto, não por SKU
Agrupe SKUs que compartilham categoria, formato de argumento de venda e tom de marca; depois renderize um prompt de estilo e um template de letra para cada grupo. Variantes dentro do grupo diferem apenas nos campos preenchidos. Isso dá consistência sonora nas páginas de categoria, preserva a identidade de cada produto e reduz drasticamente o número de prompts distintos que você precisa revisar.
Cache e deduplicação
Use como chave de cada ativo o hash da carga de letra, do prompt de estilo e da versão do modelo. Entradas iguais retornam o ativo em cache; apenas campos alterados disparam nova renderização. Assim, re-renderizar o catálogo quando você ajusta uma linha de um produto fica barato, e cada criativo tem uma URL estável para o pipeline de vídeo referenciar.
Fila e backoff
Envie renderizações por uma fila de tarefas com concorrência limitada e retries. Atualizações de catálogo são em rajadas; a fila as suaviza e permite priorizar produtos com campanhas próximas. Registre a carga da requisição por tarefa, para que renderizações com falha sejam reproduzidas sem adivinhação.
Manter a governança criativa leve
Versione templates e prompts de estilo no mesmo repositório dos dados de produto. Assim, mudanças no template de refrão podem ser revisadas como código, e você consegue ver exatamente quais produtos foram renderizados com qual revisão de template. Aposente ativos antigos quando o template mudar, em vez de deixar revisões misturadas coexistindo na loja.
Comece com uma linha de produto, valide o caminho de letra até mixagem de ponta a ponta e depois expanda categoria por categoria. O pipeline que você constrói — campos de letra estruturados, requisições HiAPI idempotentes, etapa de mixagem e uma lista curta de verificação — permanece o mesmo à medida que o catálogo cresce; só o volume muda. Quando estiver pronto para fazer a primeira requisição, explore o modelo no HiAPI.
Artigos relacionados
Ver todos os artigos →-
Guia de uso
Guia de introdução ao gpt-6.2-sol: limites de capacidade, integração via API e noções de precificação por token
Decisões de integração e pontos práticos para equipes de engenharia
-
Guia de uso
Guia de introdução ao gpt-6.2-astra: limites de capacidade do modelo de texto, pontos de integração e controle de custos
-
Guia de uso
Guia de introdução ao Tripo H3.1: três modos de entrada, parâmetros e como escolher o preço
Decisão de integração e controle de custos na geração 3D para desenvolvedores