Медиа

Как отправить референсные изображения, видео и аудио по ссылке, встроенными данными или загрузкой — и как скачать файлы, созданные задачей.

Многие модели принимают файлы на вход: фото, которое нужно оживить, клип для продления, образец голоса, песню. Передать файл можно четырьмя способами, а получить результат — одним.

Четыре способа отправить файл

Что у вас есть	Как отправить	Когда подходит
Публичная HTTPS-ссылка	Сам URL, например `"image_url": "https://…/photo.jpg"`	Файлы, которые вы уже где-то храните
Небольшое изображение в памяти	Data URI, например `"image_url": "data:image/png;base64,…"`	Быстрые тесты, изображения до 1 МиБ
Локальный файл	Загрузка, затем `"image_url": "popnow://f/fil_…"`	Всё остальное, включая видео и аудио
Файл из библиотеки ассетов	`"image_url": "popnow://a/ast_…"`	Файлы, которые используются во многих задачах. См. Ассеты

Каким бы способом вы ни воспользовались, файл кладётся в поле, которое схема модели для него объявляет (image_url, image_urls, video_url, audio_url …).

Ссылка должна отдавать сам файл и оставаться доступной без входа, пока идёт задача. Страница «поделиться» из облачного диска или соцсети отдаёт веб-страницу, а не файл, и задача падает с invalid_asset; в этом случае скачайте файл и загрузите его.

Встроенные изображения

Изображения можно отправить стандартным Base64 data URI с MIME-типом: JPEG, PNG, WebP или GIF, каждое не больше 1 МиБ после декодирования и 8192 пикселей по стороне, до 16 изображений на запрос, а всё тело JSON — меньше 2 МиБ. Base64 без префикса, SVG и встроенные видео или аудио не принимаются. Встроенные изображения сохраняются как загрузки вашего аккаунта, поэтому в input задачи вместо байтов будет URI popnow://.

Загрузка файла

Загрузка — это три вызова: получить тикет, отправить байты через PUT и подтвердить.

Получите тикет

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)

В ответе есть fileId, uploadUrl, точные headers, которые нужно отправить, expiresAt (примерно через 20 минут) и maxBytes. Имени файла нет: пути хранения всегда выбирает сервер.

Отправьте байты через 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"

Отправьте каждый заголовок из тикета в точности как есть — все они входят в подпись — и без заголовка Authorization. В браузере не указывайте Content-Length и отправьте File или Blob ровно заявленного размера: браузер выставит заголовок сам.

Подтвердите

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

Подтверждение проверяет размер, тип и сигнатуру файла и возвращает URI для использования:

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

Подставьте uri в поле модели, например "image_url": "popnow://f/fil_…". URI popnow:// работает только с ключами вашего аккаунта. Повторное подтверждение безопасно.

Ограничения загрузки

Тип	`contentType`	Максимальный размер	Максимальная длительность
Изображение	`image/jpeg`, `image/png`, `image/webp`, `image/gif`	10 МиБ	—
Видео	`video/mp4`, `video/webm`	90 МиБ	600 секунд
Аудио	`audio/mpeg`, `audio/wav`	90 МиБ	600 секунд
Веса LoRA	`application/octet-stream` (файл `.safetensors`)	2 ГиБ	—

Конкретная модель может принимать меньше — это указано в её схеме для каждого поля. Загруженные файлы временные: expiresAt в ответе подтверждения говорит, когда файл удалят, поэтому загружайте незадолго до создания задачи. Файлы для многократного использования сохраняйте в библиотеку ассетов.

Если подтверждение вернуло 40003, отправленные байты не совпадают с тикетом (другие размер, тип или содержимое). Получите новый тикет и загрузите заново.

Скачивание результатов

Завершённая задача перечисляет файлы в output.assets, у каждого есть готовая к использованию 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')"

Ссылка подписана и работает около 20 минут (expiresAt). Не храните её; храните taskId и перечитывайте задачу, чтобы получить новую.
Не прикладывайте API-ключ при скачивании. Сама ссылка и есть разрешение: любой, у кого она есть, может скачать файл до истечения срока.
Чтобы получить ссылку, не читая всю задачу, вызовите POST /api/v1/common/download-url с { "taskId": "…" } (и при желании key файла).

Сами файлы хранятся до времени, указанного в retention.outputsExpireAt задачи, или пока вы не удалите содержимое задачи. Всё, что нужно дольше, копируйте в своё хранилище или в библиотеку ассетов.