Assets e arquivos LoRA

Guarde arquivos na sua biblioteca e reutilize por URI, leia seus personagens e traga seus próprios pesos LoRA.

Uploads e resultados de tarefas são temporários. Quando quiser reutilizar um arquivo em muitas tarefas — uma foto de produto, o rosto de um personagem, uma amostra de voz —, salve-o na sua biblioteca de assets. Quando um modelo aceita pesos de estilo personalizados, traga seu próprio arquivo LoRA.

A biblioteca de assets

Um asset salvo ganha um URI fixo, popnow://a/ast_…, que você pode colocar em qualquer campo de mídia do tipo certo, em qualquer modelo, enquanto mantiver o asset:

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

O URI é uma referência, não um link de download: ele só funciona em requisições de geração feitas com chaves da sua conta. Os assets ficam até você apagá-los.

Salve um arquivo

POST /api/v1/assets copia um arquivo para a biblioteca. Escolha uma origem; o cabeçalho Idempotency-Key é obrigatório, e salvar de novo a mesma origem devolve o asset que já existe.

`source`	Envie também	Salva
`task_output`	`taskId` e a `key` ou o `index` do resultado	Um arquivo gerado por uma tarefa sua que deu certo
`upload`	`fileId`	Um upload confirmado
`url`	`url`	Um arquivo público `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\"}"

A resposta é o asset: id, uri, name, kind (image, video ou audio), tamanho e dimensões, o model que o gerou e uma previewUrl privada válida por uns 20 minutos. Guarde o uri, nunca o link de pré-visualização.

Listar, renomear e apagar

Chamada	O que faz
`GET /api/v1/assets`	Uma página de assets. Filtre com `kind`, `source`, `favorite`, `q` (busca por nome), `collectionId`, `entityId`; ordene com `sort=recent\|oldest\|name\|size`; continue com `cursor`
`GET /api/v1/assets/{id}`	Um asset com novo link de pré-visualização
`PATCH /api/v1/assets/{id}`	Altera `name` e/ou `favorite`
`DELETE /api/v1/assets/{id}`	Apaga; o URI deixa de funcionar em requisições novas
`GET /api/v1/assets/entities`	Seus personagens: conjuntos de imagens com nome, organizados no site, cada imagem com o próprio URI
`GET /api/v1/assets/usage`	Seu plano de armazenamento, quanto você usa, os limites e o que o próximo plano libera

Planos de armazenamento

O armazenamento é liberado com a sua primeira compra de créditos e cresce conforme o total que você já comprou; ele nunca diminui, e os assets salvos continuam sempre utilizáveis. GET /api/v1/assets/usage mostra os números da sua conta.

Erros

Os erros da biblioteca acrescentam um data.reason legível por máquina ao envelope de sempre:

`data.reason`	HTTP	Significado
`asset_library_locked`	400	A biblioteca abre depois da sua primeira compra de créditos
`asset_library_full`	400	O espaço ou a quantidade de itens do plano acabou — apague assets ou suba de plano
`asset_file_too_large`	400	O arquivo passa do limite por arquivo do seu plano
`asset_daily_limit`	429	Atingiu o número diário de novos assets; espere `Retry-After` (00:00 UTC)
`asset_storage_full`	503	O armazenamento está cheio do nosso lado por enquanto; tente mais tarde

Trate um motivo desconhecido como se não houvesse motivo. Leituras têm limite de 60 requisições por minuto e salvamentos, de 30 por minuto.

Traga seu próprio LoRA

Modelos cujo ID termina em -lora aceitam um array loras — até três arquivos de pesos, cada um com path e scale (de 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 pode ser um link direto público para um arquivo .safetensors ou um arquivo que você enviou ou importou:

Envie como qualquer outro arquivo, com contentType: application/octet-stream (um arquivo .safetensors de até 2 GiB; o ticket vale por duas horas). A confirmação verifica se é um arquivo safetensors completo.
Importe por link quando o arquivo exigir login, por exemplo num repositório privado do 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 aceita um ID de repositório do Hugging Face (owner/repo, quando há exatamente um arquivo .safetensors), uma página de repositório ou de arquivo do Hugging Face ou qualquer link direto HTTPS. token é opcional — um token de acesso do Hugging Face ou uma chave de API do Civitai — e só é usado nesse download, nunca armazenado. A resposta tem o mesmo formato de uma confirmação: coloque o uri dela em loras[].path.

Um LoRA precisa combinar com o modelo base para o qual foi treinado; pesos de outra base costumam falhar ou não ter efeito. Você é responsável por ter o direito de usar os pesos que traz.