Media

Jak wysłać obrazy, wideo i audio referencyjne przez URL, osadzone w zapytaniu albo przesłane — i jak pobrać pliki utworzone przez zadanie.

Wiele modeli przyjmuje pliki na wejściu: zdjęcie do ożywienia, klip do przedłużenia, próbkę głosu, piosenkę. Plik można przekazać na cztery sposoby, a wynik odebrać na jeden.

Cztery sposoby wysłania pliku

Masz	Wyślij jako	Najlepsze do
Publiczny link HTTPS	Sam URL, np. `"image_url": "https://…/photo.jpg"`	Plików, które już hostujesz
Mały obraz w pamięci	Data URI, np. `"image_url": "data:image/png;base64,…"`	Szybkich testów, obrazów poniżej 1 MiB
Plik lokalny	Przesłanie, a potem `"image_url": "popnow://f/fil_…"`	Wszystkiego innego, także wideo i audio
Plik z biblioteki zasobów	`"image_url": "popnow://a/ast_…"`	Plików używanych w wielu zadaniach. Zobacz Zasoby

Niezależnie od sposobu plik trafia do pola, które schemat modelu dla niego deklaruje (image_url, image_urls, video_url, audio_url …).

Link musi zwracać sam plik i pozostawać dostępny bez logowania przez cały czas trwania zadania. Strona udostępniania z dysku w chmurze lub portalu społecznościowego zwraca stronę WWW, a nie plik, i zadanie kończy się błędem invalid_asset; wtedy pobierz plik i prześlij go.

Obrazy osadzone

Obrazy można wysłać jako standardowe data URI Base64 z typem MIME: JPEG, PNG, WebP lub GIF, każdy najwyżej 1 MiB po zdekodowaniu i 8192 piksele na bok, do 16 obrazów na zapytanie, a cała treść JSON poniżej 2 MiB. Base64 bez prefiksu, SVG ani osadzone wideo czy audio nie są akceptowane. Osadzone obrazy są zapisywane jako przesłane pliki twojego konta, więc input zadania pokazuje URI popnow:// zamiast zwracać bajty.

Prześlij plik

Przesyłanie to trzy wywołania: poproś o bilet, wyślij bajty przez PUT, a potem zatwierdź.

Poproś o bilet

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)

Odpowiedź zawiera fileId, uploadUrl, dokładne headers do wysłania, expiresAt (za około 20 minut) i maxBytes. Nazwy pliku nie ma: ścieżki zapisu zawsze wybiera serwer.

Wyślij bajty przez PUT

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"

Wyślij każdy nagłówek z biletu dokładnie w podanej postaci — wszystkie są częścią podpisu — i bez nagłówka Authorization. W przeglądarce pomiń Content-Length i wyślij File lub Blob o dokładnie zadeklarowanym rozmiarze; przeglądarka ustawi nagłówek sama.

Zatwierdź

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

Zatwierdzenie sprawdza rozmiar, typ i sygnaturę pliku, a potem zwraca URI do użycia:

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

Wstaw uri w pole modelu, na przykład "image_url": "popnow://f/fil_…". URI popnow:// działa tylko z kluczami twojego konta. Ponowne zatwierdzenie jest bezpieczne.

Limity przesyłania

Typ	`contentType`	Największy plik	Najdłuższy czas trwania
Obraz	`image/jpeg`, `image/png`, `image/webp`, `image/gif`	10 MiB	—
Wideo	`video/mp4`, `video/webm`	90 MiB	600 sekund
Audio	`audio/mpeg`, `audio/wav`	90 MiB	600 sekund
Wagi LoRA	`application/octet-stream` (plik `.safetensors`)	2 GiB	—

Model może przyjmować mniej; jego schemat podaje to dla każdego pola. Przesłane pliki są tymczasowe — expiresAt w odpowiedzi zatwierdzenia mówi, kiedy plik zostanie usunięty — więc przesyłaj je tuż przed utworzeniem zadania. Pliki do wielokrotnego użytku zapisz w bibliotece zasobów.

Jeśli zatwierdzenie zwróci 40003, wysłane bajty nie zgadzają się z biletem (inny rozmiar, typ lub zawartość). Poproś o nowy bilet i prześlij plik ponownie.

Pobierz wyniki

Ukończone zadanie wymienia swoje pliki w output.assets, każdy z gotowym do użycia url:

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

Link jest podpisany i działa około 20 minut (expiresAt). Nie zapisuj go; zapisz taskId i odczytaj zadanie ponownie, by dostać nowy link.
Nie dołączaj klucza API przy pobieraniu. Sam link jest uprawnieniem: każdy, kto go ma, może pobrać plik do jego wygaśnięcia.
Aby utworzyć link bez odczytu całego zadania, wywołaj POST /api/v1/common/download-url z { "taskId": "…" } (opcjonalnie z key pliku).

Same pliki są przechowywane do czasu z retention.outputsExpireAt zadania albo dopóki nie usuniesz treści zadania. To, czego potrzebujesz dłużej, skopiuj do własnego magazynu lub biblioteki zasobów.