Media

Invia immagini, video e audio di riferimento tramite URL, incorporati o con un caricamento, e scarica i file prodotti da un’attività.

Molti modelli ricevono file in input: una foto da animare, una clip da allungare, un campione di voce, una canzone. Ci sono quattro modi per passarne uno e uno solo per riprendere i risultati.

Quattro modi per inviare un file

Hai	Invialo come	Ideale per
Un link HTTPS pubblico	L’URL stesso, es. `"image_url": "https://…/photo.jpg"`	File che ospiti già
Una piccola immagine in memoria	Un data URI, es. `"image_url": "data:image/png;base64,…"`	Test rapidi, immagini sotto 1 MiB
Un file locale	Un caricamento, poi `"image_url": "popnow://f/fil_…"`	Tutto il resto, video e audio compresi
Un file della tua libreria	`"image_url": "popnow://a/ast_…"`	File che riusi in molte attività. Vedi Asset

Qualunque modo tu scelga, il file va nel campo che lo schema del modello dichiara per lui (image_url, image_urls, video_url, audio_url …).

Link pubblici

Il link deve restituire il file stesso e restare raggiungibile senza accesso per tutta la durata dell’attività. Una pagina di condivisione di un cloud o di un social restituisce una pagina web, non il file, e l’attività fallisce con invalid_asset; in quel caso scarica il file e caricalo.

Immagini incorporate

Le immagini si possono inviare come data URI Base64 standard con il tipo MIME: JPEG, PNG, WebP o GIF, ognuna al massimo 1 MiB decodificata e 8.192 pixel per lato, fino a 16 immagini per richiesta e l’intero corpo JSON sotto i 2 MiB. Base64 senza prefisso, SVG e video o audio incorporati non sono accettati. Le immagini incorporate vengono salvate come caricamenti del tuo account, quindi l’input dell’attività mostra un URI popnow:// invece di restituire i byte.

Carica un file

Il caricamento richiede tre chiamate: chiedere un ticket, fare il PUT dei byte, poi confermare.

Chiedi un ticket

FILE=reference.png
CONTENT_TYPE=image/png
BYTES=$(wc -c < "$FILE" | tr -d ' ')

TICKET=$(curl -s -X POST "https://api.popnow.ai/api/v1/common/upload-url" \
  -H "Authorization: Bearer $POPNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"contentType\": \"$CONTENT_TYPE\", \"bytes\": $BYTES}")
UPLOAD_URL=$(echo "$TICKET" | jq -r .data.uploadUrl)
FILE_ID=$(echo "$TICKET" | jq -r .data.fileId)

La risposta contiene fileId, uploadUrl, gli headers esatti da inviare, expiresAt (tra circa 20 minuti) e maxBytes. Non c’è un nome file: i percorsi di archiviazione li sceglie sempre il server.

Fai il PUT dei byte

curl -s -o /dev/null -w "%{http_code}\n" -X PUT "$UPLOAD_URL" \
  -H "Content-Type: $CONTENT_TYPE" \
  -H "Content-Length: $BYTES" \
  --data-binary @"$FILE"

Invia ogni header del ticket esattamente com’è — fanno tutti parte della firma — e nessun header Authorization. In un browser, ometti Content-Length e invia un File o un Blob della dimensione esatta dichiarata; ci pensa il browser.

Conferma

curl -s -X POST "https://api.popnow.ai/api/v1/files/$FILE_ID/commit" \
  -H "Authorization: Bearer $POPNOW_API_KEY"

La conferma verifica dimensione, tipo e firma del file e restituisce l’URI da usare:

{
  "code": 200,
  "msg": "success",
  "data": {
    "fileId": "fil_01k3m8x9q2z4v7n5p6r8s0t1w3",
    "status": "ready",
    "uri": "popnow://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3",
    "contentType": "image/png",
    "bytes": 402118,
    "width": 1024,
    "height": 1024,
    "expiresAt": "2026-10-17T09:12:00Z"
  },
  "request_id": "req_…"
}

Inserisci uri nel campo del modello, per esempio "image_url": "popnow://f/fil_…". Un URI popnow:// funziona solo con le chiavi del tuo account. Confermare due volte è sicuro.

Limiti di caricamento

Tipo	`contentType`	File più grande	Durata massima
Immagine	`image/jpeg`, `image/png`, `image/webp`, `image/gif`	10 MiB	—
Video	`video/mp4`, `video/webm`	90 MiB	600 secondi
Audio	`audio/mpeg`, `audio/wav`	90 MiB	600 secondi
Pesi LoRA	`application/octet-stream` (un file `.safetensors`)	2 GiB	—

Un modello può accettare meno; il suo schema lo indica campo per campo. I file caricati sono temporanei — l’expiresAt nella risposta di conferma dice quando il file viene eliminato —, quindi caricali poco prima di creare l’attività. Per riusare un file, salvalo nella tua libreria di asset.

Se una conferma risponde 40003, i byte inviati non corrispondono al ticket (dimensione, tipo o contenuto diversi). Chiedi un nuovo ticket e ricarica il file.

Scarica i risultati

Un’attività completata elenca i suoi file in output.assets, ognuno con una url pronta all’uso:

curl -L -o result.mp4 "$(curl -s "https://api.popnow.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
  -H "Authorization: Bearer $POPNOW_API_KEY" | jq -r '.data.output.assets[0].url')"

Il link è firmato e funziona per circa 20 minuti (expiresAt). Non salvarlo; salva il taskId e rileggi l’attività per un link nuovo.
Non allegare la chiave API al download. Il link stesso è il permesso: chiunque lo abbia può scaricare il file finché non scade.
Per creare un link senza rileggere tutta l’attività, chiama POST /api/v1/common/download-url con { "taskId": "…" } (ed eventualmente la key del file).

I file restano conservati fino all’orario indicato in retention.outputsExpireAt dell’attività, o finché non elimini l’attività. Copia nel tuo archivio o nella tua libreria di asset ciò che ti serve oltre quel momento.

Media

In questa pagina