Medios

Envía imágenes, video y audio de referencia por URL, incrustados o subiéndolos, y descarga los archivos que genera una tarea.

Muchos modelos reciben archivos como entrada: una foto que animar, un clip que alargar, una muestra de voz, una canción. Hay cuatro formas de entregar uno y una sola de recuperar los resultados.

Cuatro formas de enviar un archivo

Tienes	Envíalo como	Ideal para
Un enlace HTTPS público	La URL tal cual, p. ej. `"image_url": "https://…/photo.jpg"`	Archivos que ya alojas
Una imagen pequeña en memoria	Un data URI, p. ej. `"image_url": "data:image/png;base64,…"`	Pruebas rápidas, imágenes de menos de 1 MiB
Un archivo local	Una subida y luego `"image_url": "popnow://f/fil_…"`	Todo lo demás, incluidos video y audio
Un archivo de tu biblioteca	`"image_url": "popnow://a/ast_…"`	Archivos que reutilizas en muchas tareas. Mira Recursos

Elijas la que elijas, el archivo va en el campo que el esquema del modelo declara para él (image_url, image_urls, video_url, audio_url…).

Enlaces públicos

El enlace tiene que devolver el archivo en sí y seguir accesible sin iniciar sesión mientras dura la tarea. Una página para compartir de una nube o red social devuelve una página web, no el archivo, y la tarea falla con invalid_asset; en ese caso descarga el archivo y súbelo.

Imágenes incrustadas

Las imágenes se pueden enviar como data URI Base64 estándar con su tipo MIME: JPEG, PNG, WebP o GIF, cada una de 1 MiB decodificada y 8192 píxeles por lado como máximo, hasta 16 imágenes por solicitud y todo el cuerpo JSON por debajo de 2 MiB. No se aceptan Base64 sin prefijo, SVG ni video o audio incrustados. Las imágenes incrustadas se guardan como subidas de tu cuenta, así que el input de la tarea muestra un URI popnow:// en lugar de devolverte los bytes.

Sube un archivo

Subir lleva tres llamadas: pedir un ticket de subida, hacer PUT de los bytes y confirmar.

Pide 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 respuesta trae fileId, uploadUrl, los headers exactos que hay que enviar, expiresAt (dentro de unos 20 minutos) y maxBytes. No hay nombre de archivo: las rutas de almacenamiento siempre las elige el servidor.

Haz PUT de los bytes

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"

Envía cada cabecera del ticket tal como viene —todas forman parte de la firma— y ninguna cabecera Authorization. En un navegador, omite Content-Length y envía un File o Blob del tamaño exacto declarado; el navegador la pone por ti.

Confirma

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

La confirmación revisa el tamaño, el tipo y la firma del archivo, y devuelve el URI que hay que usar:

{
  "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_…"
}

Pon uri en el campo del modelo, por ejemplo "image_url": "popnow://f/fil_…". Un URI popnow:// solo funciona con las claves de tu propia cuenta. Confirmar dos veces es seguro.

Límites de subida

Tipo	`contentType`	Archivo más grande	Duración máxima
Imagen	`image/jpeg`, `image/png`, `image/webp`, `image/gif`	10 MiB	—
Video	`video/mp4`, `video/webm`	90 MiB	600 segundos
Audio	`audio/mpeg`, `audio/wav`	90 MiB	600 segundos
Pesos LoRA	`application/octet-stream` (un archivo `.safetensors`)	2 GiB	—

Un modelo puede aceptar menos; su esquema lo indica campo por campo. Los archivos subidos son temporales —el expiresAt de la respuesta de confirmación dice cuándo se borran—, así que súbelos poco antes de crear la tarea. Para reutilizar un archivo, guárdalo en tu biblioteca de recursos.

Si una confirmación responde 40003, los bytes que enviaste no coinciden con el ticket (tamaño, tipo o contenido distintos). Pide un ticket nuevo y vuelve a subirlo.

Descarga los resultados

Una tarea terminada lista sus archivos en output.assets, cada uno con una url lista para usar:

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')"

El enlace está firmado y funciona unos 20 minutos (expiresAt). No lo guardes; guarda el taskId y vuelve a leer la tarea para obtener uno nuevo.
No adjuntes tu clave de API al descargar. El enlace en sí es el permiso: cualquiera que lo tenga puede descargar el archivo hasta que caduque.
Para generar un enlace sin leer toda la tarea, llama a POST /api/v1/common/download-url con { "taskId": "…" } (y, si quieres, la key del archivo).

Los archivos en sí se conservan hasta la hora indicada en retention.outputsExpireAt de la tarea, o hasta que purgues la tarea. Copia lo que necesites más allá a tu propio almacenamiento o a tu biblioteca de recursos.

Medios

En esta página