素材庫與 LoRA 檔案

把檔案存進素材庫並以 URI 重複使用、讀取你的角色，以及使用你自己的 LoRA 權重。

上傳的檔案與任務結果都是暫時的。想在許多任務裡重複使用同一個檔案——一張產品照、一個角色的臉、一段聲音樣本——就把它存進素材庫。如果模型支援自訂風格權重，也可以帶上你自己的 LoRA 檔案。

素材庫

儲存後的素材會取得一個穩定的 URI：popnow://a/ast_…。只要素材還在，就能填進任何模型對應類型的素材欄位：

{ "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 陣列——最多三個權重檔，每個都有 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；票證兩小時內有效）。提交時會檢查它是否為完整的 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 必須搭配它訓練時對應的基礎模型；為其他基礎模型訓練的權重通常會失敗或沒有效果。你必須確保自己有權使用所帶入的權重。

素材庫與 LoRA 檔案

素材庫

儲存檔案

列出、重新命名與刪除

儲存方案

錯誤

使用你自己的 LoRA

本頁內容