Guia da API de LoRA do MiniMax H3: escolha um modo e verifique os pesos

Uma LoRA própria só vale a pena carregar se sobreviver ao plano de que você precisa: o personagem, o movimento e o som juntos. O MiniMax H3 LoRA no SpicyAPI (spicyapi.ai) é o modelo de vídeo H3 com pesos abertos e um campo loras: até três dos seus próprios arquivos .safetensors por requisição, cada um com uma força de 0 a 4.

Escolha a tarefa pelo material de partida e vincule um arquivo direto treinado para o H3. Comece na escala 1 para uma LoRA de estilo e de 0.6 a 0.8 para uma LoRA de conceito, e julgue um rascunho de 3 segundos em 480p ($0.15) contra a mesma requisição com loras vazio. Com base nos nossos testes de setembro de 2026, as três tarefas entregaram solicitações adultas, e o SpicyAPI não adiciona nenhum filtro de conteúdo extra aos pesos que você carrega.

Escolha a tarefa pelo material de partida

As três devolvem um MP4 de 3 a 15 segundos com som estéreo na mesma passagem, em 480p, 540p, 768p ou 1080p, e carregar LoRAs não custa nada extra. Sem nenhuma LoRA para carregar, o H3 base é mais barato. Para fechar um personagem ou um visual antes de pagar por segundos de vídeo, faça primeiro stills com o H3 Image LoRA; o mesmo array loras é aproveitado (stills contra vídeo).

Escolha uma LoRA que combine com o H3

O arquivo precisa ter sido treinado para o MiniMax H3. Uma LoRA de outro modelo base não é compatível; até os adaptadores do H3 exigem uma tarefa e um layout de pesos que o carregador aceite. As LoRAs do H3 são novas e a qualidade varia, então procure um cartão de modelo que nomeie a base, a palavra-gatilho e uma força que funcione. Dois arquivos que fazem isso e que carregam nesta API:

Os dois usam a H3 Community License, que tem limites de território e de uso; leia antes de qualquer trabalho comercial.

De um cartão de modelo, pegue apenas o gatilho e a força. Receitas escritas para ComfyUI local ou outros hosts incluem controles que esta tarefa não tem (prompt_expansion_mode, contagens de passos, samplers, weight_name, um nome de repositório no lugar de um link), e LoRAs de destilação de velocidade (Turbo) existem para cortar passos de amostragem local, então pule-as.

Vincule o arquivo

path tem de ser um link HTTPS direto que devolva o arquivo .safetensors sem login. No Hugging Face esse é o link /resolve/, não a página /blob/ da sua barra de endereço. A requisição não tem campo de credenciais, então um arquivo privado precisa de um link pré-assinado que continue válido até o job terminar. Troque main por um hash de commit para que a mesma requisição carregue o mesmo arquivo no mês que vem. Uma página /blob/, um arquivo ausente ou um repositório privado é recusado com 400 antes de existir qualquer tarefa. Se uma tarefa falhar depois de aceita, reenvie a requisição idêntica com "loras": []: se isso funcionar, o problema é o arquivo (acesso, compatibilidade ou efeito dele); se falhar também, olhe o prompt ou as entradas.

Teste primeiro no Playground

1. Abra a página de texto para vídeo, fique na aba Playground na visualização Form e entre com uma conta com saldo para executar. Imagem para vídeo e referência para vídeo têm páginas próprias (links na tabela acima).
2. Coloque a palavra-gatilho primeiro no Prompt e depois escreva o plano como uma linha do tempo curta (quem aparece, o que a pessoa faz, como a câmera se move) com o som em sua própria linha Audio:. Descrever em detalhe o que a LoRA já faz tende a brigar com os pesos.
3. Em Style LoRAs, cole o link direto do arquivo em LoRA file e defina Strength. Add item dá até três arquivos.
4. Escolha 480p em Resolution e 3 em Duration para um primeiro olhar barato, defina um Seed e execute.
5. Aperte Remove item, execute de novo com o mesmo prompt e a mesma seed e compare os dois clipes. Se parecerem iguais, a LoRA não fez nada (veja a tabela de falhas abaixo).

O Playground de texto para vídeo do MiniMax H3 na visualização Form, com o campo Prompt e o botão Run. A página de LoRA acrescenta uma seção Style LoRAs ao mesmo formulário.

O corpo da requisição do Playground é o mesmo JSON que a API aceita, então uma configuração que funciona aqui pode ser copiada direto para o código. As outras duas tarefas acrescentam suas próprias entradas:

• Imagem para vídeo acrescenta Input image (o quadro de abertura) e um Closing frame opcional. Escreva o que acontece depois dentro do quadro, não uma cena nova: com uma LoRA de conceito em 1, um prompt que levava o sujeito para outro quarto substituía o quadro de abertura, enquanto o mesmo quadro se mantinha quando o prompt descrevia movimento dentro dele. Não há campo de proporção de tela, então recorte o quadro no formato desejado primeiro e deixe espaço para o movimento.
• Referência para vídeo acrescenta Reference images (até 9), Reference videos (até 3) e Reference audio (até 3). Abra o prompt com uma frase curta por entrada, cada uma com uma função só: Picture 1 is the woman, Picture 2 is the room, Video 1 is the camera move, Audio 1 is her voice. Quando você pegar movimento de um clipe, diga com todas as letras que a pessoa vem da imagem e só o movimento vem do clipe; sem essa frase a bailarina do clipe veio junto com o movimento. Três bons stills preservam a identidade melhor que nove sobrepostos.

O Playground de cada página de modelo abre em um exemplo pronto, e o painel Request body dele mostra o JSON exato. Três execuções desses exemplos:

Os clipes de referência são cobrados pelos seus segundos além dos segundos de saída, até 15 segundos de clipe no total, então mantenha-os curtos.

Depois execute pelo código

Instale o SDK do Python (pip install spicyapi), defina SPICY_API_KEY no ambiente do seu servidor e execute a requisição de texto para vídeo abaixo. Para as outras tarefas, em imagem para vídeo troque model, remova aspect_ratio e acrescente image_url; para referência para vídeo troque model e acrescente reference_image_urls (aspect_ratio permanece).

import uuid
from spicyapi import SpicyClient, output_assets

client = SpicyClient()  # reads SPICY_API_KEY from the environment

task = client.create_task(
    model="minimax/h3-lora/text-to-video",
    input_data={
        "prompt": "vh5tape, worn VHS tape with light tracking noise. A woman in a red satin dress sits alone in a late-night diner booth, turns toward the camera and slowly smiles, neon light flickering in the rain-streaked window behind her. Slow push-in. Audio: rain on glass, a jukebox ballad muffled through the tape, quiet room hum.",
        "aspect_ratio": "4:3",
        "resolution": "480p",
        "duration_seconds": 5,
        "seed": 42,
        "loras": [{
            "path": "https://huggingface.co/KennethFal/vh5tape-vhs-lora-minimax-h3/resolve/d25a4ab75aba899aa508220321525c8465ac11af/vh5tape.safetensors",
            "scale": 1.0,
        }],
    },
    idempotency_key=str(uuid.uuid4()),
)

final = client.wait_for_terminal(task["taskId"])
if final["state"] != "succeeded":
    raise RuntimeError(f"{task['taskId']} ended as {final['state']}: {final.get('errorCode')}")
print(output_assets(final)[0]["url"])  # copy the video to your own storage now

Criar, esperar, baixar, novas tentativas e códigos de erro estão no guia de tarefas e na referência do SDK Python. Os arquivos gerados ficam por no máximo 14 dias, então veja retenção e entrega antes de construir sobre o link devolvido; para produção, a comparação entre sondagem e webhooks ajuda você a escolher.

Ou deixe um Agent executar

Quando um assistente deve rodar as gerações, as três ferramentas oficiais mostram o preço e pedem confirmação antes de uma chamada paga.

• CLI. Coloque o mesmo objeto input em t2v.json e então:

``bash spicyapi tasks create --model minimax/h3-lora/text-to-video --input-file t2v.json --wait ``

Veja a documentação da CLI; npx @spicyapi/cli funciona sem instalação.

• Servidor MCP. Adicione o servidor MCP ao seu assistente e pergunte: "Run MiniMax H3 LoRA text-to-video with this prompt and this weights link at strength 1, 480p, 3 seconds." Ele chama spicyapi_task_create, que para esperando sua confirmação de preço, e depois spicyapi_task_wait.
• Skill. npx skills add spicyapi-ai/spicy-skill instala o Agent Skill, que faz um assistente de programação ler o esquema do modelo ao vivo em vez de adivinhar campos.

Ajuste a força

scale vai de 0 a 4, e 1 é neutro. Comece as LoRAs de estilo em 1 e as LoRAs de conceito entre 0.6 e 0.8. Depois rode uma escada: o mesmo prompt e a mesma seed em 480p e 3 segundos, com escala 0.5, 0.8 e 1.1, mais uma execução com loras vazio. Mude uma coisa por execução. Uma seed fixa mantém as execuções comparáveis, não idênticas, então julgue o visual e a ação em vez dos pixels.

Fique com o degrau que se lê bem, ou escolha um ponto intermediário entre dois. Pare de subir a força quando o sujeito, a ação ou o som começarem a se quebrar; se a base já falha no plano, nenhuma escala conserta. Assista ao clipe inteiro em vez do primeiro quadro, e escute, porque uma LoRA também pode mudar o som (vh5tape abafa de propósito). O cartão do vh5tape também lista frases de prompt para desgaste leve, médio e forte; mude essas antes de passar de 1 a escala.

Combine até três

Teste cada arquivo sozinho antes de combinar. Uma LoRA de personagem treinada em retratos brilhantes pode brigar com um visual de fita pesado, e uma LoRA de movimento pode virar o sujeito para fora do enquadramento. Quando uma pilha dá errado, segure a seed e o prompt e remova uma entrada por vez: uma recuperação aponta para aquele adaptador ou para a interação dele com o resto da pilha. Baixe primeiro o peso mais forte. Decida antes qual requisito vence quando dois conflitam (identidade acima de textura, por exemplo) e teste de novo uma pilha que funcionou em texto antes de usá-la em um quadro fotográfico ou uma referência.

Quanto custa

• 3 segundos em 480p: $0.15. 5 segundos em 480p: $0.25. 5 segundos em 1080p: $1.00.
• As três requisições acima: $0.25 / $0.50 / $0.58.
• Uma base mais uma escada de três degraus, quatro clipes de 3 segundos em 480p: $0.60.
• Referência para vídeo, 5 segundos em 480p: $0.32 com uma imagem, $0.34 com duas, $1.37 em 1080p com uma imagem.
• Uma tarefa que falhou ou expirou normalmente não é cobrada; um clipe pronto de que você não gosta é.
• Uma cotação que inclui um clipe de referência reserva os 15 segundos inteiros do clipe: $1.20 para uma saída de 5 segundos em 480p. A cobrança se ajusta na duração real do clipe.

Rascunhe em 480p e 3 segundos, depois reenvie o vencedor uma vez em 768p ou 1080p com a mesma seed. Espere uma variação próxima, não uma cópia.

Quando a LoRA não faz nada ou o clipe sai errado

Uso sem censura

O SpicyAPI não adiciona filtro de conteúdo ao prompt, aos pesos nem à saída. Nesses testes nada foi recusado na nossa escala de conteúdo, que vai de L1 Sugestivo e L2 Temas maduros e L3 Forte até L4 Intenso, mais as sondagens L5a de contenção e L5b de gore, sem nenhuma LoRA carregada. Um ponto fraco: sem LoRA, imagem para vídeo suavizou L4 Intenso (uma cena íntima entre dois adultos) em duas de três execuções, enquanto a entrada de texto e a de referência renderizaram todos os níveis. Com uma LoRA comunitária para adultos carregada, as três tarefas renderizaram L4. Os resultados completos estão na análise do H3 LoRA.

O fato de o SpicyAPI não adicionar filtro de conteúdo extra não dá direitos sobre uma semelhança: todas as pessoas mostradas precisam ser adultas, e uma LoRA de uma pessoa real exige o consentimento dessa pessoa e os seus direitos sobre a semelhança dela.

Teste no playground do MiniMax H3 LoRA, que mostra os preços ao vivo.

FAQ

Posso colar o nome de um repositório do Hugging Face ou um link /blob/?

Não. path recebe um link HTTPS direto para o arquivo; uma página /blob/ ou um nome owner/repo sozinho é recusado com 400, e um campo weight_name, como alguns hosts aceitam, não tem equivalente aqui. Use o link /resolve/.

Posso carregar uma LoRA que eu mesmo treinei?

Sim, se ela foi treinada no H3 de pesos abertos, salva como .safetensors e acessível por HTTPS.