Руководство
Как вызывать seedance-2.5-flash reference-to-video через HiAPI API (curl + Python)
Рабочие запросы, запускаемый Python-скрипт и обработка опроса асинхронных задач
На этой странице
Что на практике означает reference-to-video
Reference-to-video — это режим генерации, в котором вы даёте модели две вещи одновременно: текстовый промпт, описывающий движение и сцену, и один или несколько референсных материалов, задающих содержимое кадра. Промпт передаёт намерение («медленный наезд, персонаж поворачивается и улыбается»), референсы передают идентичность и внешний вид (персонаж, продукт, визуальный стиль).
Эндпоинт модели для этого рабочего процесса — seedance-2.5-flash/reference-to-video, доступный через единый API HiAPI. Вы отправляете модель, промпт и референсные материалы вместе в одном теле запроса. Нет отдельного шага загрузки, который нужно оркестрировать, и нет реестра по каждому материалу, который нужно поддерживать.
Практическое следствие: это длительная операция. Рендеринг короткого видео всё ещё занимает гораздо больше времени, чем текстовое дополнение, поэтому API рассматривает вызов как асинхронную задачу. Ваш запрос создаёт задачу; второй вызов получает её результат. Эта схема «сначала отправить, потом опрашивать» — самый важный момент при проектировании и то, вокруг чего строится остальная часть этого руководства.
Всё ниже остаётся в рамках интерфейса HiAPI: один базовый URL, один заголовок авторизации, одно семейство эндпоинтов.
Перед отправкой первого запроса
Перед первым вызовом нужно подготовить три вещи.
1. Ключ API
Создайте ключ в консоли HiAPI и держите его вне системы контроля версий. В примерах ниже он читается из переменной окружения:
export HIAPI_API_KEY="your_key_here"
Если вы не уверены в текущем формате ключа или соглашениях о заголовках, посмотрите документацию по API платформы в консоли — не угадывайте и не вшивайте ключ в скрипт, которым можете поделиться.
2. Базовый URL и заголовок авторизации
Все вызовы отправляются на базовый URL HiAPI и несут ваш ключ в заголовке Authorization. Задайте его один раз как переменную, чтобы каждый запрос был согласованным:
export HIAPI_BASE_URL="https://api.hiapi.ai"
Используйте базовый URL точно так, как указано в документации вашей учётной записи — несовпадение завершающего слэша — частая причина непонятных 404.
3. Эндпоинт модели
Ваша цель — seedance-2.5-flash/reference-to-video. Ссылайтесь на него этим идентификатором в теле запроса, а не встраивайте его в путь, чтобы позже смена модели требовала изменения одной строки.
Вам также нужно, чтобы референсные материалы были доступны по URL (или в любой форме материалов, указанной в документации эндпоинта). Разместите их и сделайте общедоступными до начала — битый URL референса — самая частая причина того, что задача успешно отправляется, но падает во время генерации.
Когда эти три вещи настроены, можно собирать тело запроса.
Сборка тела запроса с референсными материалами
У тела запроса есть три концептуальные части: какая модель используется, что вы хотите и на что ссылаетесь.
Модель
Установите model в seedance-2.5-flash/reference-to-video. Относитесь к нему как к обычному строковому полю — без URL-кодирования, без сегмента пути.
Промпт
Пишите промпт как описание кадра, а не как список желаний. Указывайте субъект, действие, поведение камеры и темп. «Человек в красной куртке идёт к камере, средний план, медленный наезд, мягкий дневной свет» даёт модели гораздо больше информации, чем «красивое видео с человеком». Держите промпт в согласии с предоставленными референсами: если два референса показывают разных персонажей, укажите, какой из них главный.
Референсные материалы
Именно референсы отличают этот эндпоинт от обычного вызова text-to-video. Вы передаёте один или несколько материалов, определяющих, что должно оставаться неизменным между кадрами. Практические правила, экономящие итерации:
- Используйте минимальное число референсов, достаточное для определения идентичности. Один сильный референс обычно лучше четырёх посредственных.
- Держите референсы согласованными между собой. Конфликтующие ракурсы или стили приводят к дрейфу результата.
- Предпочитайте чистые, хорошо освещённые исходники. Обрезанные, размытые или сильно отфильтрованные референсы передают эти дефекты дальше.
- Проверьте, что каждый URL разрешается, прежде чем отправлять — скачайте его сами один раз.
Как именно референсы задаются ключами в теле запроса (имя поля массива, структура объекта, поддерживаемые типы материалов), должно следовать из схемы запроса эндпоинта в документации HiAPI. Стройте тело запроса по этой схеме, а не по памяти; схема — авторитетный источник имён полей, а несовпадение ключей приводит к тихому сбою.
Проверьте JSON локально до того, как запрос уйдёт в сеть (python -m json.tool body.json). Неверно сформированное тело — самая легко отлавливаемая ошибка и самая раздражающая при отладке по стеку вызовов.
Рабочий запрос curl
Следующая команда следует схеме «сначала отправить, потом опрашивать»: она создаёт задачу и выводит JSON-ответ, содержащий идентификатор задачи, который вы будете использовать для опроса.
curl -sS -X POST "$HIAPI_BASE_URL/v1/videos/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.5-flash/reference-to-video",
"prompt": "Человек в красной куртке идёт к камере, средний план, медленный наезд, мягкий дневной свет",
"references": [
"https://your-cdn.example.com/refs/character-front.png",
"https://your-cdn.example.com/refs/character-side.png"
]
}'
Замените референсные URL своими размещёнными материалами и, прежде чем полагаться на этот код в продакшене, сверьте путь эндпоинта и имена полей со страницей модели в документации HiAPI — детали схемы авторитетны, а этот фрагмент лишь иллюстративный.
На что обратить внимание в ответе:
- id (или идентификатор task/job) — сохраните его; он нужен при каждом опросе.
- Поле status, показывающее, что задача принята.
- Любые предупреждения о проигнорированных или отклонённых материалах.
Для удобства чтения отформатируйте его:
curl -sS -X POST "$HIAPI_BASE_URL/v1/videos/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @body.json | python -m json.tool
Хранение тела запроса в body.json стоит этого небольшого дополнительного усилия: оно чисто версионируется, читаемо сравнивается в диффах и убирает из отладки ошибки кавычек в shell.
Тот же вызов на Python
Ниже эквивалентный вызов на Python, написанный так, что он запускается сразу после настройки переменных окружения. Он использует только стандартную библиотеку, поэтому ничего устанавливать не нужно.
import json
import os
import urllib.request
BASE_URL = os.environ["HIAPI_BASE_URL"].rstrip("/")
API_KEY = os.environ["HIAPI_API_KEY"]
def submit_reference_video(prompt, references):
body = {
"model": "seedance-2.5-flash/reference-to-video",
"prompt": prompt,
"references": references,
}
req = urllib.request.Request(
f"{BASE_URL}/v1/videos/generations",
data=json.dumps(body).encode("utf-8"),
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
method="POST",
)
with urllib.request.urlopen(req, timeout=60) as resp:
payload = json.loads(resp.read().decode("utf-8"))
return payload
if __name__ == "__main__":
result = submit_reference_video(
prompt="Человек в красной куртке идёт к камере, средний план, медленный наезд, мягкий дневной свет",
references=[
"https://your-cdn.example.com/refs/character-front.png",
"https://your-cdn.example.com/refs/character-side.png",
],
)
print(json.dumps(result, indent=2))
job_id = result.get("id")
print("job id:", job_id)
Две детали важнее, чем кажется. Во-первых, timeout=60 — вызов отправки должен возвращаться быстро, но зависшее соединение хуже быстрого отказа. Во-вторых, result.get("id") обрабатывает случай неожиданной структуры ответа, вместо того чтобы бросать KeyError в вашем нормальном пути.
Если вы предпочитаете requests или httpx, переход прост: тот же URL, те же заголовки, то же JSON-тело. Сборка тела — та часть, которую стоит копировать; HTTP-клиент заменяем.
Опрос асинхронной задачи до завершения
Генерация видео — не тот запрос, который можно подождать. Вы отправляете, получаете идентификатор и затем периодически проверяете статус, пока задача не достигнет терминального состояния. Две особенности делают это безопасным: опрос дёшев, а вызов отправки уже выполнил дорогую работу.
Цикл
import time
def wait_for_video(job_id, timeout_s=600, interval_s=5):
deadline = time.monotonic() + timeout_s
while time.monotonic() < deadline:
req = urllib.request.Request(
f"{BASE_URL}/v1/videos/generations/{job_id}",
headers={"Authorization": f"Bearer {API_KEY}"},
)
with urllib.request.urlopen(req, timeout=30) as resp:
job = json.loads(resp.read().decode("utf-8"))
status = job.get("status")
if status in ("succeeded", "completed"):
return job
if status in ("failed", "error", "cancelled"):
raise RuntimeError(f"job {job_id} ended with status {status}: {job.get('error')}")
time.sleep(interval_s)
raise TimeoutError(f"job {job_id} did not finish within {timeout_s}s")
Более частый цикл не будет быстрее; он лишь израсходует лимит частоты. Для видеозадач пятисекундный интервал — разумное значение по умолчанию.
Замечания по проектированию
- Всегда задавайте дедлайн. Задача, которая никогда не завершается, не должна навсегда подвешивать поток запроса.
- Считайте неизвестный статус «продолжать ждать», а не успехом. Успех — только явный успех.
- Не опрашивайте внутри обработчика веб-запроса. Отправляйте в обработчике, возвращайте идентификатор задачи клиенту, а опрос и сохранение результата поручите фоновому воркеру.
- Сохраняйте идентификатор задачи и переходы статусов, чтобы прерванный процесс мог восстановиться, а не отправлять повторно и платить за рендеринг дважды.
Именно это разделение «сначала отправить, потом опрашивать» позволяет медленному видеоконвейеру стоять за быстрым API.
Частые ошибки и способы их исправления
Почти все сбои в первый час попадают в одну из четырёх категорий. Проверяйте их в этом порядке.
1. Аутентификация
Симптом: ответ «не авторизован» или «запрещено» до создания любой задачи.
Проверка: действительно ли в shell или процессе, запускающем скрипт, заполнена переменная HIAPI_API_KEY? Заголовок в точности Authorization: Bearer <key>? Не загружаете ли вы ключ при импорте, тогда как скрипт ожидает его позже? Выведите первые несколько символов разобранного ключа (никогда не весь ключ) и убедитесь, что это не пустая строка.
2. Путь эндпоинта
Симптом: «не найдено», обычно сразу.
Проверка: ровно один слэш между базовым URL и путём — поэтому в Python-примере вызывается .rstrip("/"). Сверьте путь генерации и путь опроса со страницей модели в документации; URL опроса без сегмента идентификатора задачи будет отдавать 404 каждый раз. Завершающий слэш, которого не ожидает сервер, даёт тот же симптом.
3. Неверно сформированное тело запроса
Симптом: ошибка валидации или задача, падающая сразу после принятия.
Проверка: выполните json.dumps(body) и inspectуйте результат. Совпадает ли model точно с seedance-2.5-flash/reference-to-video? Является ли поле референсов массивом, и каждая ли его запись — строковым URL, который разрешается в браузере? Отправляете ли вы Content-Type: application/json? Пропустите тело через python -m json.tool, чтобы исключить синтаксические ошибки до того, как оно уйдёт в сеть.
4. Статус задачи
Симптом: вызов отправки успешен, но задача падает или никогда не завершается.
Проверка: прочитайте поле ошибки в ответе о статусе — оно обычно указывает причину, чаще всего недоступный или неподдерживаемый референсный материал. Если задача просто стоит на месте, убедитесь, что вы опрашиваете правильный id и что сравнение статусов в цикле покрывает терминальные состояния, которые API реально возвращает. Логируйте каждый переход статуса; последний статус перед сбоем — ваша основа для диагностики.
Одно правило сокращает все четыре категории диагностики: логируйте идентификатор запроса и идентификатор задачи для каждого вызова. При сбое id превращает расплывчатое сообщение об ошибке в конкретный поиск.
Дальнейшие шаги
Теперь у вас есть полная картина: собрать тело запроса с промптом и референсами, отправить его, опрашивать до терминального состояния и обрабатывать четыре частые категории сбоев. Отсюда естественные следующие шаги лежат на уровне инженерии, а не API.
- Оберните отправку в повторные попытки с экспоненциальной задержкой для обработки временных сетевых ошибок, но никогда не повторяйте задачу, у которой уже есть id — это повторный рендеринг.
- Перенесите опрос в воркер или очередь, чтобы HTTP-слой оставался отзывчивым, а задачи переживали перезапуск процесса.
- Храните идентификатор задачи вместе с метаданными вашего собственного запроса (промпт, референсы, пользователь запроса), чтобы результаты оставались отслеживаемыми спустя месяцы.
- Пропускайте референсы только после проверки — скачивайте каждый URL, предоставленный пользователем, и только затем тратьте задачу.
Авторитетную схему запроса, поддерживаемые типы материалов и актуальные детали эндпоинта ищите на странице модели seedance-2.5-flash reference-to-video в HiAPI. Стройте по этой схеме, сохраняйте разделение «сначала отправить, потом опрашивать» — и интеграция останется скучной, а именно этого вы и хотите от видеоконвейера.
Похожие статьи
Все статьи →-
Руководство
Практическое руководство по gpt-6.2-sol: 5 ценных способов применения текстовой модели в бизнесе
-
Руководство
Практическое руководство по gpt-6.2-astra: интеграция и ключевые моменты реализации для 5 ценных текстовых сценариев
Чек-лист для разработчиков: от выбора сценариев до внедрения в инженерию
-
Руководство
Практические сценарии Tripo H3.1: 5 высокоценных применений и ключевые моменты реализации
От text-to-3D до multiview-восстановления: выбирайте правильный режим и параметры под бизнес-сценарий