HiAPI
Блог

Руководство

Вызов muse-video-1.0/text-to-video через HiAPI API: руководство по curl и Python

Поля запроса, асинхронный опрос и рабочие примеры запросов

Nov 13, 2026
Абстрактная бруталистская обложка с бетонными плоскостями при скользящем свете, тёплое серое поле, серо-синие тени и тонкий шов цвета шалфея.
На этой странице

Перед отправкой: аутентификация, эндпоинт и идентификатор модели

muse-video-1.0/text-to-video преобразует текстовый промпт в сгенерированный видеоклип. Вы отправляете промпт и несколько управляющих параметров, сервис рендерит клип и возвращает URL или ссылку для скачивания.

Ключевая архитектурная деталь: этот вызов асинхронный. Рендеринг видео занимает много времени, и API не держит ваш HTTP-соединение открытым до готовности файла. Поэтому процесс состоит из двух этапов:

  1. Отправка — вы выполняете POST с промптом и параметрами. Ответ возвращается быстро и содержит идентификатор задачи и начальный статус задачи.
  2. Опрос — вы периодически выполняете GET задачи по идентификатору, пока её статус не станет терминальным (успех или ошибка), после чего получаете результат.

Эта схема «сначала отправка, затем опрос» — главное, что нужно усвоить перед написанием кода. Она меняет структуру приложения: видео не появляется в ответе на запрос отправки, а любые ошибки относятся к определённому этапу — отправке, валидации, рендерингу или получению. Разделение этих этапов в собственном коде (разные функции, отдельное логирование) упростит применение остальной части руководства.

Передаваемая строка модели должна быть точной: muse-video-1.0/text-to-video. Форма vendor/model — общее соглашение для эндпоинтов моделей HiAPI, и именно по ней API определяет, какой генератор вызывать.

Построение запроса: промпт, длительность и поля аудио

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

API-ключ

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

export HIAPI_API_KEY="your_key_here"

Передавайте его в заголовке Authorization: Bearer $HIAPI_API_KEY. Если запрос падает с ошибкой аутентификации, сначала проверьте этот заголовок — опечатка в имени переменной, пробел в конце или не заданное значение в текущей оболочке являются самыми частыми причинами.

Базовый URL

Все вызовы используют один базовый URL платформы HiAPI. Берите актуальное значение из панели аккаунта или API-справочника, не копируйте из старых фрагментов кода; сохраните его в переменной, чтобы менять в одном месте.

Идентификатор модели

Строка модели — muse-video-1.0/text-to-video. Считайте её литералом с учётом регистра. Не составляйте и не угадывайте варианты, например с другим регистром или без суффикса — неизвестный идентификатор модели является ошибкой валидации, а не запасным вариантом.

Когда эти три элемента готовы, можно строить тело запроса.

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

Тело запроса — JSON. По сути оно содержит три группы полей.

Промпт

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

Длительность

Модели текст-в-видео нужно знать, какой длины должен быть клип. Длительность — поле запроса, и она также влияет на стоимость: генерация тарифицируется по количеству выходных секунд. Поскольку допустимый диапазон и значение по умолчанию определяются моделью в конкретный момент времени, читайте точное имя поля и допустимые значения из актуального API-справочника для muse-video-1.0/text-to-video, не угадывайте. Передача длительности вне диапазона приведёт к ошибке валидации.

Аудио

muse-video-1.0/text-to-video помимо визуальной генерации поддерживает управление, связанное с аудио. Это тоже поля запроса — обычно переключатели или входные данные в стиле аудиопромпта — их точные имена и допустимые значения описаны в том же API-справочнике. При первой интеграции консервативный подход — полностью опустить необязательные поля аудио, убедиться, что видео успешно возвращается, и лишь затем добавлять аудиоопции одну за другой.

Таким образом, минимальное тело запроса выглядит примерно так (имена полей приведены только для примера — сверяйтесь со справочником):

{
  "model": "muse-video-1.0/text-to-video",
  "prompt": "На рассвете медленный воздушный проезд камеры над туманным сосновым лесом, мягкий объёмный свет, кинематографично",
  "duration": 5
}

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

Тот же запрос в Python

Вызов отправки — это HTTP POST. Точный путь ресурса определяется API-справочником HiAPI; в примере ниже используется обычный эндпоинт задач, а модель указывается в теле запроса.

curl -sS -X POST "$HIAPI_BASE_URL/v1/video/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "muse-video-1.0/text-to-video",
    "prompt": "Картонный робот идёт по переулку с неоновыми огнями в дождь, отражения на мокром асфальте, фактура 35-мм плёнки",
    "duration": 5
  }'

Ответ небольшой и возвращается быстро. Важны в нём идентификатор задачи и статус. Типичная структура:

{
  "id": "job_abc123",
  "status": "queued"
}

Запишите id — это дескриптор для всех последующих вызовов. status со значением queued или processing — нормальное явление, означающее, что запрос принят, а не что-то пошло не так.

Ручной опрос в оболочке:

curl -sS "$HIAPI_BASE_URL/v1/video/generations/job_abc123" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Запускайте его время от времени несколько раз, наблюдая, как status переходит в терминальное состояние. На практике этот цикл лучше держать в коде, а не в истории терминала.

Обработка асинхронных результатов и опрос без перегрузки API

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

import os
import time
import requests

BASE = os.environ["HIAPI_BASE_URL"]
KEY = os.environ["HIAPI_API_KEY"]
HEADERS = {"Authorization": f"Bearer {KEY}"}

MODEL = "muse-video-1.0/text-to-video"

def submit(prompt: str, duration: int) -> str:
    resp = requests.post(
        f"{BASE}/v1/video/generations",
        headers={**HEADERS, "Content-Type": "application/json"},
        json={"model": MODEL, "prompt": prompt, "duration": duration},
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json()["id"]

def wait_for(job_id: str, max_wait: int = 900) -> dict:
    deadline = time.time() + max_wait
    interval = 5
    while time.time() < deadline:
        r = requests.get(
            f"{BASE}/v1/video/generations/{job_id}",
            headers=HEADERS,
            timeout=30,
        )
        if r.status_code >= 500 or r.status_code == 429:
            time.sleep(interval)
            interval = min(interval * 2, 30)
            continue
        r.raise_for_status()
        job = r.json()
        if job["status"] == "succeeded":
            return job
        if job["status"] == "failed":
            raise RuntimeError(job.get("error") or "generation failed")
        time.sleep(interval)
        interval = min(interval * 1.5, 30)
    raise TimeoutError(f"job {job_id} did not finish in time")

def save(job: dict, path: str) -> None:
    url = job["result"]["video_url"]
    with requests.get(url, stream=True, timeout=120) as r:
        r.raise_for_status()
        with open(path, "wb") as f:
            for chunk in r.iter_content(8192):
                f.write(chunk)

if __name__ == "__main__":
    job_id = submit(
        "На деревянном столе стоит стеклянный миниатюрный террариум, утренний свет, плавающие пылинки, макросъёмка",
        5,
    )
    job = wait_for(job_id)
    save(job, "output.mp4")
    print("saved output.mp4")

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

Распространённые ошибки и способы их диагностики

Частота опроса — реальное проектное решение. Опрос каждые 200 мс создаёт лишь бесполезную нагрузку; опрос раз в пять минут тратит реальное время после завершения рендеринга.

Практическая стратегия:

  • Начните с умеренного интервала (несколько секунд) и постепенно увеличивайте его — умножение на 1,5 при каждом опросе с потолком около полуминуты работает хорошо.
  • Увеличивайте задержку для ответов 429 и 5xx: удвойте интервал и повторите, рассматривая их как сигнал о ёмкости, а не о статусе задачи.
  • Установите максимальное общее время ожидания и выбрасывайте ошибку при его истечении, а не опрашивайте вечно. Рендеринг более длинных клипов действительно занимает больше времени, поэтому верхнюю границу следует задавать исходя из собственной нагрузки.
  • Логируйте переход только при изменении статуса, а не при каждом опросе — шумные логи затрудняют обнаружение настоящих сбоев.

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

Что дальше

Начните с минимального тела запроса, убедитесь в одном успешном сквозном запуске, затем добавьте управление длительностью и аудио согласно актуальной справочной документации для muse-video-1.0/text-to-video. Та же схема «сначала отправка, затем опрос» переносится на другие эндпоинты моделей HiAPI, поэтому написанный здесь клиентский код можно переиспользовать.

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

Все статьи →

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

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

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