Eigene LoRA auf einer gehosteten API ausführen: eine URL statt einer Upload-Warteschlange

Ein veröffentlichtes Qwen Image 2.1 LoRA-Beispiel: ein Stilgewicht, geladen über das Feld loras.

Sie haben eine trainierte .safetensors-LoRA in einem Bucket oder in einem Hugging-Face-Repo und möchten sie verwenden, ohne sie zu registrieren, hochzuladen oder auf eine Freigabe zu warten. Bei Qwen Image 2.1 LoRA ist das ein Anfragefeld: eine URL und eine Stärke-Zahl, abgerufen, wenn der Task läuft. Das Modell läuft unzensiert, und die Gewichte, auf die Sie zeigen, werden nicht geprüft.

Das entfernt die Upload-Warteschlange und verschiebt eine Abhängigkeit in Ihren Anfragepfad: den Host, der Ihre Gewichte ausliefert. Unten: wie Sie Ihre Datei im Playground testen, der Code, um sie auszuführen, welche schlechten Links sofort scheitern und welche später, und was es kostet.

Die wichtigsten Punkte

• Eine LoRA ist ein Anfragefeld, kein Eintrag, den Sie registrieren. loras nimmt bis zu drei {path, scale}-Einträge auf; es wird nichts hochgeladen, gescannt oder freigegeben.
• Beide Endpunkte nehmen es, Text-zu-Bild und Referenzbearbeitung, sodass Gewichte auch auf vorhandene Einzelbilder angewendet werden können.
• Manche schlechten Links scheitern sofort, andere erst, wenn der Task angenommen wurde. Eine Webseite statt einer Datei ist ein 400; ein toter Host oder ein später ablaufender Link wird angenommen und scheitert danach, wobei die Reservierung zurückerstattet wird.
• Geladen zu sein heißt nicht zu funktionieren. Vergleichen Sie mit einem Lauf ohne Gewichte, demselben Prompt und demselben Seed.
• Die Anzahl der LoRAs ändert den Preis nicht; bei der Bearbeitung ist es die Anzahl der Referenzbilder.

Probieren Sie es zuerst im Playground

1. Öffnen Sie die Text-zu-Bild-Seite und bleiben Sie im Tab Playground in der Ansicht Form. Melden Sie sich mit einem Konto mit Guthaben an, um zu starten.
2. Schreiben Sie einen Prompt, der die Szene beschreibt, nicht den Stil; die Gewichte sollen das Aussehen übernehmen.
3. Unter Style LoRAs fügen Sie den direkten Dateilink in LoRA file ein und setzen Strength (1 ist ein normaler Startwert). Add item erlaubt bis zu drei Gewichte.
4. Wählen Sie 1k für einen günstigen ersten Blick und starten Sie dann das Modell.
5. Um zu sehen, ob die Gewichte etwas bewirkt haben, setzen Sie einen Seed, führen einmal aus, drücken Remove item und führen erneut mit demselben Prompt und Seed aus.

Der Anfrage-Body im Playground ist dasselbe JSON, das die API annimmt, eine hier funktionierende Einrichtung lässt sich also direkt in Code übernehmen. Wenn es hier fehlschlägt, reparieren Sie Link oder Gewichte, bevor Sie eine Zeile Code schreiben.

Dann aus Code ausführen

Installieren Sie das Python-SDK (pip install spicyapi), setzen Sie SPICY_API_KEY in Ihrer Serverumgebung und führen Sie aus:

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

Erstellen, Warten, Herunterladen, Retries und Fehlercodes behandelt der Tasks-Leitfaden und die Python-SDK-Referenz. Ergebnisse laufen ab, lesen Sie also Retention und Auslieferung, bevor Sie auf dem zurückgegebenen Link aufbauen.

Oder lassen Sie einen Agenten laufen

Wenn ein Assistent die Generierungen übernehmen soll, zeigen alle drei offiziellen Tools den Preis und fragen vor einem kostenpflichtigen Aufruf nach.

• CLI. Legen Sie dasselbe input-Objekt in input.json, dann:

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

Siehe die CLI-Doku; npx @spicyapi/cli funktioniert ohne Installation.

• MCP-Server. Fügen Sie Ihrem Assistenten den MCP-Server hinzu und fragen Sie dann: „Führen Sie Qwen Image 2.1 LoRA mit diesem Prompt und diesem Gewichts-Link mit Stärke 1 aus.“ Er ruft spicyapi_task_create auf, das für Ihre Preisbestätigung stoppt, und danach spicyapi_task_wait.
• Skill. npx skills add spicyapi-ai/spicy-skill installiert den Agent Skill, der einen Coding-Assistenten das live Modellschema lesen lässt, statt Felder zu raten.

Das loras-Array

loras nimmt bis zu drei { "path", "scale" }-Einträge auf beiden Endpunkten auf, Text-zu-Bild und Referenzbearbeitung (1 bis 10 Bilder).

• Verwenden Sie einen Dateilink, keine Repository-Seite. Eine Hugging-Face-Repo-URL oder eine blob/main/...-Seite wird abgelehnt. Verwenden Sie den resolve/...-Link auf die Datei selbst.
• Es gibt keine Registry. Sie bekommen nie eine Kennung für ein Gewicht und es gibt keine Liste „meine LoRAs“. Der Seed stabilisiert eine Serie, reproduziert aber kein Einzelbild; speichern Sie daher die Liste {path, scale}, Prompt, Einstellungen und Task-ID neben jeder Ausgabe.

Wählen Sie Gewichte, die als mit der genauen Aufgabe kompatibel dokumentiert sind. Die veröffentlichten Qwen Image 2.1-Beispiele enthalten 2512-Generierungsadapter und Edit-2511/2509-Bearbeitungsadapter, eine ältere Version im Dateinamen macht eine Datei also nicht allein unkompatibel. Jene älteren Aufgaben sind auch über Qwen Image 2512 LoRA verfügbar, und unser Qwen Image 2.1 LoRA-Leitfaden behandelt, welche älteren Dateien übernommen werden.

Welche schlechten Links bei der Einreichung scheitern

Wenn Sie Gewichte einreichen, versucht die API den Link. Antwortet der Host und kommt etwas zurück, das keine Datei ist, erhalten Sie ein 400, bevor ein Task existiert und bevor Gelder reserviert werden:

Referenzbilder am Bearbeitungs-Endpunkt werden genauso behandelt: eine fehlende image_urls-Datei ist ein 400 mit Angabe des Hosts.

Die beiden angenommenen Zeilen sind die, vor denen Sie sich schützen müssen. Ein Link, der später stirbt (ein abgelaufener signierter Link, ein privat gewordenes Repo, eine umbenannte oder gelöschte Datei), lässt jeden Request scheitern, der ihn referenziert, weil die Gewichte bei jedem Task geholt werden. Auf Basis unseres Tests vom Oktober 2026 wurde ein Task, dessen Gewichts-Host nicht auflöst, angenommen und scheiterte dann schnell (etwa 3 Sekunden) mit invalid_request; die Reservierung wurde zurückerstattet (cost war 0, settled war true) und die Meldung sagte, dass eine LoRA vom angegebenen Link nicht geladen werden konnte. invalid_request liefert auch eine fehlerhafte Eingabe, der Code allein zeigt also nicht auf den Link, und bei mehreren Gewichten nennt die Meldung den Eintrag nicht. Richten Sie die Diagnose ein, bevor Sie sie brauchen: Nach einem angenommenen Angebot bedeutet ein invalid_request-Fehler, zuerst die Gewichts-URLs zu prüfen.

Mit geleertem Array eingrenzen

Wenn ein angenommener Task scheitert, senden Sie dieselbe Anfrage einmal mit leerem loras und sonst nichts geändert. Erfolg deutet auf den Adapter, sein Laden oder seine Wechselwirkung mit der Anfrage; prüfen Sie Link, Dateiformat, Kompatibilität und Stack einzeln. Ein zweiter Fehlschlag macht den Fehlercode des Tasks, die Quellbilder und den Dienststatus zu den nächsten Prüfungen.

Behalten Sie ein Kontrollgewicht

Behalten Sie eine kleine Gewichtsdatei, die Sie selbst hosten, die Sie nie rotieren und deren Wirkung unübersehbar ist, etwa ein starkes Stilgewicht. Wenn ein Stapel zu scheitern beginnt, führen Sie eine Generierung mit dem Kontrollgewicht aus. Funktioniert sie, verdächtigen Sie Ihre Gewichts-URL. Scheitert sie ebenfalls, prüfen Sie errorCode des Tasks und den Dienststatus, bevor Sie Speichereinstellungen anfassen.

Beim Deployment prüfen, nicht pro Anfrage

Führen Sie ein kostenloses Angebot (spicyapi tasks quote --model alibaba/qwen-image-2.1-lora/text-to-image --input-file input.json) für jede Gewichts-URL aus, auf die Ihre Konfiguration verweist, in Ihrer Deployment-Pipeline und beim Start des Dienstes. Das erkennt eindeutig unbrauchbare Links, nicht die Adapterkompatibilität. Quoten Sie nicht vor jeder Generierung; das erhöht die Latenz und der Link kann trotzdem eine Minute später sterben.

Adresse festnageln, damit sie sich nicht bewegen kann

• Hugging Face: resolve/main/... folgt einem Branch. Nageln Sie den Commit fest: resolve/<commit-sha>/<file>.safetensors.
• Ihr eigener Speicher: legen Sie einen Content-Hash in den Key, etwa character-v7-4f9c81.safetensors, und überschreiben Sie nie einen Key.
• Ablaufende signierte URLs: vermeiden Sie sie in langlebigen Konfigurationen. Für wiederkehrende Jobs nutzen Sie eine stabile Adresse oder erzeugen Sie direkt vor jeder Einreichung einen neuen Link, der den Job und alle Retries überdauert.
• Drittanbieter-Repositories: Autoren können ein Repo jederzeit umbenennen, sperren oder löschen. Ist eine Datei tragend, kopieren Sie sie in Speicher, den Sie kontrollieren, vorbehaltlich seiner Lizenz, und nageln Sie Ihre Kopie fest.

Hat die LoRA etwas bewirkt?

Ein veröffentlichtes Qwen Image 2.1 LoRA-Stilbeispiel. Es zeigt, was ein Stilgewicht mit einem Einzelbild machen kann.

Die Antwort enthält kein Feld, das sagt, dass Ihre Gewichte angewendet wurden, beurteilen Sie es also anhand des Bildes. Eine Datei kann korrekt geholt werden und dennoch fast nichts ändern, wegen inkompatibler Gewichte, einer fehlenden Triggerphrase, schwacher Skalierung oder überlappender Adapter.

1. Wählen Sie einen Prompt, dessen Scheitern offensichtlich ist: ein Motiv, das das Basismodell fotografisch rendert, mit einem Stil, den das Gewicht durchsetzen soll.
2. Beschreiben Sie die Szene, nicht den Stil. Bitten Sie um „loose impressionist brushwork“, und der Prompt allein erzeugt es, Sie würden das Gewicht also als funktionierend einstufen. Lassen Sie die Datei das Aussehen übernehmen.
3. Führen Sie denselben Prompt und Seed ohne Gewichte aus und vergleichen Sie. Ist das Ergebnis nicht unterscheidbar, hat der Vergleich keinen sichtbaren Adaptereffekt gezeigt.
4. Ändern Sie jeweils einen Wert: Skalierung 1, dann 2, dann 3. Ein Gewicht, das sichtbar stärker wird, war nur schwach; eines, das in jedem Schritt inert bleibt, ist vermutlich für eine andere Basis gebaut. Prüfen Sie auch das empfohlene Basismodell und die Triggerwörter des Autors.
5. Schreiben Sie das Urteil neben die URL und halten Sie qualifizierte und nicht qualifizierte Gewichte in getrennten Listen.

Die Gewichte werden vor der Generierung geholt, ein erster Aufruf mit einer neuen Datei ist daher um Dutzende Sekunden langsamer, bei größeren Dateien mehr (etwa 25 Sekunden zusätzlich für eine 1.2-GB-Datei). Rechnen Sie für den Kaltstart 90 bis 120 Sekunden ein.

Drei Plätze

Drei Einträge decken den üblichen Stack ab: ein Charaktergewicht, das die Person hält, ein Hausstilgewicht mit geringerer Stärke, ein Detailgewicht für Haut oder Stoff.

• Bewegen Sie pro Lauf eine Skalierung. Ändern Sie zwei, können Sie das Ergebnis nicht zuordnen.
• Geben Sie unterstützenden Gewichten Raum. Ein Stilgewicht mit derselben Stärke wie das Charaktergewicht neigt dazu, mit ihm zu kämpfen; setzen Sie den unterstützenden Eintrag deutlich unter 1.
• Schreiben Sie im Prompt nicht erneut, was ein Gewicht schon mitbringt.
• Diese Familie hat keinen Negativ-Prompt. Setzen Sie Ausschlüsse in den Prompt.

Was es kostet

Die Preise gelten pro Bild:

• Die Anzahl der LoRAs ändert den Preis nicht. Ein Eintrag und drei kosten gleich.
• Das Laden von Gewichten kostet einen Aufschlag gegenüber dem Basismodell. Qwen Image 2.1 ohne das Array kostet $0.024 bei 1k und $0.048 bei 2k, ein Job, der keine Gewichte braucht, sollte daher die Basisfamilie aufrufen.
• Bei der Bearbeitung kostet jedes zusätzliche Referenzbild einen festen Betrag: $0.012 bei 1k und $0.024 bei 2k.

Kurz gesagt: Die Anfrage, die am meisten kostet, ist die mit vielen Referenzbildern bei 2k, nicht die mit drei LoRAs.

Hundert Text-zu-Bild-Einzelbilder kosten $3.00 bei 1k und $10.20 bei 2k; hundert Bearbeitungen mit zehn Referenzen bei 2k kosten $36.60. Iterieren Sie bei 1k und befördern Sie die brauchbaren Ergebnisse auf 2k.

Bearbeiten mit Gewichten

Wenden Sie ein Charaktergewicht auf ein Einzelbild an, das Sie bereits freigegeben haben, mit einem Hausstilgewicht darunter bei geringerer Stärke:

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

Senden Sie es mit demselben Code und verwenden Sie alibaba/qwen-image-2.1-lora/edit als Modell. Kopieren Sie Feldwerte aus dem live Schema auf der Modellseite; der Leitfaden zur Bildgenerierung erklärt, wie sich die Bild-Endpunkte unterscheiden.

Unzensierte Gewichte und Gewichte eingeschränkter Kategorien

Diese Familie ist unzensiert: es gibt kein Reife-Flag, keine Prüfung der Gewichte, auf die Sie zeigen, und keinen von SpicyAPI ergänzten Content-Scan. Ihre Pflichten bleiben unverändert: nur Erwachsene, Gewichte und Trainingsdaten, die Sie verwenden dürfen, keine Minderjährigen in Eingabe oder Ausgabe, keine nicht einvernehmliche intime Bildgebung und keine täuschende Nachahmung einer echten identifizierbaren Person.

Nächste Schritte

Für das Basismodell siehe unseren Qwen Image 2.1-Test; für die Bearbeitung ohne Maskenfeld unseren Qwen Image Edit-Test. Der breitere Bildmodell-Katalog listet das live Schema und die Schätzung jedes Modells.

Häufige Fragen

Kann ich meine eigene LoRA auf einer API ausführen, ohne sie hochzuladen?

Ja. loras nimmt bis zu drei {path, scale}-Einträge auf, wobei path ein direkter Link auf eine .safetensors-Datei ist. Es gibt keinen Upload-Endpunkt, keine Freigabewarteschlange und keine Allowlist.

Akzeptiert sie Hugging-Face-Links?

Ja, als https://huggingface.co/<user>/<repo>/resolve/<commit-sha>/<file>.safetensors. Repository-Seiten, blob/-Seiten sowie private oder fehlende Pfade werden abgelehnt.

Warum ist meine LoRA-Anfrage ohne nützlichen Fehler fehlgeschlagen?

Meistens funktionierte der path nach der Annahme des Tasks nicht mehr. Ein toter Host, ein abgelaufener signierter Link oder ein privat gewordenes Repository scheitert mit invalid_request, was auch eine fehlerhafte Eingabe liefert, der Code allein nennt also nicht den Link. Die Reservierung wird zurückerstattet. Grenzen Sie mit geleertem loras ein oder prüfen Sie zuerst die Gewichts-URLs.

Meine LoRA verändert das Bild kaum. Was stimmt nicht?

Prüfen Sie die angegebene Kompatibilität, Triggerphrase und Skalierung und vergleichen Sie sie dann allein, ohne die anderen Einträge. Ältere Qwen-Dateien sind nicht alle inkompatibel: mehrere werden in den veröffentlichten Beispielen dieses Endpunkts verwendet. Folgen Sie den Skalierungsschritten oben, bevor Sie die Datei verwerfen.

Wie viele LoRAs kann ich stapeln, und kostet Stapeln mehr?

Drei pro Anfrage, jede mit eigener Stärke. Ein vierter wird sofort abgelehnt. Ein Eintrag und drei kosten denselben Preis, wählen Sie also die Gewichte, die Sie brauchen, nicht weniger. Bei der Bearbeitung ist es die Anzahl der Referenzbilder, die den Preis bewegt.

Kann ich eine LoRA beim Bearbeiten eines vorhandenen Bildes verwenden?

Ja. Der Bearbeitungs-Endpunkt nimmt dasselbe loras-Array mit einem bis zehn Referenzbildern. Senden Sie das freigegebene Einzelbild als Referenz, sagen Sie im Prompt, was sich ändern soll, und lassen Sie die Gewichte die Identität tragen.

Was macht scale und was sollte ich setzen?

Es gewichtet die LoRA gegenüber dem Basismodell, von 0 bis 4, wobei 1 die übliche Startstärke ist. Unter 1 würzt das Gewicht den Look nur, über 1 dominiert es.

Wie reproduziere ich ein Bild, das mit einem bestimmten Stack entstanden ist?

Speichern Sie den Stack. Es gibt keine Registry und der Seed reproduziert kein Einzelbild, halten Sie daher die Liste {path, scale}, den Prompt und die Einstellungen neben der Ausgabe, mit jedem Pfad auf einer Adresse festgenagelt, die sich nicht bewegen kann.