Execute sua própria LoRA em uma API hospedada: uma URL em vez de uma fila de upload

Um exemplo publicado de LoRA do Qwen Image 2.1: um peso de estilo carregado pelo campo loras.

Você tem uma LoRA treinada em .safetensors em um bucket ou em um repositório do Hugging Face e quer usá-la sem registrar, enviar ou esperar aprovação. No Qwen Image 2.1 LoRA isso é um campo da requisição: uma URL e um número de força, buscados quando a tarefa é executada. O modelo roda sem censura e os pesos que você aponta não são revisados.

Isso elimina a fila de upload e move uma dependência para o caminho da sua requisição: o host que serve seus pesos. Abaixo: como testar seu arquivo no Playground, o código para executá-lo, quais links quebrados falham na hora e quais falham depois, e quanto custa.

Os pontos principais

• Uma LoRA é um campo da requisição, não algo que você registra. loras aceita até três entradas {path, scale}; nada é enviado, escaneado ou aprovado.
• Os dois endpoints aceitam, texto para imagem e edição por referência, então os pesos também podem ser aplicados a quadros que você já tem.
• Alguns links quebrados falham na hora, outros só depois que a tarefa é aceita. Uma página web em vez de um arquivo dá 400; um host fora do ar ou um link que expira depois é aceito e falha em seguida, com a retenção reembolsada.
• Carregar não é o mesmo que funcionar. Compare com uma execução sem os pesos, mesmo prompt e mesma seed.
• A quantidade de LoRAs não muda o preço; na edição, muda a quantidade de imagens de referência.

Teste primeiro no Playground

1. Abra a página de texto para imagem e fique na aba Playground, na visão Form. Entre com uma conta com saldo para executar.
2. Escreva um prompt que descreva a cena, não o estilo; deixe os pesos carregarem o visual.
3. Em Style LoRAs, cole o link direto do arquivo em LoRA file e defina Strength (1 é um início normal). Add item dá até três pesos.
4. Escolha 1k para um primeiro olhar barato e então execute o modelo.
5. Para ver se os pesos fizeram alguma coisa, defina um Seed, execute uma vez, pressione Remove item e execute de novo com o mesmo prompt e a mesma seed.

O corpo da requisição do Playground é o mesmo JSON que a API aceita, então uma configuração que funciona aqui vai direto para o código. Se falhar aqui, conserte o link ou os pesos antes de escrever uma linha de código.

Depois execute pelo código

Instale o SDK de Python (pip install spicyapi), defina SPICY_API_KEY no ambiente do seu servidor e execute:

import uuid
from spicyapi import SpicyClient, output_assets

client = SpicyClient()  # reads SPICY_API_KEY from the environment

task = client.create_task(
    model="alibaba/qwen-image-2.1-lora/text-to-image",
    input_data={
        "prompt": "A fishing harbour at first light, rowing boats at their moorings, "
                  "the far quay dissolving into mist over the water.",
        "loras": [{
            "path": "https://huggingface.co/your-account/your-style-lora/resolve/<commit-sha>/style.safetensors",
            "scale": 1,
        }],
        "aspect_ratio": "3:2",
        "resolution": "1k",
        "output_format": "webp",
    },
    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 image to your own storage now

Criação, espera, download, novas tentativas e códigos de erro estão no guia de tarefas e na referência do SDK de Python. Os resultados expiram, então veja retenção e entrega antes de construir sobre o link retornado.

Ou deixe um agente 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 input.json e então:

``bash spicyapi tasks create --model alibaba/qwen-image-2.1-lora/text-to-image --input-file input.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 então peça: "Execute Qwen Image 2.1 LoRA com este prompt e este link de pesos na força 1." Ele chama spicyapi_task_create, que para para 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 código ler o esquema do modelo ao vivo em vez de adivinhar campos.

O array loras

loras aceita até três entradas { "path", "scale" } nos dois endpoints, texto para imagem e edição por referência (de 1 a 10 imagens).

• Use um link de arquivo, não uma página de repositório. Uma URL de repositório do Hugging Face ou uma página blob/main/... é rejeitada. Use o link resolve/... para o próprio arquivo.
• Não há registro. Você nunca recebe um identificador para um peso e não existe lista de "minhas LoRAs". A seed estabiliza uma série, mas não reproduz um quadro; portanto guarde a lista {path, scale}, o prompt, as configurações e o ID da tarefa ao lado de cada saída.

Escolha pesos documentados como compatíveis com a tarefa exata. Os exemplos publicados do Qwen Image 2.1 incluem adaptadores de geração 2512 e adaptadores de edição Edit 2511/2509, então uma versão mais antiga no nome do arquivo não torna o arquivo incompatível por si só. Essas tarefas mais antigas também estão disponíveis pelo Qwen Image 2512 LoRA, e nosso guia Qwen Image 2.1 LoRA cobre quais arquivos antigos continuam válidos.

Quais links quebrados falham no envio

Quando você envia pesos, a API testa o link. Se o host responde e o que volta não é um arquivo, você recebe 400 antes de existir qualquer tarefa e antes de qualquer valor ser retido:

As imagens de referência do endpoint de edição recebem o mesmo tratamento: um arquivo image_urls ausente é um 400 que nomeia o host.

As duas linhas aceitas são contra as quais você precisa se proteger. Um link que morre depois (um link assinado expirado, um repositório que fica privado, um arquivo renomeado ou excluído) faz falhar toda requisição que o referencia, porque os pesos são buscados em cada tarefa. Com base no nosso teste de outubro de 2026, uma tarefa cujo host de pesos não resolve foi aceita e falhou logo em seguida (cerca de 3 segundos) com invalid_request; a retenção foi reembolsada (cost era 0, settled era true) e a mensagem dizia que uma LoRA não pôde ser carregada do link informado. invalid_request também é o que uma entrada inválida retorna, então o código sozinho não aponta o link, e com vários pesos a mensagem não nomeia a entrada. Prepare o diagnóstico antes de precisar dele: após uma cotação aceita, uma falha invalid_request significa verificar primeiro as URLs dos pesos.

Isole o problema esvaziando o array

Quando uma tarefa aceita falha, envie a mesma requisição uma vez com loras vazio e sem mudar mais nada. O sucesso aponta para o adaptador, para o carregamento dele ou para a interação com a requisição; verifique link, formato de arquivo, compatibilidade e pilha um de cada vez. Uma segunda falha faz o código de erro da tarefa, as imagens de origem e o status do serviço serem as próximas verificações.

Mantenha um peso canário

Mantenha um arquivo de pesos pequeno que você mesmo hospeda, nunca rotacionado e com efeito inconfundível, como um peso de estilo forte. Quando um lote começa a falhar, execute uma geração com o canário. Se funcionar, suspeite da sua URL de pesos. Se também falhar, verifique o errorCode da tarefa e o status do serviço antes de mexer nas configurações de armazenamento.

Verifique no deploy, não a cada requisição

Execute uma cotação gratuita (spicyapi tasks quote --model alibaba/qwen-image-2.1-lora/text-to-image --input-file input.json) para cada URL de pesos que sua configuração referencia, no seu pipeline de deploy e na inicialização do serviço. Isso pega links claramente inutilizáveis, não a compatibilidade do adaptador. Não peça cotação antes de cada geração; isso adiciona latência e o link ainda pode morrer um minuto depois.

Fixe o endereço para que ele não possa se mover

• Hugging Face: resolve/main/... acompanha um branch. Fixe o commit: resolve/<commit-sha>/<file>.safetensors.
• Seu próprio armazenamento: coloque um hash de conteúdo na chave, como character-v7-4f9c81.safetensors, e nunca sobrescreva uma chave.
• URLs assinadas que expiram: evite-as em configurações duradouras. Para tarefas recorrentes use um endereço estável, ou gere um link novo pouco antes de cada envio que sobreviva à tarefa e a qualquer nova tentativa.
• Repositórios de terceiros: autores podem renomear, bloquear ou excluir um repositório a qualquer momento. Se um arquivo for essencial, copie-o para um armazenamento que você controla, respeitando a licença dele, e fixe sua cópia.

A LoRA fez alguma coisa?

Um exemplo de estilo publicado do Qwen Image 2.1 LoRA. Mostra o que um peso de estilo pode fazer em um quadro.

A resposta não tem nenhum campo dizendo que seus pesos foram aplicados, então julgue pela imagem. Um arquivo pode ser buscado corretamente e ainda assim mudar quase nada, por causa de pesos incompatíveis, uma frase de ativação ausente, escala fraca ou adaptadores sobrepostos.

1. Escolha um prompt cuja falha seja óbvia: um assunto que o modelo base renderiza de forma fotográfica, com um estilo que o peso deve impor.
2. Descreva a cena, não o estilo. Peça "loose impressionist brushwork" e o prompt sozinho produz isso, então você vai registrar o peso como funcionando. Deixe o arquivo carregar o visual.
3. Execute o mesmo prompt e a mesma seed sem pesos e compare. Se o resultado for indistinguível, a comparação não mostrou efeito visível do adaptador.
4. Mude um valor por vez: escala 1, depois 2, depois 3. Um peso que fica visivelmente mais forte estava apenas fraco; um que permanece inerte em cada etapa provavelmente foi feito para outra base. Verifique também o modelo base e as palavras de ativação recomendadas pelo autor.
5. Escreva o veredito ao lado da URL e mantenha pesos conformes e não conformes em listas separadas.

Os pesos são buscados antes da geração, então a primeira chamada com um arquivo novo é mais lenta em dezenas de segundos, mais para arquivos grandes (cerca de 25 segundos a mais para um arquivo de 1.2 GB). Reserve de 90 a 120 segundos para a chamada a frio.

Três espaços

Três entradas cobrem a pilha usual: um peso de personagem que sustenta a pessoa, um peso de estilo da casa com menos força e um peso de detalhe para pele ou tecido.

• Mova uma escala por execução. Se você mudar duas, não consegue atribuir o resultado.
• Deixe espaço para os pesos de apoio. Um peso de estilo com a mesma força do peso de personagem tende a lutar com ele; coloque a entrada de apoio bem abaixo de 1.
• Não repita no prompt o que um peso já carrega.
• Esta família não tem prompt negativo. Coloque as exclusões no prompt.

Quanto custa

Os preços são por imagem:

• A quantidade de LoRAs não muda o preço. Uma entrada e três têm a mesma cotação.
• Carregar pesos tem custo adicional sobre o modelo base. Qwen Image 2.1 sem o array custa $0,024 em 1k e $0,048 em 2k, então uma tarefa que não precisa de pesos deve chamar a família base.
• Na edição, cada imagem de referência extra soma um valor fixo: $0,012 em 1k e $0,024 em 2k.

Em resumo: a requisição que mais custa é a de muitas imagens de referência em 2k, não a de três LoRAs.

Cem quadros de texto para imagem custam $3,00 em 1k e $10,20 em 2k; cem edições com dez referências em 2k custam $36,60. Itere em 1k e promova os melhores para 2k.

Editando com pesos

Aplique um peso de personagem a um quadro que você já aprovou, com um peso de estilo da casa por baixo e com menos força:

{
  "model": "alibaba/qwen-image-2.1-lora/edit",
  "input": {
    "prompt": "The source image is the character. Keep her face, her hair and the cut of the coat exactly as they are. Restage her on a wet city street at night, lit by shop windows from the left.",
    "image_urls": ["https://cdn.example.com/approved/frame-0412.png"],
    "loras": [
      { "path": "https://cdn.example.com/weights/character-v7-4f9c81.safetensors", "scale": 1 },
      { "path": "https://cdn.example.com/weights/house-grade-v2-0ab3de.safetensors", "scale": 0.45 }
    ],
    "aspect_ratio": "4:5",
    "resolution": "2k"
  }
}

Envie com o mesmo código, usando alibaba/qwen-image-2.1-lora/edit como modelo. Copie os valores dos campos do esquema ao vivo na página do modelo; o guia de geração de imagens explica como os endpoints de imagem diferem.

Pesos sem censura e de categorias restritas

Esta família é sem censura: não há flag de maturidade, não há revisão dos pesos que você aponta e não há varredura de conteúdo adicionada pela SpicyAPI. Suas obrigações continuam as mesmas: apenas adultos, pesos e dados de treinamento que você tem direito de usar, nenhum menor em nenhuma entrada ou saída, nenhuma imagem íntima sem consentimento e nenhuma imitação enganosa de uma pessoa real identificável.

Próximos passos

Para o modelo base, veja nosso teste do Qwen Image 2.1; para edição sem campo de máscara, nosso teste do Qwen Image Edit. O catálogo mais amplo de modelos de imagem lista o esquema ao vivo e a estimativa de cada modelo.

Perguntas frequentes

Posso executar minha própria LoRA em uma API sem fazer upload?

Sim. loras aceita até três entradas {path, scale}, onde path é um link direto para um arquivo .safetensors. Não existe endpoint de upload, fila de aprovação nem lista de permissões.

Ele aceita links do Hugging Face?

Sim, como https://huggingface.co/<user>/<repo>/resolve/<commit-sha>/<file>.safetensors. Páginas de repositório, páginas blob/ e caminhos privados ou inexistentes são rejeitados.

Por que minha requisição de LoRA falhou sem erro útil?

Na maioria das vezes o path não funcionou mais depois que a tarefa foi aceita. Host fora do ar, link assinado expirado ou repositório que ficou privado falham com invalid_request, que também é retornado por entrada inválida, então o código sozinho não nomeia o link. A retenção é reembolsada. Isole o problema com loras vazio, ou verifique primeiro as URLs dos pesos.

Minha LoRA quase não muda a imagem. O que está errado?

Verifique a compatibilidade declarada, a frase de ativação e a escala; depois compare-a sozinha, sem as outras entradas. Arquivos antigos do Qwen não são todos incompatíveis: vários são usados nos exemplos publicados deste endpoint. Siga os passos de escala acima antes de descartar o arquivo.

Quantas LoRAs posso empilhar e empilhar custa mais?

Três por requisição, cada uma com sua própria força. A quarta é rejeitada na hora. Uma entrada e três têm o mesmo preço, então escolha os pesos de que precisa, não menos. Na edição, o que mexe no preço é a quantidade de imagens de referência.

Posso usar uma LoRA ao editar uma imagem existente?

Sim. O endpoint de edição aceita o mesmo array loras com uma a dez imagens de referência. Envie o quadro aprovado como referência, diga no prompt o que deve mudar e deixe os pesos carregarem a identidade.

O que scale faz e o que devo definir?

Ele pesa a LoRA em relação ao modelo base, de 0 a 4, com 1 como força inicial usual. Abaixo de 1 o visual fica mais discreto, acima de 1 um peso domina.

Como reproduzo uma imagem feita com uma pilha específica?

Guarde a pilha. Não há registro e a seed não reproduz um quadro, então mantenha a lista {path, scale}, o prompt e as configurações ao lado da saída, com cada caminho fixado em um endereço que não pode se mover.