Руководство
Вызов muse-video-1.0/text-to-video через HiAPI API: руководство по curl и Python
Поля запроса, асинхронный опрос и рабочие примеры запросов
На этой странице
Перед отправкой: аутентификация, эндпоинт и идентификатор модели
muse-video-1.0/text-to-video преобразует текстовый промпт в сгенерированный видеоклип. Вы отправляете промпт и несколько управляющих параметров, сервис рендерит клип и возвращает URL или ссылку для скачивания.
Ключевая архитектурная деталь: этот вызов асинхронный. Рендеринг видео занимает много времени, и API не держит ваш HTTP-соединение открытым до готовности файла. Поэтому процесс состоит из двух этапов:
- Отправка — вы выполняете POST с промптом и параметрами. Ответ возвращается быстро и содержит идентификатор задачи и начальный статус задачи.
- Опрос — вы периодически выполняете 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, поэтому написанный здесь клиентский код можно переиспользовать.
Похожие статьи
Все статьи →-
Руководство
Практическое руководство по gpt-6.2-sol: 5 ценных способов применения текстовой модели в бизнесе
-
Руководство
Практическое руководство по gpt-6.2-astra: интеграция и ключевые моменты реализации для 5 ценных текстовых сценариев
Чек-лист для разработчиков: от выбора сценариев до внедрения в инженерию
-
Руководство
Практические сценарии Tripo H3.1: 5 высокоценных применений и ключевые моменты реализации
От text-to-3D до multiview-восстановления: выбирайте правильный режим и параметры под бизнес-сценарий