HiAPI
Блог

Руководство

Как использовать topaz-upscale/video через API HiAPI: примеры на curl и Python

Nov 17, 2026
Обложка: несколько полупрозрачных стеклянных пластинок пересекаются под сдержанным углом, преломляя на светлом фоне холодно-синие параллельные цветовые полосы; текста на изображении нет.
На этой странице

Что делает topaz-upscale/video и когда его использовать

topaz-upscale/video — это эндпоинт улучшения видео на HiAPI. Вы отправляете исходное видео и инструкции, а он возвращает улучшенное видео: более высокое разрешение, восстановленные мелкие детали и, опционально, более плавное движение за счёт интерполяции кадров. Используйте этот эндпоинт, когда материал уже существует, а проблема заключается в качестве, а не в генерации контента.

Сценарии применения

Типичные задачи, естественно подходящие для этого эндпоинта:

  • Архивные и старые материалы — старая видеозапись, сжатая запись экрана или унаследованные медиа, которые должны выглядеть достойно в современном разрешении.
  • Конвейеры рендеринга — готовые последовательности, отрендеренные в низком разрешении для скорости, затем улучшенные для сдачи.
  • Сглаживание движения — источник с низкой частотой кадров требует интерполированных кадров, чтобы избежать рывков при воспроизведении.
  • Варианты поставки — один мастер-файл, несколько уровней качества вывода, улучшение применяется к каждому уровню отдельно.

Когда выбирать его вместо альтернатив

Решение обычно сводится к трём вопросам:

  1. Проблема в разрешении и деталях или в содержимом? Если вам нужно придумать новые пиксели (сцену, которую никогда не снимали), это неподходящий инструмент. Улучшение предполагает наличие реальных исходных кадров.
  2. Может ли ваш конвейер допустить асинхронную работу? Видеозадачи не мгновенны. Если ваш пользовательский опыт требует субсекундного отклика, этот эндпоинт должен работать в фоновой задаче, а не в обработчике запросов.
  3. Нужны ли вам интерполяция кадров и увеличение разрешения? Если важна плавность движения, вы хотите получить обе возможности за одну обработку, а не связывать несколько отдельных инструментов. topaz-upscale/video покрывает и то, и другое.

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

Подготовка запроса перед первым вызовом

Большинство неудач при первом вызове связаны с недостающими звеньями, а не с плохими промптами. Подготовьте их до написания кода.

Аккаунт и учётные данные

Вам нужен ключ API HiAPI с доступом к topaz-upscale/video. Храните ключ в переменной окружения, а не в исходном коде — каждый пример ниже читает HIAPI_API_KEY из окружения.

export HIAPI_API_KEY="your-key-here"

Доступный исходный медиафайл

Модель должна иметь возможность получить ваш входной файл. Два надёжных подхода:

  • Публичный или подписанный URL — URL, который сервис может скачать без интерактивной аутентификации. Если ваше хранилище требует подписанные ссылки, создайте ссылку с достаточным сроком действия и не забывайте перегенерировать её при повторных попытках, иначе длинная задача завершится ошибкой на полпути.
  • Сначала загрузить — отправьте файл через механизм загрузки платформы и используйте возвращённый идентификатор. Это более безопасный вариант для больших файлов и всего, что находится за частной сетью.

Характеристики источника, которые стоит проверить

Перед тем как потратить вызов, убедитесь в следующем:

  • Длительность. Длинное видео означает длинную задачу. Если вы тестируете, возьмите 5–10-секундный фрагмент из середины источника — середина обычно более показательна, чем начальные кадры.
  • Кодек и контейнер. Редкие кодеки иногда не декодируются. Если сомневаетесь, переупакуйте в распространённый контейнер.
  • Частота кадров. Запишите точно; она понадобится при интерполяции кадров.
  • Разрешение. Запишите точные размеры источника, чтобы ваше сравнение «до и после» было честным.

Определите цель вывода

Решите насчёт выходного разрешения и частоты кадров до первого вызова, а не после. Разумные настройки улучшения для источника 720p при переходе на 1080p отличаются от настроек для источника 480p при переходе на 4K. Запишите цель; вы будете повторно использовать её в каждом последующем запросе.

Выполнение вызова с помощью curl

Запрос — это POST с JSON-телом на эндпоинт topaz-upscale/video. Ниже приведён полный рабочий пример — замените URL медиафайла на свой.

curl -sS https://api.hiapi.ai/v1/video/enhance \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "topaz-upscale/video",
    "input": {
      "video": "https://your-bucket.example.com/clips/source_720p.mp4"
    },
    "parameters": {
      "target_resolution": "1080p",
      "target_fps": 60,
      "interpolation": "smooth",
      "detail": "balanced"
    },
    "prompt": "Восстановить мелкую текстуру ткани и кожи, сохранить естественное зерно, интерполировать до 60fps без двоения"
  }'

Расшифровка ответа

Немедленный ответ подтверждает задачу. Вы получите идентификатор задачи и поле статуса. Видеоработа асинхронна, поэтому реальная схема такая:

# 1. Отправить и получить id задачи
JOB_ID=$(curl -sS https://api.hiapi.ai/v1/video/enhance \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json | jq -r '.id')

# 2. Опрашивать до терминального статуса
curl -sS "https://api.hiapi.ai/v1/jobs/$JOB_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY" | jq '.status, .output'

При чтении результата важны три поля:

  • status — от постановки в очередь до выполнения и терминального состояния. Любой нераспознанный статус считайте «продолжать ждать», а не успехом.
  • output — присутствует при успехе, содержит URL или идентификатор улучшенного видео.
  • error — присутствует при неудаче. Читайте сообщение буквально; оно обычно указывает на проблемное поле.

Если вы итерируете промпты, поместите тело запроса в файл (request.json) и используйте -d @request.json. Это сохраняет историю shell чистой и позволяет сравнивать разные версии одного и того же запроса.

Вызов того же эндпоинта из Python

Версия на Python — тонкая обёртка над тем же HTTP-контрактом. Используйте requests, храните ключ в окружении, а отправку и цикл опроса оберните в функцию, чтобы вызывающей стороне не нужно было знать об асинхронности.

import os
import time
import requests

BASE = "https://api.hiapi.ai/v1"
HEADERS = {
    "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
    "Content-Type": "application/json",
}

def enhance_video(
    video_url: str,
    prompt: str,
    target_resolution: str = "1080p",
    target_fps: int = 60,
    poll_interval: float = 5.0,
    timeout: float = 1800.0,
) -> str:
    payload = {
        "model": "topaz-upscale/video",
        "input": {"video": video_url},
        "parameters": {
            "target_resolution": target_resolution,
            "target_fps": target_fps,
            "interpolation": "smooth",
            "detail": "balanced",
        },
        "prompt": prompt,
    }

    resp = requests.post(f"{BASE}/video/enhance",
                         headers=HEADERS, json=payload, timeout=60)
    resp.raise_for_status()
    job_id = resp.json()["id"]

    deadline = time.monotonic() + timeout
    while time.monotonic() < deadline:
        r = requests.get(f"{BASE}/jobs/{job_id}", headers=HEADERS, timeout=30)
        r.raise_for_status()
        data = r.json()
        if data["status"] == "succeeded":
            return data["output"]["video"]
        if data["status"] == "failed":
            raise RuntimeError(data.get("error", "Улучшение не удалось"))
        time.sleep(poll_interval)

    raise TimeoutError(f"Задача {job_id} не завершилась за ожидаемое время")

Рекомендации по использованию в реальном конвейере

  • Экспоненциальная задержка при опросе. Фиксированный пятисекундный интервал подходит для shell-скрипта; в продакшене используйте задержку с верхним пределом. Длинные видео могут выполняться долго, и более частый опрос не ускорит их завершение.
  • Идемпотентность. Если вызов отправки завершился тайм-аутом, вы можете не знать, была ли задача запущена. Записывайте тело запроса вместе с id задачи, чтобы сверять дубликаты, а не отправлять повторно вслепую.
  • Сохраняйте id задачи. Записывайте его в базу данных сразу после получения. Если процесс умрёт посреди опроса, вы сможете восстановиться по id, не платя за второе улучшение.

Рецепты промптов для интерполяции кадров

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

Шаблон: описывайте движение, а не математику

Плохо:

interpolate

Лучше:

Интерполировать до плавных 60fps. Сохранить исходный ритм движения — не менять скорость. Панорамирование и движение камеры должны быть линейными и стабильными; избегать искажений по краям кадра.

Вы уже указали целевой FPS в parameters. Промпт должен описывать, как выглядит плавное движение в этом материале.

Шаблон: называйте артефакты, которых нужно избегать

Сгладить 24p до 60fps. Избегать двоения на быстро движущихся руках, избегать шлейфов вокруг тонких объектов, таких как перила и волосы. Статичный фон должен оставаться полностью неподвижным.

Указание конкретных режимов отказа работает гораздо лучше, чем «высокое качество». Модель может сверять свой вывод с конкретными инструкциями.

Шаблон: разделяйте движение и текстуру

В этом проходе сосредоточиться только на плавности движения. Сохранить существующие детали и зерно без изменений — восстановление текстуры обрабатывается отдельно.

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

Шаблон: работа со смешанным движением

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

Интерполировать до 60fps. Камера неподвижна — фон должен быть полностью неподвижным или мерцать. Только голова и руки говорящего должны показывать плавное движение.

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

Рецепты промптов для восстановления деталей

Восстановление деталей — это та половина задачи, которая изобретает правдоподобные мелкие структуры. Режим отказа — галлюцинированные текстуры: кожа выглядит как пластик, растительность превращается в шум, текст становится нечитаемым. Промпт должен задавать границы для изобретения.

Шаблон: привязка к источнику

Восстанавливать детали, согласованные с исходными кадрами. Не изобретать текстуры, которые не подразумеваются исходными пикселями. Там, где детали действительно потеряны, предпочитать мягкий правдоподобный результат, а не зашумлённую резкость.

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

Шаблон: называйте материалы в кадре

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

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

Шаблон: защита текста и графики

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

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

Шаблон: намеренная регулировка резкости

Применять сдержанное восстановление деталей. Цель — естественно выглядящий материал в 1080p, а не перешарпленный стоп-кадр. Лёгкая мягкость допустима; звон и ореолы недопустимы.

Комбинирование обоих

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

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

Сравнение вывода до и после

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

Соберите стандартный набор тестовых фрагментов

Выберите три коротких фрагмента (по 5–10 секунд каждый), которые никогда не меняете:

  1. Простой — хорошее освещение, медленное движение, чистый источник. Должен выглядеть почти идеально; если нет, значит где-то есть ошибка в конфигурации.
  2. Сложный — быстрое движение, мелкие детали или смешанные типы движения. Здесь проявятся артефакты интерполяции.
  3. Состязательный — экранный текст, тонкие структуры или сильное предшествующее сжатие. Здесь проявятся галлюцинации.

Запускайте на всех трёх при каждом изменении промпта или параметров. Изменение, которое помогает на простом фрагменте, но вредит на состязательном, не является улучшением.

Сравнивайте в этом порядке

  • Сравнение бок о бок при 100% масштабе. Не используйте подгонку под окно — артефакты скроются. Проверяйте одинаковые области кадрирования: лица, области текста и зоны быстрого движения.
  • Покадровая прокрутка. Пройдите по кадрам в быстродвижущихся частях в поисках двоения, искажений и мерцания.
  • Воспроизведение в реальном времени. Многие артефакты исчезают при покадровой прокрутке и проявляются в движении, и наоборот. Смотрите оба варианта.
  • Проверка читаемости текста. Прочитайте каждую субтитровую надпись в улучшенной версии, сверяясь с источником. Это самая быстрая объективная проверка «прошёл/не прошёл», доступная вам.

Баланс качества и стоимости

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

Устранение типичных проблем с запросами

Большинство трений при интеграции с topaz-upscale/video сводится к нескольким категориям. Прорабатывайте их по порядку.

Аутентификация и доступ

401 означает, что ключ отсутствует, имеет неверный формат или не отправлен — проверьте, что переменная окружения действительно установлена в оболочке, выполняющей команду, а не только в редакторе. 403 обычно означает, что ключ действителен, но у аккаунта нет доступа к этой модели. Убедитесь, что имя модели написано точно как topaz-upscale/video.

Сервис не может получить ваше видео

Это самая частая ошибка. Симптом: задача быстро завершается ошибкой загрузки или ввода. Причины:

  • URL является приватным или требует интерактивного входа.
  • Подписанный URL истёк до того, как задача дошла до шага загрузки — особенно вероятно в длинных очередях.
  • Хост блокирует автоматические запросы или слишком медленный, что приводит к тайм-ауту.

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

Ошибка декодирования

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

Задача выполняется слишком долго или истекает время ожидания

Длинные источники требуют много времени, а некоторые запросы занимают непропорционально долго. Перед повторной отправкой проверьте статус задачи по id — возможно, вы видите поставленную в очередь задачу, а не сбойную. Слепая повторная отправка может удвоить затраты. Если опрос идёт из скрипта, убедитесь, что тайм-аут вашего клиента больше ожидаемого времени выполнения задачи, иначе вы бросите задачу, которая всё ещё нормально выполняется.

Вывод выглядит хуже исходника

Запрос успешен, но результат перешарплен, пластиковый или с двоением. Это проблема промпта, а не API: вернитесь к рецептам восстановления деталей и интерполяции, добавьте явные ограничения — «согласовано с источником», «без двоения», «фон должен оставаться неподвижным». Затем перезапустите ваш стандартный набор сравнения.

Периодические, невоспроизводимые ошибки

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

Похожие статьи

Все статьи →

Начните работать с постоянными артефактами ИИ

Получите API-ключ и вызывайте модели изображений, видео и аудио через один API на основе tasks.

Читать документацию API