Mídia

Envie imagens, vídeos e áudios de referência por URL, embutidos ou por upload, e baixe os arquivos que uma tarefa produz.

Muitos modelos recebem arquivos como entrada — uma foto para animar, um clipe para estender, uma amostra de voz, uma música. Há quatro jeitos de entregar um arquivo e um só de pegar os resultados.

Quatro jeitos de enviar um arquivo

Você tem	Envie como	Melhor para
Um link HTTPS público	A própria URL, ex.: `"image_url": "https://…/photo.jpg"`	Arquivos que você já hospeda
Uma imagem pequena na memória	Um data URI, ex.: `"image_url": "data:image/png;base64,…"`	Testes rápidos, imagens com menos de 1 MiB
Um arquivo local	Um upload e depois `"image_url": "popnow://f/fil_…"`	Todo o resto, inclusive vídeo e áudio
Um arquivo da sua biblioteca	`"image_url": "popnow://a/ast_…"`	Arquivos reaproveitados em muitas tarefas. Veja Assets

Seja qual for o jeito, o arquivo vai no campo que o schema do modelo declara para ele (image_url, image_urls, video_url, audio_url …).

Links públicos

O link precisa devolver o próprio arquivo e continuar acessível sem login enquanto a tarefa roda. Uma página de compartilhamento de nuvem ou de rede social devolve uma página web, não o arquivo, e a tarefa falha com invalid_asset; nesse caso, baixe o arquivo e faça o upload.

Imagens embutidas

Imagens podem ir como data URI Base64 padrão com o tipo MIME: JPEG, PNG, WebP ou GIF, cada uma com no máximo 1 MiB decodificada e 8.192 pixels por lado, até 16 imagens por requisição e o corpo JSON inteiro abaixo de 2 MiB. Base64 sem prefixo, SVG e vídeo ou áudio embutidos não são aceitos. Imagens embutidas são guardadas como uploads da sua conta, por isso o input da tarefa mostra um URI popnow:// em vez de devolver os bytes.

Faça upload de um arquivo

O upload leva três chamadas: pedir um ticket, fazer PUT dos bytes e confirmar.

Peça um 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)

A resposta traz fileId, uploadUrl, os headers exatos a enviar, expiresAt (daqui a uns 20 minutos) e maxBytes. Não há nome de arquivo: os caminhos de armazenamento são sempre escolhidos pelo servidor.

Faça PUT dos 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"

Envie cada cabeçalho do ticket exatamente como veio — todos fazem parte da assinatura — e nenhum cabeçalho Authorization. No navegador, deixe de fora o Content-Length e envie um File ou Blob com exatamente o tamanho declarado; o navegador define o cabeçalho para você.

Confirme

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

A confirmação verifica tamanho, tipo e assinatura do arquivo e devolve o URI a 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_…"
}

Coloque uri no campo do modelo, por exemplo "image_url": "popnow://f/fil_…". Um URI popnow:// só funciona com chaves da sua própria conta. Confirmar duas vezes é seguro.

Limites de upload

Tipo	`contentType`	Maior arquivo	Duração máxima
Imagem	`image/jpeg`, `image/png`, `image/webp`, `image/gif`	10 MiB	—
Vídeo	`video/mp4`, `video/webm`	90 MiB	600 segundos
Áudio	`audio/mpeg`, `audio/wav`	90 MiB	600 segundos
Pesos LoRA	`application/octet-stream` (um arquivo `.safetensors`)	2 GiB	—

Um modelo pode aceitar menos; o schema dele diz isso campo a campo. Arquivos enviados são temporários — o expiresAt da resposta da confirmação diz quando o arquivo é removido —, então faça o upload pouco antes de criar a tarefa. Para reaproveitar um arquivo, salve-o na sua biblioteca de assets.

Se a confirmação responder 40003, os bytes enviados não batem com o ticket (tamanho, tipo ou conteúdo diferentes). Peça um ticket novo e envie de novo.

Baixe os resultados

Uma tarefa concluída lista os arquivos em output.assets, cada um com uma url pronta 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')"

O link é assinado e funciona por uns 20 minutos (expiresAt). Não guarde o link; guarde o taskId e leia a tarefa de novo para pegar um link novo.
Não envie a chave de API ao baixar. O próprio link é a permissão: quem o tiver pode baixar o arquivo até ele expirar.
Para gerar um link sem ler a tarefa inteira, chame POST /api/v1/common/download-url com { "taskId": "…" } (e, se quiser, a key do arquivo).

Os arquivos em si ficam guardados até o horário em retention.outputsExpireAt da tarefa, ou até você apagar a tarefa. Copie para o seu próprio armazenamento ou para a sua biblioteca de assets o que precisar depois disso.

Mídia

Nesta página