에셋과 LoRA 파일

파일을 에셋 라이브러리에 저장해 URI로 다시 쓰기, 캐릭터 읽기, 내 LoRA 가중치 가져오기.

업로드한 파일과 작업 결과는 임시입니다. 제품 사진, 캐릭터의 얼굴, 목소리 샘플처럼 여러 작업에서 다시 쓰고 싶은 파일은 에셋 라이브러리에 저장하세요. 사용자 지정 스타일 가중치를 받는 모델에는 내 LoRA 파일을 가져올 수 있습니다.

에셋 라이브러리

저장한 에셋에는 popnow://a/ast_…라는 고정 URI가 생깁니다. 에셋을 지우지 않는 한 어느 모델이든 맞는 종류의 미디어 필드에 넣을 수 있습니다.

{ "model": "google/nano-banana-2.1/edit",
  "input": { "prompt": "Put this mug on a wooden café table, morning light",
             "image_urls": ["popnow://a/ast_01k3m8x9q2z4v7n5p6r8s0t1w3"] } }

이 URI는 참조일 뿐 다운로드 링크가 아닙니다. 내 계정의 키로 보내는 생성 요청 안에서만 쓸 수 있습니다. 에셋은 삭제할 때까지 남습니다.

파일 저장

POST /api/v1/assets는 파일을 라이브러리로 복사합니다. 출처를 하나 고르며 Idempotency-Key 헤더는 필수이고, 같은 출처를 다시 저장하면 기존 에셋을 돌려줍니다.

`source`	함께 보낼 것	저장되는 것
`task_output`	`taskId`와 결과물의 `key` 또는 `index`	내 성공한 작업이 만든 파일
`upload`	`fileId`	커밋된 업로드
`url`	`url`	공개된 `http`/`https` 파일(JPEG, PNG, WebP, GIF, MP4, WebM, MP3, WAV, FLAC, Ogg)

curl -X POST "https://api.popnow.ai/api/v1/assets" \
  -H "Authorization: Bearer $POPNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: save-$TASK_ID-0" \
  -d "{\"source\": \"task_output\", \"taskId\": \"$TASK_ID\", \"index\": 0, \"name\": \"Hero shot\"}"

응답은 에셋 자체입니다. id, uri, name, kind(image, video, audio), 크기와 치수, 만든 model, 약 20분 동안 유효한 비공개 previewUrl이 들어 있습니다. 저장할 것은 미리보기 링크가 아니라 uri입니다.

목록, 이름 바꾸기, 삭제

호출	하는 일
`GET /api/v1/assets`	에셋 한 페이지. `kind`, `source`, `favorite`, `q`(이름 검색), `collectionId`, `entityId`로 거르고, `sort=recent\|oldest\|name\|size`로 정렬하고, `cursor`로 이어 받기
`GET /api/v1/assets/{id}`	에셋 하나와 새 미리보기 링크
`PATCH /api/v1/assets/{id}`	`name`과/또는 `favorite` 변경
`DELETE /api/v1/assets/{id}`	삭제. 이후 새 요청에서는 URI가 동작하지 않음
`GET /api/v1/assets/entities`	내 캐릭터. 웹사이트에서 정리한 이름 붙은 이미지 묶음이며, 이미지마다 URI가 있음
`GET /api/v1/assets/usage`	저장 플랜, 사용량, 한도, 다음 플랜에서 늘어나는 것

저장 플랜

저장 공간은 첫 크레딧 구매로 열리고, 지금까지 구매한 양에 따라 늘어납니다. 줄어들지 않으며, 저장한 에셋은 언제나 쓸 수 있습니다. 내 계정의 수치는 GET /api/v1/assets/usage로 확인하세요.

오류

에셋 라이브러리 오류에는 평소 형식에 기계가 읽을 수 있는 data.reason이 더해집니다.

`data.reason`	HTTP	의미
`asset_library_locked`	400	라이브러리는 첫 크레딧 구매 후 열립니다
`asset_library_full`	400	플랜의 용량이나 개수를 다 씀. 에셋을 지우거나 플랜을 올리세요
`asset_file_too_large`	400	파일이 플랜의 파일당 한도를 넘음
`asset_daily_limit`	429	오늘 새로 만들 수 있는 에셋 수에 도달. `Retry-After`(UTC 00:00)까지 기다리기
`asset_storage_full`	503	저희 쪽 저장 공간이 잠시 가득 참. 나중에 다시 시도

모르는 reason은 reason이 없는 것처럼 다루세요. 라이브러리 읽기는 분당 60회, 저장은 분당 30회로 제한됩니다.

내 LoRA 가져오기

ID가 -lora로 끝나는 모델은 loras 배열을 받습니다. 가중치 파일은 최대 3개이고, 각각 path와 scale(0~4)이 있습니다.

{ "model": "alibaba/qwen-image-2.1-lora/text-to-image",
  "input": { "prompt": "A cozy reading nook in watercolor style",
             "loras": [{ "path": "popnow://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3", "scale": 1 }] } }

path에는 .safetensors 파일의 공개 직접 링크나, 업로드·가져오기한 파일을 넣을 수 있습니다.

업로드: 다른 파일처럼 contentType: application/octet-stream으로 올립니다(.safetensors 파일, 최대 2 GiB, 티켓은 2시간 유효). 커밋할 때 완전한 safetensors 파일인지 확인합니다.
링크에서 가져오기: 비공개 Hugging Face 저장소처럼 내려받으려면 로그인이 필요한 파일에 씁니다.

curl -X POST "https://api.popnow.ai/api/v1/files/import" \
  -H "Authorization: Bearer $POPNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "your-name/your-lora-repo", "token": "hf_..."}'

url에는 Hugging Face 저장소 ID(owner/repo, .safetensors 파일이 정확히 하나일 때), Hugging Face 저장소 페이지나 파일 페이지, 또는 아무 HTTPS 직접 링크를 넣을 수 있습니다. token은 선택이며 Hugging Face 액세스 토큰이나 Civitai API 키입니다. 이번 한 번의 다운로드에만 쓰고 저장하지 않습니다. 응답은 커밋과 같은 형식이니 uri를 loras[].path에 넣으세요.

LoRA는 학습할 때 쓴 베이스 모델과 맞아야 합니다. 다른 베이스용 가중치는 대개 실패하거나 효과가 없습니다. 가져오는 가중치를 쓸 권리가 있는지는 직접 책임지고 확인하세요.