素材库与 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 key——只用于这一次下载，不会保存。响应和提交的格式一样：把它的 uri 填进 loras[].path。

LoRA 必须和它训练时对应的底模匹配；给别的底模训练的权重通常会失败或没有效果。你需要确保自己有权使用所带的权重。

素材库与 LoRA 文件

素材库

保存文件

列出、重命名与删除

存储档位

错误

使用你自己的 LoRA

本页内容