Руководство
muse-video-1.0 API генерации видео из изображения: руководство по curl и Python Requests
На этой странице
Какие требования предъявляет эндпоинт генерации видео из изображения muse-video-1.0
Эндпоинт muse-video-1.0/image-to-video преобразует одно статичное изображение в короткий видеоролик. Понимание структуры запроса до написания первой строки кода поможет вам собрать правильный запрос с первого раза.
На высоком уровне вызов включает четыре аспекта:
- Маршрутизация модели — вы указываете модель как
muse-video-1.0/image-to-videoчерез единый API HiAPI. - Входное изображение — статичный кадр, служащий отправной точкой анимации. Это обязательный творческий входной параметр.
- Параметры генерации — поведение аудио и уровень длительности, которые формируют характеристики вывода, а не исходный материал.
- Асинхронное выполнение — генерация не возвращает готовое видео сразу. Сначала вы отправляете задачу, затем опрашиваете результат.
Последний пункт разработчики упускают чаще всего. Поскольку рендеринг требует времени, эндпоинт работает на основе механизма задач: первоначальный вызов подтверждает ваш запрос и возвращает дескриптор, после чего вы следите за статусом до готовности видео. Проектируйте клиент вокруг этого двухэтапного процесса с самого начала, а не добавляйте опрос постфактум.
Тело запроса — это JSON. Поля сгруппированы: изображение находится в отдельном блоке input, а аудио и длительность располагаются рядом с ним как настройки генерации. Держите в голове эту ментальную модель — разделение входа, параметров и жизненного цикла задачи — и остальная часть руководства будет простой.
Аутентификация
Каждый запрос аутентифицируется вашим API-ключом HiAPI в виде bearer-учетных данных в заголовке Authorization. Относитесь к ключу как к секрету: загружайте его из переменной окружения, а не встраивайте в скрипт, которым можете поделиться.
export HIAPI_API_KEY="your_api_key_here"
После экспорта ключа у вас есть всё необходимое для понимания запроса. В следующих разделах мы шаг за шагом соберем тело запроса.
Подготовка и загрузка первого кадра
Первый кадр — творческий якорь всей задачи. То, что вы предоставите, станет нулевым кадром, от которого модель начнет анимацию. Правильная подготовка позволит избежать трат на лишние генерации.
Практические рекомендации для исходного кадра
- Используйте четкое, качественное статичное изображение. То, что хорошо читается как отдельный кадр, дает модели наилучшую отправную точку.
- Выбирайте соотношение сторон, соответствующее целевому выводу. Широкий горизонтальный кадр и вертикальный кадр приведут к совершенно разной композиции, поэтому ориентацию следует определить еще до фактической загрузки.
- Избегайте сильного смаза движения или неясного субъекта. Визуально стабильное статичное изображение приводит к более предсказуемой анимации.
- Убедитесь, что файл доступен во время запроса. Независимо от того, передаете ли вы URL или закодированные данные, ссылка должна быть достижима в момент отправки задачи.
Как изображение попадает в запрос
Изображение передается в блоке input JSON-тела запроса. Минимальный ввод изображения выглядит так:
{
"input": {
"image": "https://your-host.example/first-frame.jpg"
}
}
Если исходное изображение хранится локально, разместите его в месте, доступном для запроса, или передайте в закодированном виде, который принимает эндпоинт. Ключевое правило: значение в input.image должно разрешаться в реальное содержимое изображения при создании задачи — поврежденная или устаревшая ссылка приведет к ошибке при отправке, а не при опросе, что на самом деле является полезным ранним сигналом.
Проверка перед генерацией
Быстрая проверка на здравый смысл ценна: откройте URL изображения в браузере, убедитесь, что оно загружается, затем проверьте, что размеры подходят для вашего ожидаемого вывода. Две секунды проверки здесь избавят от запутанной отладки позже.
Когда первый кадр готов и доступен, можно переходить к параметрам генерации.
Настройка параметров аудио и уровня длительности
Помимо изображения, muse-video-1.0/image-to-video предоставляет два типа параметров, изменяющих характеристики вывода: поведение аудио и длительность.
Параметр аудио
Аудио представлено полем в теле запроса рядом с вашим input. Определите намерение перед вызовом:
- Беззвучный вывод — если вы планируете добавить собственное музыкальное сопровождение на этапе постобработки или вам нужна чистая видеодорожка, оставьте аудио выключенным.
- Включить аудио — если клип должен иметь собственный звук, включите аудио. Явно проверяйте эту опцию в теле запроса, а не полагайтесь на значение по умолчанию.
Поскольку обработка аудио является свойством самого запроса, а не этапом постобработки, стоит определиться с этим до масштабирования. Если ваш конвейер смешивает беззвучные и озвученные клипы, моделируйте этот выбор как явный параметр в вашем клиентском коде, чтобы избежать случайностей.
Уровень длительности
Эндпоинт позволяет выбрать уровень длительности для клипа. Рассматривайте длительность как осознанное творческое и стоимостное решение:
- Более короткий уровень подходит для быстрых превью, социальных клипов и тестирования раскадровок, когда вы хотите быстро получить обратную связь по множеству исходных изображений.
- Более длинный уровень дает анимации больше пространства для развития и лучше подходит для ключевых кадров или сцен, которым нужно дыхание.
Длительность оплачивается по выходным секундам, поэтому выбранный уровень напрямую влияет на расходы. Нет смысла рендерить длинный клип только для быстрой визуальной проверки — используйте короткий уровень при итерации по первому кадру, а затем повышайте выигрышные настройки до более длинного уровня.
Сборка параметров вместе
В JSON настройки аудио и длительности располагаются рядом с блоком input:
{
"input": {
"image": "https://your-host.example/first-frame.jpg"
},
"audio": true,
"duration": "<duration_tier>"
}
Используйте точные идентификаторы уровней из документации эндпоинта, а не угадывайте значения. В следующем разделе это превратится в работающий запрос.
Рабочий запрос curl
Когда тело запроса собрано, вот команда curl для первоначальной отправки. Она создает задачу; готовое видео она не возвращает.
curl -X POST "https://api.hiapi.ai/v1/muse-video-1.0/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"input": {
"image": "https://your-host.example/first-frame.jpg"
},
"audio": true,
"duration": "<duration_tier>"
}'
Несколько замечаний по команде:
- URL задает модель по имени. Вам не нужен отдельный клиент для каждой модели; путь уже идентифицирует
muse-video-1.0/image-to-video. - Заголовок несет ваш ключ.
$HIAPI_API_KEYраскрывается из переменной окружения, которую вы экспортировали ранее, поэтому ключ никогда не появляется в самом скрипте. - Тело — это только что собранный вами запрос. URL изображения, флаг аудио и уровень длительности передаются вместе.
Ответ — это подтверждение задачи: он содержит идентификатор только что созданной задачи. Скопируйте этот идентификатор — он понадобится на этапе опроса. Если вы только изучаете API, обработайте ответ инструментом форматирования JSON, чтобы легче найти job ID.
Если отправка не удалась, ошибка обычно немедленная и конкретная: некорректное JSON-тело запроса, отсутствующая ссылка на изображение или нераспознанное значение параметра. Этот быстрый цикл обратной связи — именно то, ради чего стоит протестировать отправку отдельно, прежде чем подключать опрос.
Тот же запрос на Python
Большинство интеграций в конечном итоге оказываются на Python, поэтому вот эквивалентная отправка с использованием стандартной библиотеки — без сторонних SDK.
import json
import os
import urllib.request
API_KEY = os.environ["HIAPI_API_KEY"]
ENDPOINT = "https://api.hiapi.ai/v1/muse-video-1.0/image-to-video"
payload = {
"input": {
"image": "https://your-host.example/first-frame.jpg"
},
"audio": True,
"duration": "<duration_tier>",
}
request = urllib.request.Request(
ENDPOINT,
data=json.dumps(payload).encode("utf-8"),
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
method="POST",
)
with urllib.request.urlopen(request) as response:
result = json.loads(response.read().decode("utf-8"))
job_id = result["id"]
print("Submitted job:", job_id)
Этот скрипт поле за полем соответствует вызову curl. Несколько привычек, которые стоит выработать:
- Храните тело запроса в словаре. Построение в виде словаря Python означает, что вы можете передать ту же структуру в любую HTTP-библиотеку —
urllib,requestsили асинхронный клиент — без переписывания логики. - Читайте ключ из окружения.
os.environдержит учетные данные вне системы контроля версий. - Сразу разбирайте ответ как JSON. Извлечение job ID в именованную переменную делает шаг опроса более читаемым.
Если вы предпочитаете библиотеку requests, единственное изменение — замена транспортного уровня: постройте тот же словарь payload и отправьте его с вашим набором заголовков, затем вызовите .json() для ответа. Эндпоинт, заголовки и тело запроса остаются полностью идентичными.
После отправки задачи и сохранения ее идентификатора остается только правильно дождаться результата.
Опрос асинхронной задачи и получение видео
Генерация видео не мгновенная, поэтому эндпоинт асинхронный. После отправки вы опрашиваете статус задачи, чтобы узнать, когда рендеринг завершен, а затем получаете вывод.
Цикл опроса
Надежный цикл делает три вещи: ждет между проверками, устанавливает верхний предел, чтобы не работать бесконечно, и различает «все еще обрабатывается», «завершено» и «ошибка».
import time
import urllib.request
STATUS_ENDPOINT = "https://api.hiapi.ai/v1/jobs/{job_id}"
def wait_for_video(job_id, max_attempts=60, interval=5):
for attempt in range(max_attempts):
url = STATUS_ENDPOINT.format(job_id=job_id)
request = urllib.request.Request(
url,
headers={"Authorization": f"Bearer {API_KEY}"},
)
with urllib.request.urlopen(request) as response:
status = json.loads(response.read().decode("utf-8"))
state = status.get("status")
if state == "succeeded":
return status.get("output")
if state == "failed":
raise RuntimeError(f"Job {job_id} failed: {status}")
time.sleep(interval)
raise TimeoutError(f"Job {job_id} did not finish in time")
Ключевые моменты для продакшена
- Используйте разумный интервал. Пять секунд — разумная отправная точка; не бомбардируйте эндпоинт статуса.
- Всегда ограничивайте число попыток. Верхний предел
max_attemptsпревращает бесконечное ожидание в четкую ошибку, которую можно логировать и по которой можно настраивать оповещения. - Явно обрабатывайте состояния ошибки. Неудачные задачи содержат диагностическую информацию — выводите ее, а не молча повторяйте тот же ввод.
- Сохраняйте job ID. Если ваш процесс перезапустится, вы сможете возобновить опрос, не оплачивая повторную генерацию.
Получение вывода
При успешном завершении задачи ответ со статусом содержит ссылку на вывод готового видео. Своевременно скачайте его в ваше собственное хранилище, а не полагайтесь на долгоживущие ссылки. Как только у вас есть файл локально или в бакете, с точки зрения конвейера генерация завершена.
Вот и весь жизненный цикл: отправка, опрос, получение. Разделите эти два этапа в коде, и каждый из них останется простым.
Распространенные ловушки и советы по отладке
Большинство проблем интеграции с muse-video-1.0/image-to-video можно отнести к нескольким категориям. Вот что следует проверить при возникновении проблем.
Проблемы с входным изображением
- Ссылка на изображение недоступна. Если URL требует аутентификации или истек, задача завершится ошибкой при отправке. Разместите кадр в месте, публично доступном на время запроса.
- Несоответствие соотношения сторон. Принудительное использование вертикального статичного изображения для горизонтального вывода приведет к неудобной обрезке или черным полосам. Установите ориентацию источника в соответствии с целью.
- Неверное содержимое. Легко указать на эскиз или заглушку вместо настоящего кадра. Проверьте, что URL открывает ожидаемое изображение.
Ошибки параметров
- Угадывание значения длительности. Используйте точные идентификаторы уровней, указанные в документации эндпоинта. Нераспознанные значения — частая причина отказа.
- Забытый флаг аудио. Если вы опускаете настройку аудио, но ожидаете звук, вы можете получить беззвучный клип. Явно указывайте, нужен ли аудио.
- Путаница полей верхнего уровня и полей input. Изображение находится внутри
input; аудио и длительность — соседние узлыinput, а не его потомки. Неправильная вложенность приводит к запутанным сообщениям валидации.
Ошибки опроса
- Принятие отправки за завершение. Первый ответ — это только подтверждение, а не видео. Всегда выполняйте проверку статуса.
- Неограниченный опрос. Цикл без верхнего предела подвесит ваш worker при зависании задачи. Добавьте верхний предел и ошибку таймаута.
- Игнорирование ошибок. Задача, завершившаяся со статусом ошибки, никогда не выдаст видео; перехватите ее и изучите диагностику, а не продолжайте ждать.
- Долгое ожидание при неверном вводе. Когда рендеринг продолжает завершаться ошибкой, прекратите повторную генерацию. Сначала исправьте исходный кадр или параметры, затем отправьте заново.
Эффективный порядок отладки
- Убедитесь, что URL изображения загружается в браузере.
- Отправьте минимальный запрос только с изображением, чтобы изолировать проблемы параметров.
- Проверьте, что job ID возвращается корректно.
- Сначала опросите вручную, наблюдая за переходами статуса.
- Только после этого автоматизируйте цикл, добавив повторные попытки для временных сетевых ошибок.
Последовательное выполнение этих шагов быстро сузит проблему до определенного уровня — изображения, параметров или жизненного цикла — и сохранит продвижение интеграции. Поняв структуру запроса, параметры и процесс опроса, вы готовы создавать решение для этого эндпоинта.
Похожие статьи
Все статьи →-
Руководство
Практическое руководство по gpt-6.2-sol: 5 ценных способов применения текстовой модели в бизнесе
-
Руководство
Практическое руководство по gpt-6.2-astra: интеграция и ключевые моменты реализации для 5 ценных текстовых сценариев
Чек-лист для разработчиков: от выбора сценариев до внедрения в инженерию
-
Руководство
Практические сценарии Tripo H3.1: 5 высокоценных применений и ключевые моменты реализации
От text-to-3D до multiview-восстановления: выбирайте правильный режим и параметры под бизнес-сценарий