English Arabic Français Deutsch 日本語 한국어 Português Русский Español

Hunyuan Video Fast API: краткое руководство по началу работы на Novita AI

Автор / / Video, API / 5 минут чтения
Hunyuan Video Fast API: краткое руководство по началу работы на Novita AI
Содержание
  1. Когда использовать Hunyuan Video Fast вместо стандартной версии
  2. Шаг 1: Получите API-ключ Novita AI
  3. Шаг 2: Endpoint и идентификатор модели
  4. Шаг 3: Отправьте первый запрос
  5. Шаг 4: Опрашивайте API для получения результата видео
  6. Пример на Python
  7. Пример с cURL
  8. Ключевые параметры
  9. Цены и лимиты
  10. Устранение неполадок
  11. Часто задаваемые вопросы
  12. Рекомендуемые статьи

Hunyuan Video Fast доступен на Novita AI по адресу POST https://api.novita.ai/v3/async/hunyuan-video-fast. Это оптимизированная по скорости версия открытой базовой модели Hunyuan Video от Tencent — она сокращает время генерации по сравнению со стандартной версией ценой некоторой точности движений, что делает её практичной для конвейеров с высокой пропускной способностью, итераций по промптам и промежуточных рабочих процессов, где скорость выполнения важнее пикового кинематографического качества.

Как и все асинхронные видео API Novita, он возвращает task_id при отправке и предоставляет URL видео после завершения задачи. В этом руководстве рассматриваются endpoint, формат запроса, рабочие примеры на Python и cURL, а также сценарии применения быстрой версии по сравнению со стандартной моделью.

Когда использовать Hunyuan Video Fast вместо стандартной версии

Быстрая версия — правильный выбор, когда время генерации и объём запросов важнее пикового визуального качества. Стандартная версия Hunyuan Video обеспечивает более точное движение и лучшее следование промпту при каждой генерации. Быстрая версия значительно сокращает это время — это полезно для:

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

Если основным ограничением является качество вывода — эфирное вещание, финальная доставка или фотореалистичное движение — используйте вместо этого стандартный endpoint Hunyuan Video.

Шаг 1: Получите API-ключ Novita AI

Зарегистрируйтесь на novita.ai и создайте API-ключ на странице управления ключами. Новые аккаунты получают бесплатные кредиты. Храните ключ в переменной окружения — никогда не встраивайте его в исходный код.

export NOVITA_API_KEY="your_api_key_here"

Шаг 2: Endpoint и идентификатор модели

Поле Значение
Endpoint отправки POST https://api.novita.ai/v3/async/hunyuan-video-fast
Получение результата GET https://api.novita.ai/v3/async/task-result?task_id=<id>
Заголовок авторизации Authorization: Bearer $NOVITA_API_KEY
Content-Type application/json

Официальная документация API: novita.ai/docs/api-reference/model-apis-hunyuan-video-fast

Шаг 3: Отправьте первый запрос

Отправьте запрос на генерацию с вашим промптом и настройками вывода:

curl -s -X POST https://api.novita.ai/v3/async/hunyuan-video-fast \
  -H "Authorization: Bearer $NOVITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A red fox running through a snowy forest at dawn, slow motion, cinematic wide shot",
    "negative_prompt": "blurry, low quality, distorted, watermark",
    "width": 1280,
    "height": 720,
    "seed": -1
  }'

API сразу возвращает task_id:

{
  "task_id": "hunyuan-fast-abc123"
}

Видео отсутствует в этом ответе — сохраните task_id и используйте его на следующем шаге.

Шаг 4: Опрашивайте API для получения результата видео

curl -s "https://api.novita.ai/v3/async/task-result?task_id=hunyuan-fast-abc123" \
  -H "Authorization: Bearer $NOVITA_API_KEY"

Продолжайте опрос, пока task_status не станет TASK_STATUS_SUCCEED:

{
  "task_status": "TASK_STATUS_SUCCEED",
  "videos": [
    {
      "video_url": "https://cdn.novitai.com/output/...",
      "video_url_ttl": 3600,
      "video_type": "mp4"
    }
  ]
}

Скачайте или сохраните video_url своевременно — он истекает через video_url_ttl секунд.

Значения статусов задачи

Статус Значение
TASK_STATUS_QUEUED Запрос принят, ожидает выполнения
TASK_STATUS_PROCESSING Генерация выполняется
TASK_STATUS_SUCCEED Завершено — URL видео доступен в videos[0].video_url
TASK_STATUS_FAILED Сбой генерации — проверьте ответ на наличие причины сбоя

Пример на Python

import os
import time
import requests

API_KEY = os.environ["NOVITA_API_KEY"]
BASE_URL = "https://api.novita.ai"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}


def submit_video(
    prompt: str,
    negative_prompt: str = "",
    width: int = 1280,
    height: int = 720,
    seed: int = -1,
) -> str:
    payload = {
        "prompt": prompt,
        "negative_prompt": negative_prompt,
        "width": width,
        "height": height,
        "seed": seed,
    }
    resp = requests.post(
        f"{BASE_URL}/v3/async/hunyuan-video-fast",
        headers=HEADERS,
        json=payload,
    )
    resp.raise_for_status()
    return resp.json()["task_id"]


def poll_result(task_id: str, interval: int = 5, timeout: int = 300) -> dict:
    deadline = time.time() + timeout
    while time.time() < deadline:
        resp = requests.get(
            f"{BASE_URL}/v3/async/task-result",
            headers=HEADERS,
            params={"task_id": task_id},
        )
        resp.raise_for_status()
        data = resp.json()
        status = data.get("task_status", "")
        if status == "TASK_STATUS_SUCCEED":
            return data
        if status == "TASK_STATUS_FAILED":
            raise RuntimeError(f"Task failed: {data}")
        time.sleep(interval)
    raise TimeoutError(f"Task {task_id} did not complete within {timeout}s")


if __name__ == "__main__":
    task_id = submit_video(
        prompt="A red fox running through a snowy forest at dawn, slow motion, cinematic wide shot",
        negative_prompt="blurry, low quality, distorted, watermark",
        width=1280,
        height=720,
    )
    print(f"Task submitted: {task_id}")

    result = poll_result(task_id)
    for video in result.get("videos", []):
        print(f"Video URL (expires in {video['video_url_ttl']}s): {video['video_url']}")

Пример с cURL

# Step 1: Submit the generation request
TASK_ID=$(curl -s -X POST https://api.novita.ai/v3/async/hunyuan-video-fast \
  -H "Authorization: Bearer $NOVITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A timelapse of a city skyline transitioning from dusk to night, cinematic",
    "negative_prompt": "blurry, low quality, distorted",
    "width": 1280,
    "height": 720,
    "seed": 42
  }' | jq -r '.task_id')

echo "Task ID: $TASK_ID"

# Step 2: Poll until complete
while true; do
  RESULT=$(curl -s "https://api.novita.ai/v3/async/task-result?task_id=$TASK_ID" \
    -H "Authorization: Bearer $NOVITA_API_KEY")
  STATUS=$(echo "$RESULT" | jq -r '.task_status')
  if [ "$STATUS" = "TASK_STATUS_SUCCEED" ]; then
    echo "$RESULT" | jq -r '.videos[0].video_url'
    break
  elif [ "$STATUS" = "TASK_STATUS_FAILED" ]; then
    echo "Failed: $RESULT"
    break
  fi
  echo "Status: $STATUS — waiting..."
  sleep 5
done

Ключевые параметры

Параметр Тип Обязательный Описание
prompt string Да Текстовое описание сцены видео, объекта, движения и стиля
negative_prompt string Нет Элементы, которых следует избегать в выводе (например, “blurry, low quality”)
width integer Нет Ширина вывода в пикселях — поддерживаемые значения см. в документации API
height integer Нет Высота вывода в пикселях — используется вместе с width для задания разрешения
seed integer Нет Задайте фиксированное целое число, чтобы воспроизвести тот же результат; -1 для случайного значения

Полный список параметров, включая параметры длительности, ограничения максимального разрешения и любые специфические для модели поля, см. в справочнике API Hunyuan Video Fast.

Цены и лимиты

Актуальные цены за видео смотрите на странице моделей Novita AI. Цены на генерацию видео обычно устанавливаются за клип и зависят от разрешения и длительности. Проверяйте страницу с ценами перед построением модели затрат для производственных нагрузок.

Перед развертыванием подтвердите следующие лимиты в официальной документации:

  • Максимальная длина промпта в символах
  • Поддерживаемые значения разрешения (комбинации ширины и высоты)
  • Максимальная длительность видео в секундах
  • Лимиты запросов и максимальное количество одновременных задач на один API-ключ

Быстрая версия обычно стоит меньше за клип, чем стандартная модель, благодаря сокращённому времени вычислений — проверяйте актуальную разницу на странице цен Novita.

Устранение неполадок

401 Unauthorized — API-ключ отсутствует, недействителен или истёк. Убедитесь, что NOVITA_API_KEY задан и ключ активен в вашей панели управления Novita AI.

422 Unprocessable Entity — Отсутствует обязательный параметр или значение вне допустимого диапазона. Убедитесь, что prompt не пуст, а значения width/height входят в поддерживаемый набор из документации API.

Задача остаётся в статусе TASK_STATUS_PROCESSING — Генерация всё ещё выполняется. Быстрая версия завершается быстрее стандартной, но более высокие разрешения и большая длительность требуют больше времени. Увеличьте таймаут опроса для больших выходных данных.

video_url возвращает 403 или 404 — Срок действия URL истёк (прошёл video_url_ttl). В производстве скачивайте или переносите видео сразу после TASK_STATUS_SUCCEED — не полагайтесь на размещённый URL как на постоянное хранилище.

Постоянные проблемы с качеством для определённых типов промптов — Перейдите к подходу уточнения prompt: явно описывайте объект, действие, ракурс камеры и стиль. Добавляйте элементы в negative_prompt для распространённых артефактов. Если качество по-прежнему недостаточно для вашего сценария, оцените стандартный endpoint Hunyuan Video.

Часто задаваемые вопросы

Какой endpoint Novita AI используется для Hunyuan Video Fast?

POST https://api.novita.ai/v3/async/hunyuan-video-fast. API работает асинхронно: отправьте запрос, получите task_id, затем опрашивайте GET https://api.novita.ai/v3/async/task-result?task_id=<id>, пока task_status не станет TASK_STATUS_SUCCEED.

Чем Hunyuan Video Fast отличается от стандартной версии Hunyuan Video?

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

Можно ли задать конкретную длительность видео?

Проверьте справочник API на наличие поддерживаемых параметров длительности. Некоторые видео API Novita предоставляют явное поле duration; другие используют значение по умолчанию модели. Уточняйте, прежде чем полагаться на стандартную длину клипа.

Как воспроизвести конкретный результат видео?

Установите seed в фиксированное целое число. Одна и та же комбинация seed, prompt, width и height должна давать согласованный результат при разных запусках.

Поддерживает ли Hunyuan Video Fast преобразование изображения в видео?

Hunyuan Video Fast на Novita AI — это модель преобразования текста в видео. Для генерации изображения в видео на Novita ознакомьтесь с доступными моделями I2V, такими как Kling, Vidu или Wan, на странице моделей Novita.

Сколько стоит Hunyuan Video Fast на Novita AI?

Актуальные цены смотрите на novita.ai/models. Цены за клип для видеомоделей могут меняться; всегда проверяйте страницу с ценами перед составлением производственных смет.

Подходит ли Hunyuan Video Fast для производственных видеоконвейеров?

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

Рекомендуемые статьи

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