API увеличения видео: процесс доставки и проверки качества

У вас есть короткий клип, который нравится, полученный дёшево в 480p или вырезанный из старых материалов, а выпустить его нужно в 1080p или 4K вместе с исходной звуковой дорожкой. API увеличения видео делает это одним вызовом, но вызов — лишь середина работы. Определяет пригодность файла то, что вы делаете до него (заканчиваете монтаж, проверяете исходник) и после него (успеваете скачать, подтверждаете размер, длительность и звук, экспортируете ровно то полотно, которое требует площадка).

Коротко: увеличьте финальный монтаж один раз, на том уровне, который нужен площадке. SpicyAPI Video Upscaler принимает один MP4 длиной от 3 до 60 секунд и уровень, а возвращает тот же клип с более высоким разрешением, сохраняя длительность, соотношение сторон, движение и звуковую дорожку. Промпта нет. Цены: $0.006 за секунду исходника в 720p или 1080p, $0.012 в 2K, $0.024 в 4K.

Что вы отправляете и сколько платите

Отправьте video_url (прямую ссылку на MP4 или загруженный файл) и, по желанию, resolution: 720p, 1080p (по умолчанию), 2k или 4k. Загруженные MP4 могут весить до 90 МБ. Тарификация идёт по секундам исходного клипа с округлением вверх до целой секунды и минимумом в три секунды.

Округление применяется к каждому отправленному клипу отдельно, поэтому три клипа по 5.2 секунды оплачиваются как 18 секунд, а не как 16. Оценка, показанная перед отправкой, предполагает клип длиной 60 секунд ($0.36 в 1080p, $1.44 в 4K); неиспользованная часть освобождается при расчёте задачи, поэтому клип длиной 6 секунд оплачивается как 6 секунд. За неудачную задачу возвращают деньги.

Довод в пользу увеличения лежит на стороне генерации. Клип 10 секунд, созданный в 480p через Seedance 2.5 Spicy, стоит $2.16 за попытку; в нативном 1080p — $10.80. Сделайте черновик в 480p, оставьте нужный дубль и добавьте $0.06 за увеличение до 1080p. Апскейлер увеличивает только то, что уже есть в кадре, поэтому детали, которой нет в черновике, не появится. Если мелкая этикетка или лицо должны быть точными, проверьте их в черновике или снимите черновик в более высоком разрешении.

Подготовьте исходник

Сначала закончите монтаж. Обрежьте, переставьте и смикшируйте звук до увеличения. Иначе каждая последующая правка делалась бы на файле, в котором в несколько раз больше пикселей, и вы платили бы за обработку секунд, которые выбросите. Апскейлер не исправит неверный дубль: искажённая рука или уезжающий логотип вернутся ещё больше.

Проверьте файл. ffprobe показывает то, что вы действительно отправляете, включая длительность, которая на экране округляется до «60 секунд», но на самом деле равна 60.4:

ffprobe -v error \
  -show_entries format=duration,size:stream=codec_type,codec_name,width,height,avg_frame_rate,sample_rate,channels \
  -of json approved-source.mp4

На что посмотреть. Длительность должна попадать в диапазон от 3 до 60 секунд. Клип с телефона может проигрываться вертикально, тогда как сохранённый кадр горизонтальный плюс флаг поворота (ffprobe -show_streams перечисляет его в side data); запеките поворот перед загрузкой. И отметьте звуковой поток: позже вы сравните его с результатом.

Пропускайте клипы, которые уже достаточно большие. Клип на уровне или выше возвращается примерно того же размера, но оплачивается: клип 786x1178, отправленный в 720p, вернулся как 784x1176. Если исходник уже удовлетворяет требованиям площадки, экспортируйте его и на этом закончите.

Начинайте с самого чистого мастера. Блоки сжатия и шум увеличиваются вместе со всем остальным. Используйте мастер генерации или монтажа, а не копию, заново скачанную из социальной ленты.

Выберите уровень по площадке

Уровень — это бюджет пикселей с сохранённым соотношением сторон, поэтому нестандартные исходники возвращаются нестандартными размерами. Клип 832x480 вернулся как 1896x1094 в 1080p и как 3792x2188 в 4K; клип 854x480 вернулся как 1922x1080. Не ждите ровно 1920x1080.

• 720p или 1080p для лент, посадочных страниц и рекламы. Стоят одинаково, поэтому выбирайте по площадке, а не по цене. 1080p — значение по умолчанию и обычно верный выбор.
• 2K или 4K для больших экранов, презентаций или когда вы будете кадрировать потом. Они стоят в два и четыре раза дороже и требуют больше времени: около 35 секунд для пятисекундной задачи в 1080p и около 100 секунд в 4K. Пятисекундный файл в 4K весит около 19 МБ.
• Если площадке нужно ровное полотно, например 1080x1920 для вертикальной ленты, считайте это отдельным шагом экспорта после увеличения.

Увеличение горизонтального клипа с последующим кадрированием в вертикаль оплачивает отбрасываемые пиксели. Определите кадрирование до увеличения и отправьте итоговую композицию.

Сначала попробуйте в Playground

1. Откройте страницу Video Upscaler и оставайтесь во вкладке Playground в представлении Form. Войдите под аккаунтом с балансом, чтобы запустить выполнение.
2. В поле Input video поместите утверждённый MP4 (до 90 МБ) или вставьте прямую ссылку на файл через Asset URL. Страница, которая проигрывает видео, отдаёт HTML, и вызов завершается ошибкой с возвратом списания; загрузка файла — самый надёжный путь.
3. Задайте Resolution как 720p, 1080p, 2K или 4K. Поле помечено как влияющее на цену, и оценка пересчитывается по вашему выбору.
4. Запустите, проиграйте результат в сравнении с исходником (см. проверки ниже) и только потом скопируйте его в собственное хранилище.

Пятисекундный клип стоит несколько центов даже в 4K, поэтому попробуйте свой настоящий клип на том уровне, на котором собираетесь выпустить его, прежде чем писать код.

Затем запустите из кода

Установите Python SDK (pip install spicyapi), задайте SPICY_API_KEY в окружении сервера и выполните:

import uuid
from spicyapi import SpicyClient, output_assets

client = SpicyClient()  # reads SPICY_API_KEY from the environment

task = client.create_task(
    model="spicyapi/video-upscaler-v1/upscale",
    input_data={
        "video_url": "https://example.com/approved-product-ad.mp4",
        "resolution": "1080p",
    },
    idempotency_key=str(uuid.uuid4()),  # one key per approved clip and tier
)

print("Resume task:", task["taskId"], flush=True)
final = client.wait_for_terminal(task["taskId"])
if final["state"] != "succeeded":
    raise RuntimeError(f"{task['taskId']} ended as {final['state']}: {final.get('errorCode')}")
assets = output_assets(final)
if not assets or any(a.get("pending") or a.get("unavailable") or not a.get("url") for a in assets):
    raise RuntimeError(f"Task {task['taskId']} has no ready output; check this task before a new run")
print(assets[0]["url"])  # copy the file to your own storage now

Создание, ожидание, повторные попытки, коды ошибок и загрузка разобраны в руководстве по задачам и справочнике Python SDK; локальный файл проходит через бесплатный поток загрузки и передаётся как URI spicy://. Ссылка на результат живёт недолго, а файл хранится около 14 дней, поэтому прочитайте о хранении и доставке, прежде чем строить на этом. Задача в состоянии succeeded означает лишь, что сервис закончил работу; отметьте клип как доставленный после того, как пройдут проверки ниже.

Или пусть это выполнит агент

Когда увеличение должен запустить ассистент, все три официальных инструмента показывают цену и спрашивают разрешения перед платным вызовом.

• CLI. Поместите {"video_url": "https://example.com/approved-product-ad.mp4", "resolution": "1080p"} в input.json, затем:

``bash spicyapi tasks create --model spicyapi/video-upscaler-v1/upscale --input-file input.json --wait ``

Смотрите документацию по CLI; npx @spicyapi/cli работает без установки.

• MCP-сервер. Добавьте MCP-сервер, а затем спросите: «Upscale approved-source.mp4 to 1080p with Video Upscaler.» Он загружает файл через spicyapi_upload_file, вызывает spicyapi_task_create, который останавливается для подтверждения цены, а затем spicyapi_task_wait.
• Skill. npx skills add spicyapi-ai/spicy-skill устанавливает Agent Skill, благодаря которому кодовый ассистент читает актуальную схему модели, а не угадывает поля.

Проверьте результат по исходнику

Запустите один и тот же зонд на обоих файлах и сравните. Это короткий скрипт, печатающий по одной строке на клип:

probe() {
  ffprobe -v error -of json \
    -show_entries format=duration,size:stream=codec_type,codec_name,width,height,avg_frame_rate,sample_rate,channels,duration "$1" |
  jq -c '{size_bytes: (.format.size|tonumber), duration: (.format.duration|tonumber),
    video: (.streams|map(select(.codec_type=="video"))[0]|{codec:.codec_name,w:.width,h:.height,fps:.avg_frame_rate}),
    audio: (.streams|map(select(.codec_type=="audio"))[0]|if .==null then null else {codec:.codec_name,rate:.sample_rate,ch:.channels} end)}'
}
probe approved-source.mp4
probe returned.mp4

Что нужно подтвердить:

1. Размер и форма. Соотношение сторон совпадает с исходником, а размеры соответствуют тому, что должен дать уровень. Запишите реальную ширину и высоту; не переписывайте их из названия уровня.
2. Длительность. Длительность совпадает с исходником. Если площадка зависит от точных точек склейки, проверьте первый и последний кадр, а не только округлённое число.
3. Звук. Возвращённый файл содержит звуковой поток с тем же числом каналов и той же длительностью, что и исходник. Сам факт существования потока не доказывает его правильность, поэтому проиграйте оба файла в одних и тех же точках: первое произнесённое слово, склейка, последняя фраза. Если исходник был беззвучным намеренно, результат тоже должен быть.
4. Картинка в движении. Просмотрите весь клип на обычной скорости, прежде чем разглядывать неподвижные кадры. Мерцание, переливающаяся текстура и ореолы вокруг движущихся краёв видны при воспроизведении и почти не видны в стоп-кадре.
5. Детали, несущие смысл. Этикетки товара, логотипы, текст и лица — это места, где апскейлер способен выдумать правдоподобную деталь вместо восстановления настоящей. Сравните их с исходником при том же кадрировании. Изменённая марка проваливает клип, как бы чётко он ни выглядел.

Чтобы сравнить один момент рядом, увеличив исходник до размера результата методом ближайшего соседа, чтобы увидеть его настоящие пиксели:

ffmpeg -ss 2.0 -i returned.mp4 -ss 2.0 -i approved-source.mp4 \
  -filter_complex "[1:v]scale=1896:1094:flags=neighbor[s];[s][0:v]hstack" \
  -frames:v 1 compare-at-2s.png

Задайте масштаб по возвращённой ширине и высоте.

Экспортируйте точный файл поставки

Когда площадке нужно фиксированное полотно, завершите локальным экспортом. Пример предполагает примерно вертикальный исходник, такой как 2:3; горизонтальная картинка, увеличенная и дополненная до 1080x1920, оставляет узкую полосу изображения. Дополнение сохраняет весь кадр; кадрирование заполняет полотно, но срезает края, поэтому после любого из двух вариантов посмотрите на товар.

ffmpeg -i accepted-upscale.mp4 \
  -vf "scale=1080:1920:force_original_aspect_ratio=decrease,pad=1080:1920:(ow-iw)/2:(oh-ih)/2" \
  -c:v libx264 -pix_fmt yuv420p -crf 18 \
  -c:a aac -b:a 192k delivery-vertical.mp4

Это перекодирует звук. Если исходную дорожку нужно оставить нетронутой, используйте -c:a copy, когда площадка это принимает, а затем снова запустите зонд на экспортированном файле. Субтитры и графику запекайте после увеличения, чтобы края букв рисовались в итоговом размере, а не увеличивались.

Храните три файла: утверждённый исходник, нетронутый результат увеличения и каждый экспорт. Тогда последующее кадрирование или повторный экспорт никогда не будет стоить второго увеличения.

Когда что-то пошло не так

Чините тот этап, который дал сбой, вместо повторного увеличения.

Пилот перед пакетом

Пропустите один клип с настоящим движением и звуковой дорожкой по всему пути: зонд, увеличение, загрузка, сравнение, экспорт, а затем проиграйте итоговый файл на реальной площадке (в ленте, в плеере, на большом экране). Локальные плееры и платформы декодируют и пережимают по-разному, поэтому именно площадка покажет, выдержит ли результат. Для пакета возьмите быстрый панорамный сдвиг, рекламу с большим числом склеек и клип с мелкой текстурой, а для каждого клипа запишите длительность исходника, оплаченные секунды, уровень, итоговое списание и причину любого отклонения.

Если вы выбираете между уровнями, держите клип постоянным и сравните 1080p с 4K в том размере, в котором его будут смотреть. Если 1080p уже удовлетворяет требованиям площадки, дополнительные $0.018 в секунду не покупают ничего видимого.

Решение

Считайте возвращённый файл мастером, который нужно проверить, а не готовой поставкой. Вызов стоит несколько центов; избежимые расходы — это повторный монтаж в более высоком разрешении, увеличение клипа, который уже был достаточно большим, и отправка файла, у которого изменился звук или этикетка товара. Откройте страницу модели Video Upscaler, чтобы попробовать клип.