ホスト型APIで自分のLoRAを動かす：アップロード待ち列の代わりにURLを

公開されたQwen Image 2.1 LoRAの例。lorasフィールドで読み込んだスタイルの重みです。

バケットやHugging Faceのリポジトリに学習済みの.safetensors形式のLoRAがあり、登録もアップロードも承認待ちもせずに使いたいとします。Qwen Image 2.1 LoRAでは、これはリクエストフィールドです。URLと強度の数値ひとつで、ジョブが動くときに取得されます。モデルは規制なしで動き、指し示した重みが検査されることもありません。

これでアップロードの待ち列が不要になり、依存がひとつリクエスト経路に移ります。あなたが重みを置いているホストです。以下では、Playgroundで自分のファイルを試す方法、実行用のコード、壊れたリンクのうちどれが即座に失敗してどれが後で失敗するか、そして費用がどれくらいかかるかを説明します。

押さえたい点

• LoRAは登録する対象ではなくリクエストフィールドです。 lorasは{path, scale}のエントリを最大3つ受け取ります。何もアップロードもスキャンも承認もされません。
• 両方のエンドポイントが使えます。 テキストから画像でも参照編集でも、だからすでにお手元のフレームに重みを適用することもできます。
• 壊れたリンクには、即座に落ちるものと、タスクが受理されたあとに落ちるものがあります。 ファイルではなくWebページを渡すと400になります。ホストが死んでいる場合や、あとで期限切れになるリンクは受理され、そのあとに失敗します。保留分は返金されます。
• 読み込まれたことは、効果が出ることを意味しません。 重みなしで実行したものと、同じプロンプトとシードで比べてください。
• LoRAの個数は価格を変えません。 編集で価格を動かすのは参照画像の数です。

まずPlaygroundで試す

1. テキストから画像のページを開き、PlaygroundタブのForm表示のままにしてください。実行するには入金済みのアカウントでログインします。
2. スタイルではなく場面を描くプロンプトを書いてください。見た目は重みに任せます。
3. Style LoRAsの下で、ファイルの直接リンクをLoRA fileに貼り付け、Strengthを設定します（1が通常の開始値です）。Add itemで重みを最大3つまで足せます。
4. 最初は1kの低解像度で動きを確認してから、モデルを動かします。
5. 重みが何を変えたかを見るには、Seedを決めて一度実行し、Remove itemを押してから、同じプロンプトとシードでもう一度実行します。

PlaygroundのリクエストボディはAPIが受け取るJSONと同じです。ここで動いた設定はそのままコードにコピーできます。ここで失敗するなら、コードを1行書く前にリンクか重みを直してください。

続いてコードから実行する

Python SDK（pip install spicyapi）を入れ、サーバー環境のSPICY_API_KEYを設定して、次を実行します。

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

タスクの作成、待機、ダウンロード、再試行、エラーコードはtasksガイドとPython SDKリファレンスで説明しています。結果は期限が切れるので、返されたリンクの上に構築する前に保持と配信を確認してください。

Agentに実行させる

生成をアシスタントに任せたい場合、3つの公式ツールはいずれも価格を表示し、有料の呼び出しの前に確認を求めます。

• CLI. 同じinputオブジェクトをinput.jsonに入れておき、次を実行します。

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

CLIドキュメントも参照してください。npx @spicyapi/cliはインストールなしでも動きます。

• MCPサーバー。 アシスタントにMCPサーバーを追加して、こう依頼します。「このプロンプトとこの重みリンクで、強度1のQwen Image 2.1 LoRAを実行して」。spicyapi_task_createが価格確認で止まり、その後spicyapi_task_waitが呼ばれます。
• Skill. npx skills add spicyapi-ai/spicy-skillはAgent Skillを入れます。フィールドを推測せず、コーディングアシスタントが実際のモデルスキーマを読むようになります。

loras配列

lorasは両方のエンドポイントで{ "path", "scale" }のエントリを最大3つ受け取ります。テキストから画像でも参照編集でも、（1から10枚の画像で）同じです。

• リポジトリのページではなく、ファイルのリンクを使ってください。 Hugging FaceのリポジトリURLやblob/main/...のページは拒否されます。ファイル自体のresolve/...リンクを使ってください。
• レジストリはありません。 重みの識別子は発行されず、「自分のLoRA」の一覧も存在しません。シードは系列を安定させますが、1フレームの再現はしません。{path, scale}の一覧、プロンプト、設定、タスクIDを各出力の隣に保存してください。

対象のタスクと互換性があると記載された重みを選んでください。公開されたQwen Image 2.1の例には2512の生成アダプターとEdit 2511/2509の編集アダプターが含まれるため、ファイル名に古い番号が書いてあるだけでは非互換になるわけではありません。これらの古いタスクはQwen Image 2512 LoRAでも利用でき、Qwen Image 2.1 LoRAガイドが古いファイルの引き継ぎを扱っています。

送信時に失敗する壊れたリンク

重みを送信すると、APIはそのリンクを試します。ホストが応答しても、返ってきたものがファイルでなければ、資金が保留される前に400が返ります。

編集用エンドポイントの参照画像にも同じ扱いがあります。image_urlsのファイルが欠けていると、ホスト名を挙げる400になります。

受理される2行が、防御すべきポイントです。あとで死ぬリンク（期限切れの署名付きリンク、非公開になったリポジトリ、名前が変わったか削除されたファイル）は、重みがジョブごとに取得されるため、それを参照するすべてのリクエストが失敗します。2026年10月のテストでは、重みのホストが解決しないタスクは受理されたあと、3秒ほどでinvalid_requestで失敗しました。保留分は返金され（costは0、settledはtrue）、メッセージは指定されたリンクからLoRAを読み込めなかったと述べていました。invalid_requestは入力の誤りでも返るため、コードだけではリンクの特定はできません。重みが複数あると、メッセージはどのエントリかも示しません。必要になる前に診断の準備を済ませておいてください。受理された見積りのあとinvalid_requestで失敗したら、まず重みのURLを確認します。

配列を空にして切り分ける

受理されたタスクが失敗したら、同じリクエストをそのままloras空の状態で一度だけ送ってください。それ以外は何も変えません。成功すれば原因はアダプター、その読み込み、またはリクエストとの相互作用にあります。リンク、ファイル形式、互換性、スタックを1つずつ確認してください。2度続けて失敗した場合は、タスクのエラーコード、元の画像、サービスの状態が次の確認対象になります。

カナリア重みを1つ持っておく

自分でホストしている小さな重みファイルを1つ持ち、入れ替えず、効果がはっきり分かるものを用意してください。強いスタイルの重みなどが適しています。まとめて失敗し始めたら、カナリアで1回生成してみてください。成功するなら、自分の重みURLを疑ってください。それも失敗するなら、ストレージ設定に触れる前にタスクのerrorCodeとサービスの状態を確認します。

リクエストごとではなくデプロイ時に確認する

設定が参照するすべての重みURLについて無料見積り（spicyapi tasks quote --model alibaba/qwen-image-2.1-lora/text-to-image --input-file input.json）を、デプロイのパイプラインとサービス起動時に実行してください。明らかに使えないリンクは検出できますが、アダプターの互換性は検出できません。生成ごとの見積りは遅延が増え、リンクは1分後に死にうるのでしないでください。

アドレスを固定して動かせないようにする

• Hugging Face：resolve/main/...はブランチを追うため、コミットを固定します。resolve/<commit-sha>/<file>.safetensors。
• 自分のストレージ：キーに内容のハッシュを埋め込んでください。character-v7-4f9c81.safetensorsのようにし、キーを上書きしないでください。
• 期限切れの署名付きURL：長期的な設定では使わないでください。繰り返しのジョブには安定したアドレスを使うか、送信の直前に新しくリンクを発行して、ジョブと再試行を確実に超える寿命にしてください。
• 第三者のリポジトリ：作者はいつでもリポジトリの名前を変える、制限する、削除できます。重要なファイルは、ライセンスに従ったうえで自分が管理するストレージにコピーし、そのコピーを固定してください。

LoRAは何かを変えましたか

公開されたQwen Image 2.1 LoRAのスタイル例。スタイルの重みが1フレームに何をもたらすかを示しています。

レスポンスに重みが適用されたことを示すフィールドはないので、画像で判断します。ファイルが正しく取得されても、非互換な重み、トリガー語の欠落、弱い強度、互いを打ち消すアダプターのために、ほとんど何も変えないことがあります。

1. 失敗が明らかなプロンプトを選ぶ：ベースモデルが写真的に描く被写体に、重みが課すべきスタイルを組み合わせます。
2. スタイルではなく場面を描く。 「loose impressionist brushwork」と頼むと、プロンプトだけでそれができるので、重みが機能していると記録してしまいます。見た目はファイルに任せてください。
3. 重みなしで同じプロンプトと同じシードを実行して比べます。結果が区別できないなら、比較ではアダプターの視覚的な効果が見えていませんでした。
4. 値は1つずつ変える：強度を1、次に2、次に3。段階を踏んで明らかに強くなる重みは、もともと弱かっただけです。どの段階でも変化しない重みは、別のベース用に作られた可能性が高いです。作者が推奨するベースモデルとトリガー語も確認してください。
5. 判定はURLの隣に書いて、適合する重みとそうでない重みは別々のリストに分けてください。

重みは生成の前に取得されるため、新しいファイルでの最初の呼び出しは数十秒遅くなり、大きいファイルではさらに遅くなります（1.2 GBのファイルで約25秒の追加）。コールドコールには90〜120秒を見込んでください。

3つの枠

3つのエントリで一般的な構成をまかなえます。人物を支えるキャラクターの重み、低い強度のハウススタイルの重み、そして肌や布のためのディテールの重みです。

• 実行ごとに動かす強度は1つだけ。 2つ変えると、どちらが効いたのか特定できません。
• 補助的な重みには余裕を与える。 キャラクターの重みと同じ強度のスタイル重みは、互いに張り合いがちです。補助のエントリは1を下回る位置に置いてください。
• 重みが既に伝えている内容をプロンプトで繰り返さない。
• このファミリーにネガティブプロンプトはありません。 除外条件はプロンプトに書いてください。

費用

価格は画像単位です。

• LoRAの個数は価格を変えません。 1エントリと3エントリは同額です。
• 重みの読み込みにはプレミアムが乗ります。 Qwen Image 2.1 を配列なしで使うと1kで$0.024、2kで$0.048です。重みが不要なジョブはベースファミリーを呼ぶべきです。
• 編集では、参照画像が1枚増えるごとに固定額が加算されます。 1kで$0.012、2kで$0.024です。

要するにもっとも高くつくのは、参照画像が多くて2kでのリクエストであり、LoRAを3つ並べたものではありません。

テキストから画像の100コマは1kで$3.00、2kで$10.20です。2kで参照10枚の編集100回は$36.60です。1kで回してから、気に入ったものを2kへ進めましょう。

重みを使った編集

既に承認したフレームにキャラクターの重みを適用し、その下に低めの強度でハウススタイルの重みを置きます。

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

同じコードで、モデルにalibaba/qwen-image-2.1-lora/editを指定して送ってください。フィールド値はモデルページの最新スキーマから取得します。画像生成ガイドが画像系エンドポイントの違いを説明します。

規制なしと制限カテゴリーの重み

このファミリーは規制なしです。年齢区分フラグはなく、指し示した重みのレビューもなく、SpicyAPIが追加したコンテンツスキャンもありません。使う側の義務は変わりません。成人のみ、使う権利のある重みと学習データ、入力にも出力にも未成年を含めないこと、同意のない親密な画像を作らないこと、特定できる実在人物への欺瞞的ななりすましをしないことです。

次のステップ

ベースモデルについてはQwen Image 2.1のテストを、マスクなしで編集する点についてはQwen Image Editのテストを見てください。より広い画像モデルのカタログには、各モデルの最新スキーマと概算が並びます。

よくある質問

LoRAをアップロードせずにAPIで実行できますか

はい。lorasは{path, scale}のエントリを最大3つ受け取り、pathは.safetensorsファイルへの直接リンクです。アップロード用エンドポイントも承認待ち列も許可リストもありません。

Hugging Faceのリンクは受け付けますか

はい。https://huggingface.co/<user>/<repo>/resolve/<commit-sha>/<file>.safetensorsの形なら受け付けます。リポジトリページ、blob/ページ、非公開または存在しないパスは拒否されます。

LoRAのリクエストが有益なエラーなしで失敗したのはなぜですか

多くの場合、タスクが受理されたあとにpathが動かなくなっています。ホストが死んでいる、署名付きリンクが期限切れになった、リポジトリが非公開になった場合、invalid_requestで失敗します。これは入力の誤りでも返るため、コードだけではリンクを特定できません。保留分は返金されます。lorasを空にして切り分けるか、まず重みのURLを確認してください。

LoRAが画像をほとんど変えません。何が問題ですか

記載されている互換性、トリガー語、強度を確かめてから、他のエントリを外して単独で比較してください。古いQwenのファイルがすべて非互換というわけではありません。複数のファイルはこのエンドポイントの公開例に使われています。ファイルを捨てる前に、上の強度の段階に従ってください。

LoRAを何個まで重ねられますか。重ねると高くなりますか

リクエストごとに3個までで、それぞれ固有の強度を持ちます。4個目は即座に拒否されます。1個と3個は同額なので、少なくするより必要な重みを選んでください。編集で価格を動かすのは参照画像の数です。

既存の画像を編集するときにLoRAを使えますか

はい。編集用エンドポイントは同じloras配列を1〜10枚の参照画像とともに受け取ります。承認済みのフレームを参照として送り、プロンプトで何を変えるかを書き、重みにアイデンティティを任せてください。

scaleは何をするもので、何に設定すべきですか

LoRAをベースモデルに対して0から4の範囲で重み付けします。1が通常の開始強度です。1より下なら実感が落ち着き、1より上なら重みが支配的になります。

特定の構成で作った画像を再現するには

構成を保存してください。レジストリはなく、シードは1フレームを再現しません。{path, scale}の一覧、プロンプト、設定を出力の隣に保管し、各パスは動き得ないアドレスに固定してください。