HiAPI
Блог

Руководство

Как вызывать seedance-2.5-flash для генерации видео из текста через HiAPI API (curl и Python)

Пошаговая отработка рабочего запроса для разработчиков: эндпоинт, параметры, обработка асинхронных задач и рабочие примеры на curl и Python

Nov 19, 2026
Обложка: на тёмно-синем фоне вложенные широкие стрелки с персиковыми передними кромками ступенчато продвигаются вперёд, образуя геометрическую композицию, подобную потоку сигналов.
На этой странице

Что даёт вам seedance-2.5-flash/text-to-video

seedance-2.5-flash/text-to-video — это эндпоинт генерации видео из текста в HiAPI API. Вы отправляете текстовый промпт с описанием целевой сцены, а модель возвращает сгенерированное видео. Всё соглашение простое: на входе текст, на выходе видео.

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

Таким образом, работа по интеграции с вашей стороны делится на три части: сформировать корректный запрос на отправку, сохранить ID задачи и надёжно получить готовое видео. В этом руководстве эти три шага пройдены с рабочим кодом на curl и Python, затем рассмотрены проверка параметров, выбор между опросом и обратными вызовами, а также сценарии сбоев, с которыми сталкивается большинство первых интеграций.

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

Предварительные требования и получение API Key

Перед отправкой первого запроса убедитесь в трёх вещах.

Аккаунт HiAPI и API Key

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

export HIAPI_API_KEY="your_api_key_here"

Клиент, способный выполнять HTTPS-запросы

Для части с curl вам понадобится curl, который есть в macOS и большинстве дистрибутивов Linux. Для части на Python вам понадобятся Python 3 и библиотека requests (pip install requests). Проприетарный SDK не нужен — этот эндпоинт представляет собой обычный HTTPS с JSON-телом запроса, поэтому подойдёт любой HTTP-клиент, от fetch в Node до httpx в Python.

Способ хранения состояния между запросами

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

Имея Key и рабочий клиент, вы можете отправить запрос.

Первый рабочий запрос через curl

Вызов отправки — это POST с JSON-телом запроса. Точный путь эндпоинта и имя заголовка аутентификации указаны на странице модели — используйте эти значения как есть, не выводя их из других API. Структура вызова выглядит так:

curl -X POST "$HIAPI_BASE_URL/v1/models/seedance-2.5-flash/text-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A slow aerial shot over a misty pine forest at sunrise, soft light, cinematic"
  }'

Несколько замечаний о частях запроса:

  • Метод и путь. POST создаёт новую задачу генерации. Путь идентифицирует модель; перед копированием в собственную конфигурацию сверьте его со страницей модели.
  • Заголовки. Заголовок Authorization содержит ваш Key, а Content-Type: application/json сообщает серверу, как разбирать тело запроса.
  • Тело запроса. Как минимум нужно отправить строку prompt. Промпт — это творческий вход, всё, что рендерит модель, происходит из него, поэтому явно указывайте субъект, движение, освещение и поведение камеры.

Если запрос принят, ответ будет содержать объект задачи. Вы не получите URL видео сразу. Извлеките из ответа идентификатор задачи и сохраните его. Точное имя поля является частью схемы ответа, описанной на странице модели; считайте её единственным источником истины и не вшивайте догадки в клиент, пока не увидите реальный ответ.

Сначала можно проверить исходный ответ с помощью curl, а затем, поняв его структуру, перенести тот же вызов в код.

Выбор параметров: промпт, разрешение и длительность

Строго обязателен только prompt, но несколько необязательных параметров определяют результат и стоимость запроса. Задавайте их осознанно, а не принимайте значения по умолчанию вслепую.

Промпт

Промпт — параметр с наибольшим влиянием. Пишите его как бриф для оператора: субъект, действие, окружение, освещение и стиль съёмки. «A cyclist weaving through a neon-lit Tokyo street at night, handheld camera, shallow depth of field» даёт модели гораздо больше информации, чем «a city». Держите промпт в пределах ограничения длины, указанного на странице модели.

Разрешение

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

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

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

Проверка перед отправкой

Прежде чем подключать значения к производственному коду, посмотрите на странице модели допустимые диапазоны каждого параметра — разрешённую длительность, поддерживаемые разрешения и любые перечисления. Затем выполняйте проверку на клиенте: отклоняйте длительность вне диапазона и неизвестные значения разрешения до того, как запрос покинет ваш процесс. Так вы превращаете класс ошибок серверной проверки в мгновенный и недорогой сбой в собственных журналах.

То же правило действует для имён параметров. Копируйте их из документации; опечатка вроде лишнего подчёркивания в поле длительности обычно приводит к отказу или к молчаливому игнорированию, а молчаливое игнорирование — это ошибка, которую труднее обнаружить.

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

Ниже приведён эквивалентный код отправки на Python. Он читает Key из переменной окружения, отправляет JSON-тело, проверяет код состояния и возвращает идентификатор задачи из поля ответа, описанного в документации.

import os
import requests

BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]


def submit_video(prompt: str, **options) -> str:
    payload = {
        "prompt": prompt,
        **options,  # e.g. resolution="720p", duration=5
    }
    response = requests.post(
        f"{BASE_URL}/v1/models/seedance-2.5-flash/text-to-video",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=30,
    )
    response.raise_for_status()
    body = response.json()
    task_id = body["id"]  # confirm the field name on the model page
    return task_id


if __name__ == "__main__":
    task_id = submit_video(
        "A slow aerial shot over a misty pine forest at sunrise, soft light, cinematic"
    )
    print("submitted task:", task_id)

В этом коде есть несколько намеренных решений:

  • Тайм-аут. Вызов отправки должен возвращаться быстро, но явный timeout не даёт зависшему сокету заблокировать ваш рабочий процесс.
  • raise_for_status(). Немедленно завершается с ошибкой при HTTP-ошибке, а не разбирает тело ошибочного ответа как успешный ответ.
  • Именованные аргументы-опции. Передача **options сохраняет читаемость места вызова, а после подтверждения точных имён на странице модели добавить resolution или duration становится очень просто.
  • Возврат ID. Ответственность функции заканчивается на отправке. Сохраните этот ID в какое-либо постоянное хранилище — он понадобится в следующем разделе для получения результата.

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

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

После отправки у вас есть ID задачи, но ещё нет видео. Есть два способа сократить этот разрыв.

Опрос

С фиксированным интервалом опрашивайте эндпоинт состояния задачи, пока задача не перейдёт в терминальное состояние, затем получите URL вывода из ответа о завершении.

import time
import requests


def wait_for_video(task_id: str, timeout_s: int = 600) -> dict:
    deadline = time.time() + timeout_s
    delay = 2.0
    while time.time() < deadline:
        response = requests.get(
            f"{BASE_URL}/v1/tasks/{task_id}",  # confirm path on the model page
            headers={"Authorization": f"Bearer {API_KEY}"},
            timeout=30,
        )
        response.raise_for_status()
        task = response.json()
        state = task["status"]
        if state == "completed":
            return task
        if state == "failed":
            raise RuntimeError(task.get("error", "generation failed"))
        time.sleep(delay)
        delay = min(delay * 1.5, 15)  # gentle backoff, capped
    raise TimeoutError(f"task {task_id} did not finish in time")

Три практических правила опроса:

  • Экспоненциальная задержка. Начинайте с короткой задержки и постепенно увеличивайте её. Постоянный высокочастотный опрос впустую расходует квоту и увеличивает нагрузку без всякой пользы.
  • Устанавливайте предел. Каждый цикл опроса нуждается в крайнем сроке. Генерация видео может занять некоторое время, но неограниченный цикл в конечном итоге из-за зависшей задачи подвесит ваш рабочий процесс навсегда.
  • Различайте состояния. Явно обрабатывайте failed, чтобы плохой промпт не воспринимался молча как тайм-аут.

Обратные вызовы

Если вы зарегистрируете URL обратного вызова по HTTPS, HiAPI сможет уведомить вас о завершении задачи, полностью избавляя от опроса. Два правила делают обратные вызовы безопасными и надёжными:

  • Сначала проверьте, потом доверяйте. Рассматривайте обратный вызов как неаутентифицированный ввод, пока не проверите его подпись или источник с помощью механизма, описанного в документации платформы.
  • Обеспечьте идемпотентность. Обратный вызов может быть доставлен несколько раз. Используйте ID задачи в качестве ключа обработчика и сделайте обработку повторных доставок безоперационной — сохраняйте результат один раз, а повторные доставки подтверждайте.

Независимо от выбранного способа получение результата идемпотентно: запрос URL результата для завершённой задачи должен возвращать то же видео, поэтому повторные попытки после сетевой ошибки безопасны.

Типичные ошибки и способы их исправления

Большинство сбоев сводится к нескольким категориям. Прежде чем предполагать недокументированное поведение, пройдитесь по этому списку.

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

401 или 403 почти всегда означает, что Key отсутствует, имеет неверный формат или истёк. Проверьте, присутствует ли заголовок Authorization, в точности ли схема аутентификации соответствует документации и действительно ли переменная окружения содержит Key — пустая строка даёт запутанный, но связанный с аутентификацией сбой.

Отказ проверки

4xx с сообщением о проверке означает, что сервер отклонил ваши параметры. Перечитайте допустимые диапазоны на странице модели и проверьте имена параметров посимвольно. Если длительность или разрешение выходят за пределы диапазона, исправление — это проверка на клиенте, описанная ранее: быстро завершайтесь с ошибкой в собственном коде, а не отправляйте запрос на сервер и обратно.

Задача застряла в нетерминальном состоянии

Если опрос так и не видит completed или failed, задача может всё ещё выполняться, либо ваш цикл опроса запрашивает неверный ID задачи. Записывайте отправленный ID и ID, который опрашивается, и сравнивайте их. Ваш цикл также должен применять крайний срок; когда срок срабатывает, следует вывести ID задачи, а не повторять попытки вслепую.

Результат не пришёл после обратного вызова

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

Повторная отправка той же задачи

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

Общий принцип: при сбое сначала прочитайте тело ответа с ошибкой и документацию модели, а затем меняйте код. Если какое-либо значение или поле не описано, избегайте предположения о его существовании — проверьте по странице модели и соответствующим образом скорректируйте запрос.

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

Все статьи →

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

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

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