Exécutez votre propre LoRA sur une API hébergée : une URL au lieu d'une file d'attente

Un exemple publié de LoRA Qwen Image 2.1 : un poids de style chargé via le champ loras.

Vous avez une LoRA entraînée au format .safetensors dans un bucket ou dans un dépôt Hugging Face, et vous voulez l'utiliser sans l'enregistrer, l'envoyer ni attendre une validation. Sur Qwen Image 2.1 LoRA, c'est un champ de requête : une URL et un nombre de force, récupérés au moment où la tâche s'exécute. Le modèle s'exécute sans censure et les poids que vous visez ne sont pas examinés.

Cela supprime la file d'attente d'envoi et déplace une dépendance dans le chemin de votre requête : l'hébergeur qui sert vos poids. Ci-dessous : comment essayer votre fichier dans le Playground, le code pour l'exécuter, quels liens défaillants échouent tout de suite et lesquels plus tard, et ce que cela coûte.

L'essentiel

• Une LoRA est un champ de requête, pas quelque chose à enregistrer. loras accepte jusqu'à trois entrées {path, scale} ; rien n'est envoyé, analysé ni approuvé.
• Les deux endpoints l'acceptent, texte vers image et édition par référence, les poids peuvent donc aussi s'appliquer aux images que vous possédez déjà.
• Certains liens défaillants échouent tout de suite, d'autres seulement après acceptation de la tâche. Une page web au lieu d'un fichier donne un 400 ; un hébergeur mort ou un lien qui expire plus tard est accepté puis échoue ensuite, la retenue étant remboursée.
• Charger n'est pas travailler. Comparez avec une exécution sans les poids, même prompt et même seed.
• Le nombre de LoRAs ne change pas le prix ; en édition, c'est le nombre d'images de référence qui le change.

Essayez d'abord dans le Playground

1. Ouvrez la page texte vers image et restez dans l'onglet Playground, en vue Form. Connectez-vous avec un compte approvisionné pour lancer.
2. Écrivez un prompt qui décrit la scène, pas le style ; laissez les poids porter l'apparence.
3. Sous Style LoRAs, collez le lien direct du fichier dans LoRA file et réglez Strength (1 est un départ normal). Add item donne jusqu'à trois poids.
4. Choisissez 1k pour un premier aperçu économique, puis lancez le modèle.
5. Pour voir si les poids ont fait quelque chose, fixez une Seed, lancez une fois, appuyez sur Remove item, puis relancez avec le même prompt et la même seed.

Le corps de requête du Playground est le même JSON que celui que l'API accepte : une configuration qui fonctionne ici se recopie telle quelle dans le code. Si cela échoue ici, corrigez le lien ou les poids avant d'écrire une ligne de code.

Exécutez ensuite depuis le code

Installez le SDK Python (pip install spicyapi), définissez SPICY_API_KEY dans l'environnement de votre serveur et exécutez :

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

La création, l'attente, le téléchargement, les reprises et les codes d'erreur sont couverts dans le guide des tâches et la référence du SDK Python. Les résultats expirent, consultez donc rétention et livraison avant de construire sur le lien renvoyé.

Ou laissez un agent l'exécuter

Quand un assistant doit lancer les générations, les trois outils officiels affichent le prix et vous demandent avant un appel payant.

• CLI. Mettez le même objet input dans input.json, puis :

``bash spicyapi tasks create --model alibaba/qwen-image-2.1-lora/text-to-image --input-file input.json --wait ``

Voir la documentation CLI ; npx @spicyapi/cli fonctionne sans installation.

• Serveur MCP. Ajoutez le serveur MCP à votre assistant, puis demandez : « Lancez Qwen Image 2.1 LoRA avec ce prompt et ce lien de poids à la force 1. » Il appelle spicyapi_task_create, qui s'arrête pour votre confirmation de prix, puis spicyapi_task_wait.
• Skill. npx skills add spicyapi-ai/spicy-skill installe l'Agent Skill, qui fait lire à un assistant de code le schéma du modèle en direct au lieu de deviner les champs.

Le tableau loras

loras accepte jusqu'à trois entrées { "path", "scale" } sur les deux endpoints, texte vers image et édition par référence (de 1 à 10 images).

• Utilisez un lien de fichier, pas une page de dépôt. Une URL de dépôt Hugging Face ou une page blob/main/... est rejetée. Utilisez le lien resolve/... vers le fichier lui-même.
• Il n'y a pas de registre. Vous n'obtenez jamais d'identifiant pour un poids et il n'existe pas de liste « mes LoRAs ». La seed stabilise une série mais ne reproduit pas une image ; conservez donc la liste {path, scale}, le prompt, les réglages et l'ID de tâche à côté de chaque sortie.

Choisissez des poids documentés comme compatibles avec la tâche exacte. Les exemples publiés Qwen Image 2.1 incluent des adaptateurs de génération 2512 et des adaptateurs d'édition Edit 2511/2509 : une version plus ancienne dans un nom de fichier ne rend donc pas un fichier incompatible à elle seule. Ces tâches plus anciennes sont aussi disponibles via Qwen Image 2512 LoRA, et notre guide Qwen Image 2.1 LoRA couvre les anciens fichiers qui restent valides.

Quels liens défaillants échouent à la soumission

Quand vous soumettez des poids, l'API teste le lien. Si l'hébergeur répond et que ce qui revient n'est pas un fichier, vous obtenez un 400 avant qu'aucune tâche n'existe et avant qu'aucun fonds ne soit retenu :

Les images de référence de l'endpoint d'édition reçoivent le même traitement : un fichier image_urls manquant est un 400 nommant l'hébergeur.

Les deux lignes acceptées sont celles contre lesquelles vous devez vous protéger. Un lien qui meurt ensuite (un lien signé expiré, un dépôt devenu privé, un fichier renommé ou supprimé) fait échouer toute requête qui le référence, car les poids sont récupérés à chaque tâche. D'après notre test d'octobre 2026, une tâche dont l'hébergeur de poids ne résout pas a été acceptée puis a échoué rapidement (environ 3 secondes) avec invalid_request ; la retenue a été remboursée (cost valait 0, settled valait true) et le message indiquait qu'une LoRA n'avait pas pu être chargée depuis le lien fourni. invalid_request est aussi ce que renvoie une entrée incorrecte, donc le code seul ne désigne pas le lien, et avec plusieurs poids le message ne nomme pas l'entrée. Préparez le diagnostic avant d'en avoir besoin : après un devis accepté, un échec invalid_request signifie vérifier d'abord les URL des poids.

Réduisez le problème en vidant le tableau

Lorsqu'une tâche acceptée échoue, envoyez la même requête une fois avec loras vide et sans rien changer d'autre. Un succès désigne l'adaptateur, son chargement ou son interaction avec la requête ; vérifiez le lien, le format de fichier, la compatibilité et la pile un par un. Un second échec rend le code d'erreur de la tâche, les images sources et l'état du service les prochaines vérifications.

Gardez un poids canari

Gardez un petit fichier de poids que vous hébergez vous-même, que vous ne faites jamais tourner et dont l'effet est indubitable, comme un poids de style marqué. Quand un lot commence à échouer, lancez une génération avec le canari. Si elle fonctionne, suspectez votre URL de poids. Si elle échoue aussi, vérifiez l'errorCode de la tâche et l'état du service avant de toucher au stockage.

Vérifiez au déploiement, pas à chaque requête

Lancez un devis gratuit (spicyapi tasks quote --model alibaba/qwen-image-2.1-lora/text-to-image --input-file input.json) pour chaque URL de poids référencée par votre configuration, dans votre pipeline de déploiement et au démarrage du service. Cela repère les liens manifestement inutilisables, pas la compatibilité de l'adaptateur. Ne demandez pas de devis avant chaque génération : cela ajoute de la latence et le lien peut encore mourir une minute plus tard.

Figez l'adresse pour qu'elle ne puisse pas bouger

• Hugging Face : resolve/main/... suit une branche. Figez le commit : resolve/<commit-sha>/<file>.safetensors.
• Votre propre stockage : mettez une empreinte de contenu dans la clé, comme character-v7-4f9c81.safetensors, et n'écrasez jamais une clé.
• URL signées expirables : évitez-les dans une configuration durable. Pour les tâches récurrentes, utilisez une adresse stable, ou générez un lien neuf juste avant chaque soumission, qui survit à la tâche et aux reprises.
• Dépôts tiers : les auteurs peuvent renommer, fermer ou supprimer un dépôt à tout moment. Si un fichier est indispensable, copiez-le dans un stockage que vous contrôlez, sous réserve de sa licence, et figez votre copie.

La LoRA a-t-elle fait quelque chose ?

Un exemple de style publié Qwen Image 2.1 LoRA. Il montre ce qu'un poids de style peut faire sur une image.

La réponse ne contient aucun champ indiquant que vos poids ont été appliqués, jugez donc sur l'image. Un fichier peut être récupéré correctement et ne changer presque rien, à cause de poids incompatibles, d'une phrase déclencheuse manquante, d'une échelle faible ou d'adaptateurs qui se chevauchent.

1. Choisissez un prompt dont l'échec est évident : un sujet que le modèle de base rend de façon photographique, avec un style que le poids doit imposer.
2. Décrivez la scène, pas le style. Demandez « loose impressionist brushwork » et le prompt seul le produit, vous classerez donc le poids comme fonctionnel. Laissez le fichier porter l'apparence.
3. Lancez le même prompt et la même seed sans poids et comparez. Si le résultat est indiscernable, la comparaison n'a pas montré d'effet visible d'adaptateur.
4. Changez une valeur à la fois : échelle 1, puis 2, puis 3. Un poids qui devient visiblement plus fort était simplement faible ; un poids qui reste inerte à chaque étape est probablement construit pour une autre base. Vérifiez aussi le modèle de base et les mots déclencheurs recommandés par l'auteur.
5. Écrivez le verdict à côté de l'URL et gardez les poids conformes et non conformes dans des listes séparées.

Les poids sont récupérés avant la génération : le premier appel avec un nouveau fichier est plus lent de dizaines de secondes, davantage pour les gros fichiers (environ 25 secondes de plus pour un fichier de 1.2 GB). Prévoyez 90 à 120 secondes pour l'appel à froid.

Trois emplacements

Trois entrées couvrent la pile habituelle : un poids de personnage qui tient la personne, un poids de style maison plus faible et un poids de détail pour la peau ou le tissu.

• Déplacez une échelle par exécution. Si vous en changez deux, vous ne pouvez pas attribuer le résultat.
• Laissez de la place aux poids d'appui. Un poids de style à la même force que le poids de personnage tend à lui livrer bataille ; mettez l'entrée d'appui nettement en dessous de 1.
• Ne répétez pas dans le prompt ce qu'un poids apporte déjà.
• Cette famille n'a pas de prompt négatif. Mettez les exclusions dans le prompt.

Ce que cela coûte

Les prix sont par image :

• Le nombre de LoRAs ne change pas le prix. Une entrée et trois sont chiffrées pareil.
• Le chargement de poids coûte une prime par rapport au modèle de base. Qwen Image 2.1 sans le tableau coûte $0.024 en 1k et $0.048 en 2k : une tâche qui n'a pas besoin de poids devrait donc appeler la famille de base.
• En édition, chaque image de référence supplémentaire ajoute un montant fixe : $0.012 en 1k et $0.024 en 2k.

En résumé : la requête la plus coûteuse est celle avec beaucoup d'images de référence en 2k, pas celle avec trois LoRAs.

Cent images texte vers image coûtent $3.00 en 1k et $10.20 en 2k ; cent éditions avec dix références en 2k coûtent $36.60. Itérez en 1k et passez en 2k les images retenues.

Éditer avec des poids

Appliquez un poids de personnage à une image que vous avez déjà approuvée, avec un poids de style maison en dessous, à plus faible force :

{
  "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"
  }
}

Envoyez-la avec le même code, en utilisant alibaba/qwen-image-2.1-lora/edit comme modèle. Copiez les valeurs de champs depuis le schéma en direct de la page du modèle ; le guide de génération d'images explique en quoi diffèrent les endpoints d'image.

Poids sans censure et de catégories restreintes

Cette famille est sans censure : pas de drapeau de maturité, pas d'examen des poids que vous visez, pas d'analyse de contenu ajoutée par SpicyAPI. Vos obligations sont inchangées : uniquement des adultes, des poids et des données d'entraînement que vous êtes en droit d'utiliser, aucun mineur en entrée ou en sortie, aucune image intime non consentie et aucune usurpation trompeuse d'une personne réelle identifiable.

Prochaines étapes

Pour le modèle de base, voyez notre test Qwen Image 2.1 ; pour l'édition sans champ de masque, notre test Qwen Image Edit. Le catalogue plus large des modèles d'image liste le schéma en direct et l'estimation de chaque modèle.

Questions fréquentes

Puis-je exécuter ma propre LoRA sur une API sans l'envoyer ?

Oui. loras accepte jusqu'à trois entrées {path, scale}, où path est un lien direct vers un fichier .safetensors. Il n'y a ni endpoint d'envoi, ni file d'attente d'approbation, ni liste d'autorisation.

Accepte-t-il les liens Hugging Face ?

Oui, sous la forme https://huggingface.co/<user>/<repo>/resolve/<commit-sha>/<file>.safetensors. Les pages de dépôt, les pages blob/ et les chemins privés ou manquants sont rejetés.

Pourquoi ma requête LoRA a-t-elle échoué sans erreur utile ?

Le plus souvent, le path ne fonctionnait plus après l'acceptation de la tâche. Un hébergeur mort, un lien signé expiré ou un dépôt devenu privé échoue avec invalid_request, ce que renvoie aussi une entrée incorrecte : le code seul ne nomme donc pas le lien. La retenue est remboursée. Réduisez le problème avec loras vide, ou vérifiez d'abord les URL des poids.

Ma LoRA change à peine l'image. Quel est le problème ?

Vérifiez sa compatibilité annoncée, sa phrase déclencheuse et son échelle, puis comparez-la seule, sans les autres entrées. Les anciens fichiers Qwen ne sont pas tous incompatibles : plusieurs sont utilisés dans les exemples publiés de cet endpoint. Suivez les paliers d'échelle ci-dessus avant d'écarter le fichier.

Combien de LoRAs puis-je empiler, et l'empilement coûte-t-il plus cher ?

Trois par requête, chacune avec sa propre force. Une quatrième est rejetée aussitôt. Une entrée et trois sont chiffrées au même prix : choisissez donc les poids dont vous avez besoin, pas moins. En édition, c'est le nombre d'images de référence qui fait bouger le prix.

Puis-je utiliser une LoRA en éditant une image existante ?

Oui. L'endpoint d'édition accepte le même tableau loras avec une à dix images de référence. Envoyez l'image approuvée comme référence, dites dans le prompt ce qui doit changer et laissez les poids porter l'identité.

Que fait scale et que dois-je mettre ?

Il pondère la LoRA par rapport au modèle de base, de 0 à 4, avec 1 comme force de départ habituelle. En dessous de 1, un rendu n'est que nuancé, au-dessus de 1 un poids domine.

Comment reproduire une image faite avec une pile donnée ?

Conservez la pile. Il n'y a pas de registre et la seed ne reproduit pas une image : gardez donc la liste {path, scale}, le prompt et les réglages à côté de la sortie, chaque chemin figé sur une adresse qui ne peut pas bouger.