호스팅 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개 받습니다. 업로드도, 스캔도, 승인도 없습니다.
• 두 엔드포인트 모두 받습니다. 텍스트에서 이미지와 참조 편집 모두 받으므로 이미 가지고 있는 프레임에 가중치를 적용할 수도 있습니다.
• 깨진 링크 중 일부는 즉시, 일부는 작업이 승인된 뒤에 실패합니다. 파일 대신 웹 페이지를 주면 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입니다. 여기서 동작한 설정은 그대로 코드로 옮길 수 있습니다. 여기서 실패한다면 코드를 한 줄 쓰기 전에 링크나 가중치를 고치세요.

그다음 코드로 실행하기

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에게 맡겨도 됩니다

생성을 어시스턴트가 실행하게 하려 할 때, 공식 도구 세 가지 모두 가격을 보여 주고 유료 호출 전에 확인을 받습니다.

• 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" 목록도 없습니다. 시드는 시리즈를 안정화하지만 프레임을 재현하지는 않으므로, {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을 반환합니다.

승인된 두 행이 바로 경계해야 할 대상입니다. 나중에 죽는 링크(만료된 서명 링크, 비공개로 바뀐 저장소, 이름이 바뀌거나 삭제된 파일)는 가중치가 모든 작업마다 다시 가져와지기 때문에 그 링크를 참조하는 모든 요청이 실패합니다. 2026년 10월 테스트에 따르면, 가중치 호스트가 해석되지 않는 작업은 승인된 뒤 빠르게(약 3초) invalid_request로 실패했습니다. 보류 금액은 환불되었고(cost는 0, settled는 true), 메시지는 제공된 링크에서 LoRA를 불러올 수 없다고 했습니다. 잘못된 입력도 invalid_request를 반환하므로 코드만으로는 링크를 특정할 수 없고, 가중치가 여러 개면 메시지가 어느 항목인지 이름으로 알려주지 않습니다. 진단 방법을 필요하기 전에 준비해 두세요. 승인된 견적 뒤에 invalid_request로 실패했다면 가중치 URL을 먼저 확인하는 겁니다.

배열을 비워서 좁혀보기

승인된 작업이 실패했다면, loras만 빈 배열로 보내고 나머지는 그대로 둔 채 같은 요청을 한 번 보내세요. 성공하면 어댑터, 로딩, 또는 요청과의 상호작용을 가리키는 겁니다. 링크, 파일 형식, 호환성, 스택을 하나씩 확인하세요. 두 번째로도 실패하면 작업의 오류 코드와 소스 이미지, 서비스 상태를 다음으로 검사할 대상이 됩니다.

카나리 가중치 하나 유지하기

내가 직접 호스팅하는 작은 가중치 파일 하나를 그대로 유지하세요. 절대 교체하지 말고, 효과가 확실히 눈에 띄는 것을 고르세요. 예를 들어 강한 스타일 가중치 같은 것입니다. 어떤 배치가 실패하기 시작하면 카나리로 한 번 생성해 보세요. 통과하면 내 가중치 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 스타일 예시입니다. 스타일 가중치가 한 프레임에 무엇을 할 수 있는지 보여 줍니다.

응답에는 가중치가 적용됐는지 알려 주는 필드가 없으므로, 그림으로 판단해야 합니다. 파일이 정상적으로 가져와져도 호환되지 않는 가중치, 빠진 트리거 구절, 약한 scale, 겹치는 어댑터 때문에 거의 아무것도 바뀌지 않을 수 있습니다.

1. 실패가 분명한 프롬프트를 고르세요: 베이스 모델이 사진처럼 그릴 피사체에, 가중치가 씌우려는 스타일을 붙이는 것입니다.
2. 스타일이 아니라 장면을 기술하세요. "loose impressionist brushwork"을 요청하면 프롬프트만으로도 그것이 나오므로, 가중치가 작동한다고 잘못 판단하게 됩니다. 외형은 파일이 맡게 하세요.
3. 가중치 없이 같은 프롬프트와 시드로 실행해서 비교하세요. 결과가 구분되지 않는다면 그 비교는 눈에 보이는 어댑터 효과를 보여 주지 못한 겁니다.
4. 한 번에 값 하나만 바꾸세요: scale 1, 그다음 2, 그다음 3. 눈에 띄게 강해지는 가중치는 그저 약했던 겁니다. 어느 단계에서든 무반응인 가중치는 아마 다른 베이스용입니다. 작성자가 권장한 베이스 모델과 트리거 단어도 확인하세요.
5. URL 옆에 판정을 적어 두세요. 조건을 만족한 가중치와 그렇지 않은 가중치를 서로 다른 목록으로 관리하세요.

가중치는 생성 전에 가져와지므로, 새 파일의 첫 호출은 몇십 초 더 느립니다. 큰 파일일수록 더 그렇습니다(1.2 GB 파일이면 약 25초 추가). 콜드 호출에는 90~120초를 잡으세요.

세 개의 슬롯

세 항목이면 보통의 스택을 덮습니다: 사람을 붙잡아 주는 캐릭터 가중치, 더 낮은 강도의 하우스 스타일 가중치, 피부나 천을 위한 디테일 가중치입니다.

• 실행마다 scale 하나만 바꾸세요. 둘을 바꾸면 어느 쪽 때문인지 가릴 수 없습니다.
• 보조 가중치에는 여유를 주세요. 캐릭터 가중치와 같은 강도의 스타일 가중치는 서로 부딪히기 쉽습니다. 보조 항목은 1보다 훨씬 낮게 두세요.
• 가중치가 이미 담고 있는 것을 프롬프트에서 다시 말하지 마세요.
• 이 계열에는 네거티브 프롬프트가 없습니다. 제외할 내용은 프롬프트에 넣으세요.

비용

가격은 이미지 단위입니다.

• LoRA 개수는 가격을 바꾸지 않습니다. 항목 1개와 3개의 견적은 같습니다.
• 가중치 로딩에는 기본 모델 대비 할증이 붙습니다. 배열 없는 Qwen Image 2.1은 1k에서 $0.024, 2k에서 $0.048이므로, 가중치가 필요 없는 작업은 베이스 계열을 호출하세요.
• 편집에서는 참조 이미지가 하나 늘 때마다 고정 금액이 더 붙습니다: 1k에서 $0.012, 2k에서 $0.024.

요약하면: 가장 비싼 요청은 LoRA 세 개가 아니라 2k에서 참조 이미지가 많은 요청입니다.

텍스트에서 이미지로 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 테스트를 보세요. 더 넓은 이미지 모델 카탈로그에는 각 모델의 실제 스키마와 예상 비용이 정리돼 있습니다.

자주 묻는 질문

업로드 없이 API에서 제 LoRA를 실행할 수 있나요?

네. 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가 이미지를 거의 바꾸지 않습니다. 무엇이 문제인가요?

명시된 호환성, 트리거 구절, scale을 확인하고, 다른 항목을 빼고 이 가중치만 단독으로 비교하세요. 오래된 Qwen 파일이 모두 호환되지 않는 것은 아닙니다. 이 엔드포인트의 공개 예시에서도 몇 개가 쓰입니다. 파일을 버리기 전에 위의 scale 단계를 따라가 보세요.

LoRA를 몇 개까지 쌓을 수 있고, 쌓으면 더 비쌉니까?

요청당 3개이며, 각각 자신의 강도를 가집니다. 넷째는 즉시 거부됩니다. 항목 1개와 3개의 견적은 같은 가격이라, 적게 쌓는 대신 필요한 가중치를 고르세요. 편집에서는 참조 이미지 개수가 가격을 움직입니다.

기존 이미지를 편집할 때 LoRA를 쓸 수 있나요?

네. 편집 엔드포인트도 같은 loras 배열을 받으며 참조 이미지는 1~10장입니다. 승인한 프레임을 참조로 보내고, 프롬프트에서 무엇이 바뀌어야 하는지 말한 뒤, 정체성은 가중치에 맡기세요.

scale은 무엇을 하고, 무엇으로 설정해야 하나요?

LoRA를 베이스 모델에 대해 0부터 4까지 가중시킵니다. 1이 보통의 시작 강도입니다. 1보다 낮으면 외형에 살짝 가미하는 정도이고, 1보다 높으면 가중치가 주도하게 됩니다.

특정 스택으로 만든 이미지를 어떻게 재현하나요?

스택을 저장하세요. 레지스트리는 없고 시드도 프레임을 재현하지 않으므로, {path, scale} 목록과 프롬프트, 설정을 결과물 옆에 보관하고, 모든 path는 움직일 수 없는 주소에 고정하세요.