Asset e file LoRA

Conserva i file nella tua libreria e riusali tramite URI, leggi i tuoi personaggi e porta i tuoi pesi LoRA.

I caricamenti e i risultati delle attività sono temporanei. Quando vuoi riusare un file in molte attività — una foto prodotto, il volto di un personaggio, un campione di voce —, salvalo nella tua libreria di asset. Se un modello accetta pesi di stile personalizzati, porta il tuo file LoRA.

La libreria di asset

Un asset salvato riceve un URI stabile, popnow://a/ast_…, che puoi inserire in qualsiasi campo media del tipo giusto di qualsiasi modello, finché lo conservi:

{ "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"] } }

L’URI è un riferimento, non un link di download: funziona solo nelle richieste di generazione fatte con le chiavi del tuo account. Gli asset restano finché non li elimini.

Salva un file

POST /api/v1/assets copia un file nella libreria. Scegli una fonte; l’header Idempotency-Key è obbligatorio e salvare di nuovo la stessa fonte restituisce l’asset già esistente.

`source`	Invia anche	Salva
`task_output`	`taskId` e la `key` o l’`index` del risultato	Un file prodotto da una tua attività riuscita
`upload`	`fileId`	Un caricamento confermato
`url`	`url`	Un file pubblico `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\"}"

La risposta è l’asset: id, uri, name, kind (image, video o audio), dimensioni e peso, il model che l’ha generato e una previewUrl privata valida circa 20 minuti. Salva l’uri, mai il link di anteprima.

Elenca, rinomina ed elimina

Chiamata	Effetto
`GET /api/v1/assets`	Una pagina di asset. Filtra con `kind`, `source`, `favorite`, `q` (ricerca per nome), `collectionId`, `entityId`; ordina con `sort=recent\|oldest\|name\|size`; prosegui con `cursor`
`GET /api/v1/assets/{id}`	Un asset con un nuovo link di anteprima
`PATCH /api/v1/assets/{id}`	Modifica `name` e/o `favorite`
`DELETE /api/v1/assets/{id}`	Lo elimina; il suo URI smette di funzionare nelle nuove richieste
`GET /api/v1/assets/entities`	I tuoi personaggi: insiemi di immagini con un nome, organizzati sul sito, ogni immagine con il proprio URI
`GET /api/v1/assets/usage`	Il tuo piano di archiviazione, quanto usi, i limiti e cosa sblocca il piano successivo

Piani di archiviazione

L’archiviazione si apre con il tuo primo acquisto di crediti e cresce con il totale acquistato nel tempo; non si riduce mai e gli asset salvati restano sempre utilizzabili. GET /api/v1/assets/usage mostra i numeri del tuo account.

Errori

Gli errori della libreria aggiungono un data.reason leggibile dalle macchine all’involucro consueto:

`data.reason`	HTTP	Significato
`asset_library_locked`	400	La libreria si apre dopo il tuo primo acquisto di crediti
`asset_library_full`	400	Spazio o numero di elementi del piano esauriti — elimina asset o passa al piano superiore
`asset_file_too_large`	400	Il file supera il limite per file del tuo piano
`asset_daily_limit`	429	Raggiunto il numero giornaliero di nuovi asset; attendi `Retry-After` (00:00 UTC)
`asset_storage_full`	503	L’archiviazione è temporaneamente piena da parte nostra; riprova più tardi

Tratta un motivo sconosciuto come se mancasse. La lettura è limitata a 60 richieste al minuto, il salvataggio a 30.

Porta la tua LoRA

I modelli il cui ID termina con -lora accettano un array loras: fino a tre file di pesi, ognuno con path e scale (da 0 a 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 può essere un link diretto pubblico a un file .safetensors oppure un file che hai caricato o importato:

Caricalo come qualsiasi altro file con contentType: application/octet-stream (un file .safetensors fino a 2 GiB; il ticket vale due ore). La conferma verifica che sia un file safetensors completo.
Importalo da un link quando il file richiede l’accesso, per esempio in un repository privato di 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 accetta un ID di repository Hugging Face (owner/repo, se contiene esattamente un file .safetensors), una pagina di repository o di file di Hugging Face, o qualsiasi link diretto HTTPS. token è facoltativo — un token di accesso Hugging Face o una chiave API di Civitai — e viene usato solo per questo download, senza essere mai salvato. La risposta ha la stessa forma di una conferma: inserisci il suo uri in loras[].path.

Una LoRA deve corrispondere al modello base per cui è stata addestrata; pesi pensati per un’altra base di solito falliscono o non hanno effetto. Spetta a te avere il diritto di usare i pesi che porti.