Использование Kandinsky 6.0 Pro для преобразования текста в видео на HiAPI: руководство по curl и Python

Что делает запрос kandinsky-6.0-pro/text-to-video

kandinsky-6.0-pro/text-to-video преобразует текстовый промпт в короткий видеоклип. Вы отправляете промпт и несколько параметров генерации, а модель создаёт видеофайл, который можно сохранить и воспроизвести. Это весь продукт: на входе промпт, на выходе видеоклип.

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

У этой схемы есть несколько последствий, которые следует учитывать с самого начала:

• Клиент должен опрашивать статус. Один POST не может вернуть готовое видео, поэтому любая интеграция требует цикла опроса статуса или повторной проверки, подобной webhook.
• Запрос должен быть идемпотентным на вашей стороне. Если скрипт упадёт после отправки, вы не хотите незаметно создать вторую задачу. Захватите идентификатор задачи и сохраните его надёжно.
• Задержка варьируется. Генерация видео медленнее, чем вызовы для изображений или текста, поэтому ожидание — это норма, а не дефект.

Остальная часть руководства следует этому жизненному циклу: подготовка, отправка через curl, опрос, скачивание, а затем воссоздание того же процесса на Python. Рассматривайте код как рабочий каркас — пути эндпоинтов и имена полей всегда следует сверять со справочником API для этой модели, поскольку эти детали меняются по мере развития платформы.

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

Перед первым вызовом нужно подготовить четыре вещи.

1. Учётная запись HiAPI и API-ключ

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

export HIAPI_API_KEY="your-key-here"

Каждый из приведённых ниже запросов предполагает, что ключ отправляется как bearer token в заголовке Authorization. Если вы ещё не создали ключ, сделайте это сначала в панели управления учётной записи.

2. HTTP-клиент

curl достаточно, чтобы проверить, работает ли запрос. Для всего, что нужно выполнять повторно, используйте Python 3 и библиотеку requests — одна зависимость, читаемый код и лёгкость последующего включения в планировщик или сервис:

python3 -m pip install requests

3. Место для сохранения вывода

Видеофайлы намного больше, чем JSON-ответы. Заранее решите, писать ли в локальный каталог или передавать потоком в объектное хранилище. В этом руководстве достаточно локального каталога ./output:

mkdir -p output

4. Продуманный промпт

Напишите промпт до написания кода. Конкретный, описательный промпт — субъект, действие, поведение камеры, визуальный стиль — даёт вам базовую линию для сравнения, когда что-то пойдёт не так. Когда промпт — это именованная константа в скрипте, а не строка, вводимая в приглашении оболочки, гораздо легче менять одну переменную за раз.

Это полный список предварительных условий. Не нужно устанавливать SDK, нет шагов сборки; платформа доступна по обычному HTTPS.

Рабочий запрос curl

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

Запрос состоит из трёх частей: эндпоинт модели, заголовок Authorization и JSON-тело с промптом и параметрами генерации.

curl -X POST "https://api.hiapi.ai/v1/models/kandinsky-6.0-pro/text-to-video/jobs" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A slow drone shot over a misty pine forest at sunrise, soft golden light, cinematic",
    "duration_seconds": 5,
    "aspect_ratio": "16:9"
  }'

Внимательно прочитайте ответ. Вам нужно найти:

• Идентификатор задачи — дескриптор, который вы будете использовать для опроса. Он может называться id, job_id или подобным образом.
• Начальное поле статуса, обычно похожее на queued или processing.
• Любые эхо-параметры, по которым можно убедиться, что тело запроса разобрано так, как вы ожидали.

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

Уточните контракт, прежде чем строить на нём

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

Если вы получили 4xx, тело ответа с ошибкой даёт больше информации, чем код состояния. 401 означает неверный или отсутствующий ключ; ошибки валидации типа 422 обычно указывают на проблемное поле.

Отправка и опрос задачи до завершения

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

Отправка

POST из предыдущего раздела создаёт задачу. Что бы ни делал код дальше, он должен сохранить возвращённый идентификатор в надёжном месте — в переменной скрипта, в строке таблицы задач, в сообщении очереди. Если процесс завершится после получения ответа на отправку, но до сохранения идентификатора, вы потеряете возможность опрашивать эту задачу.

Опрос

Опрос — это GET-запрос к ресурсу задачи с использованием захваченного идентификатора:

curl "https://api.hiapi.ai/v1/models/kandinsky-6.0-pro/text-to-video/jobs/$JOB_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

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

Как долго ждать

Важны два числа: интервал опроса и общий таймаут.

• Интервал. Опрашивайте каждые несколько секунд, не в плотном цикле. Плотный цикл не даёт дополнительных преимуществ и может вызвать ограничение скорости. Для видеозадач разумно делать интервал в несколько секунд между запросами.
• Таймаут. Установите верхний предел. Генерация видео требует времени, но «ждать вечно» — неприемлемый ответ для производственного скрипта. Выберите максимальный реальный бюджет времени и рассматривайте превышение как сбой, который можно залогировать и осознанно повторить.

Схема, выдерживающая реальное использование

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

Скачивание сгенерированного видеоклипа

Завершённая задача — это ещё не файл на вашем диске. Ответ со статусом завершённой задачи указывает на вывод — обычно это URL, иногда вложенный объект, содержащий URL. Прочитайте это поле и используйте его как вход для шага скачивания.

curl -L "$OUTPUT_URL" -o output/clip.mp4

Проверьте следующие моменты, чтобы убедиться, что скачивание действительно удалось:

• Следование перенаправлениям. URL вывода часто отдаются через перенаправления; curl обрабатывает это с -L, Python — с allow_redirects=True.
• Проверка типа содержимого. Завершённая задача должна выдавать видеополезную нагрузку. Если сохранённый как clip.mp4 файл на самом деле является JSON или HTML-страницей ошибки, значит, проблема в скачивании, а не в генерации.
• Проверка размера. Файл нулевого размера или подозрительно маленький файл — это сбой скачивания. Если есть заголовки ответа, сравните количество байт с размером, заявленным в заголовках.
• Учёт истечения срока. URL вывода обычно имеют ограничение по времени. Скачивайте сразу после завершения, а если нужна долговечность, копируйте файл в собственное хранилище, а не сохраняйте URL как постоянную ссылку.

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

Реализация того же запроса на Python

Ниже процесс curl воссоздан как вызываемая функция: отправка, опрос, скачивание. Имена, которые нужно адаптировать, собраны вверху как константы.

import os
import time
import requests

API_BASE = "https://api.hiapi.ai/v1"
MODEL_PATH = "/models/kandinsky-6.0-pro/text-to-video"
API_KEY = os.environ["HIAPI_API_KEY"]

HEADERS = {"Authorization": f"Bearer {API_KEY}"}

RUNNING_STATES = {"queued", "pending", "processing", "running"}
DONE_STATES = {"completed", "succeeded", "done"}
FAILED_STATES = {"failed", "cancelled", "error"}


def generate_clip(prompt, out_path, timeout_s=600, interval_s=5):
    # 1. submit
    resp = requests.post(
        API_BASE + MODEL_PATH + "/jobs",
        headers={**HEADERS, "Content-Type": "application/json"},
        json={"prompt": prompt, "duration_seconds": 5, "aspect_ratio": "16:9"},
        timeout=30,
    )
    resp.raise_for_status()
    job = resp.json()
    job_id = job["id"]
    print(f"submitted job {job_id}")

    # 2. poll
    deadline = time.monotonic() + timeout_s
    while time.monotonic() < deadline:
        status_resp = requests.get(
            f"{API_BASE}{MODEL_PATH}/jobs/{job_id}",
            headers=HEADERS,
            timeout=30,
        )
        status_resp.raise_for_status()
        data = status_resp.json()
        state = str(data.get("status", "")).lower()

        if state in DONE_STATES:
            break
        if state in FAILED_STATES:
            raise RuntimeError(f"job {job_id} ended in state {state}: {data}")
        time.sleep(interval_s)
    else:
        raise TimeoutError(f"job {job_id} did not finish within {timeout_s}s")

    # 3. download
    url = data["output"]["url"] if isinstance(data.get("output"), dict) else data["output"]
    with requests.get(url, stream=True, allow_redirects=True, timeout=60) as r:
        r.raise_for_status()
        tmp = out_path + ".part"
        with open(tmp, "wb") as f:
            for chunk in r.iter_content(chunk_size=1 << 16):
                f.write(chunk)
        os.replace(tmp, out_path)
    print(f"saved {out_path}")
    return job_id


if __name__ == "__main__":
    generate_clip(
        "A slow drone shot over a misty pine forest at sunrise, soft golden light, cinematic",
        "output/clip.mp4",
    )

Почему написано именно так

• Наборы состояний вместо точного совпадения. Сопоставление возвращённых статусов с running/done/failed означает, что новые промежуточные состояния не сломают цикл.
• Монотонный дедлайн. time.monotonic() не подвержен корректировкам часов, поэтому таймаут точен.
• Атомарная запись. Запись в .part с последующим переименованием означает, что прерванное скачивание никогда не оставит усечённый файл, выглядящий допустимым.
• Возврат ID задачи. Вызывающая сторона может записать, сохранить и при необходимости опросить снова — это первый шаг к выносу опроса из этого процесса.

Настройте путь эндпоинта, имена полей запроса и ключи ответа в соответствии со справочником API модели. Всё остальное — цикл, таймауты, скачивание — универсально.

Состояния ошибок и контрольный список отладки

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

Сбой аутентификации

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

Ошибка формата запроса

Ошибки типа 400 или 422 при отправке означают, что тело запроса не прошло валидацию. Тело ответа обычно указывает на поле. Частые причины: опечатка в имени параметра, длительность вне поддерживаемого диапазона или пустой промпт. Сравните ваш JSON с справочником API поле за полем; один переименованный ключ — самая частая причина.

Задача застревает в состоянии выполнения

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

Задача завершена, но скачивание не удалось

Если задача завершена, но скачивание не удалось, это проблема обработки файла, а не генерации. Проверьте, следуют ли перенаправления, не истёк ли URL и является ли тип содержимого видео, а не JSON. Попробуйте URL отдельно с помощью curl -L, чтобы изолировать его от скрипта.

Один и тот же промпт снова и снова не удаётся

Если один промпт постоянно терпит неудачу, а другие успешны, сначала подозревайте политику контента или длину промпта, а не инфраструктуру. Измените одну переменную — сократите промпт, упростите описание сцены — и повторите попытку.

Одно общее правило

Логируйте для каждой задачи четыре вещи: идентификатор задачи, конечное состояние, фактически затраченное время и HTTP-статус скачивания. Эти четыре значения менее чем за минуту превращают большинство отчётов «оно не работает» в конкретный, исправимый этап.