Ассеты и файлы 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, которая его создала, и закрытая previewUrl, действующая около 20 минут. Храните 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` (00:00 UTC)
`asset_storage_full`	503	Наше хранилище временно заполнено; попробуйте позже

Незнакомую причину обрабатывайте так, будто причины нет. Чтение библиотеки ограничено 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 ГиБ; тикет действует два часа). При подтверждении проверяется, что это полный файл 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 принимает ID репозитория Hugging Face (owner/repo, если в нём ровно один файл .safetensors), страницу репозитория или файла на Hugging Face или любую прямую HTTPS-ссылку. token необязателен — это токен доступа Hugging Face или API-ключ Civitai; он используется только для этого скачивания и не сохраняется. Ответ такой же, как при подтверждении: подставьте его uri в loras[].path.

LoRA должна соответствовать базовой модели, для которой её обучали; веса для другой базы обычно не работают или ни на что не влияют. Право на использование подключаемых весов — ваша ответственность.