Как использовать seedance-2.0-fast через hiapi API: curl, Python и рабочие запросы

В этом руководстве показаны минимальный запрос для генерации видео с помощью seedance-2.0-fast, все входные поля, которые модель фактически принимает, а также способы дождаться результата через опрос (polling) или callback. Каждая структура запроса и сообщение об ошибке ниже проверены на реальном API, поэтому код можно копировать и использовать напрямую.

Что вы создадите и что потребуется

Цель одна: отправить текстовый промпт и получить загружаемый URL MP4. seedance-2.0-fast — это оптимизированная по скорости версия Seedance 2.0: она жертвует максимальным разрешением (не выше 720p) ради более быстрой генерации, поэтому отлично подходит для превью, итерационных циклов и больших объёмов коротких видеоклипов.

Вам нужно только одно: API-ключ hiapi. Получите его в своей панели управления, его формат выглядит как sk-.... Все видеомодели (включая эту) обслуживаются через единый асинхронный эндпоинт задач: сначала вы выполняете POST /v1/tasks, чтобы создать задачу, затем получаете результат по id задачи. Для видео синхронного режима нет.

Актуальную цену за один клип смотрите на странице тарифов (модель только что запущена, поэтому ориентируйтесь на неё, а не на любые цифры из статей в блогах).

Минимальный рабочий пример (curl)

Создание задачи:

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-fast",
    "input": {
      "prompt": "Бумажный кораблик плывёт по залитой дождём улице в сумерках, кинематографично, медленный наезд камеры",
      "duration": 5,
      "resolution": "720p",
      "aspect_ratio": "16:9"
    }
  }'

Id задачи в ответе находится в data.taskId:

{
  "data": {
    "taskId": "task_abc123..."
  }
}

Опрашивайте задачу, пока состояние не станет терминальным:

curl "https://api.hiapi.ai/v1/tasks/task_abc123..." \
  -H "Authorization: Bearer sk-YOUR_KEY"

Когда data.status равен "success", URL видео находится в data.output[0].url. Этот URL подписан и истекает — скачайте файл немедленно, не используйте горячие ссылки:

curl -o clip.mp4 "<the output url>"

Все входные поля (проверено)

Обязателен только prompt. Любое поле, отсутствующее в этой таблице, будет отклонено с кодом 400 — схема не допускает дополнительных свойств.

Поле	Тип	Обязательно	Допустимые значения
prompt	string	да	минимальная длина 3 символа
duration	целое число	нет	4–15 (секунд)
resolution	string	нет	480p, 720p
aspect_ratio	string	нет	1:1, 4:3, 3:4, 16:9, 9:16, 21:9, adaptive

Два момента стоит отметить особо:

• duration — это целое число, а не строка. Отправка "duration": "5" не пройдёт валидацию с ошибкой duration: got string, want integer.
• Нет ввода изображений. seedance-2.0-fast поддерживает только генерацию видео из текста; поля вроде image_urls будут отклонены схемой. Если вам нужна генерация видео из изображения, обратитесь к руководству по рабочему процессу API генерации видео из изображений, чтобы узнать о моделях, поддерживающих эту функцию.

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

SDK не нужен — достаточно requests:

import time
import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer sk-YOUR_KEY",
    "Content-Type": "application/json",
}

def create_task(prompt: str, duration: int = 5,
                resolution: str = "720p", aspect_ratio: str = "16:9") -> str:
    payload = {
        "model": "seedance-2.0-fast",
        "input": {
            "prompt": prompt,
            "duration": duration,
            "resolution": resolution,
            "aspect_ratio": aspect_ratio,
        },
    }
    r = requests.post(API_BASE, json=payload, headers=HEADERS, timeout=60)
    r.raise_for_status()
    return r.json()["data"]["taskId"]

def wait_task(task_id: str, timeout_s: int = 600, poll_interval: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30)
        r.raise_for_status()
        task = r.json()["data"]
        if task["status"] == "success":
            return task
        if task["status"] == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')}: {err.get('message')}")
        time.sleep(poll_interval)
    raise TimeoutError(f"task {task_id} still running after {timeout_s}s")

task_id = create_task(
    "Бариста создаёт латте-арт в залитом солнцем кафе, малая глубина резкости"
)
task = wait_task(task_id)
video_url = task["output"][0]["url"]

# URL подписан и истекает — сохраните байты немедленно.
with open("clip.mp4", "wb") as f:
    f.write(requests.get(video_url, timeout=120).content)
print("saved clip.mp4")

Считайте любое состояние, кроме success / fail, значением «всё ещё выполняется» — так цикл останется устойчивым, даже если названия промежуточных состояний изменятся в будущем.

Замечания для production

Используйте callback вместо опроса

Для любого сценария за пределами скриптов зарегистрируйте callback при создании задачи и полностью пропустите опрос:

{
  "model": "seedance-2.0-fast",
  "input": { "prompt": "..." },
  "callback": { "url": "https://your-app.com/hooks/hiapi", "when": "final" }
}

При "when": "final" ваш эндпоинт получит ровно один POST, когда задача достигнет терминального состояния. Опрос подходит для CLI и notebook; при работе в масштабе callback лучше (нет лишних запросов и задержки из-за интервала опроса). Если ваш хук, похоже, не срабатывает, обратитесь к руководству по устранению неполадок с callback — почти всегда это либо проблема доступности URL, либо ваш обработчик возвращает ответ, отличный от 2xx.

Идемпотентность

Создание задачи не бесплатно, поэтому предотвращайте дублирующие отправки на своей стороне: пусть каждое бизнес-событие соответствует не более чем одному вызову POST /v1/tasks (например, сохраняйте taskId вместе со строкой вашего заказа/задачи перед повтором). Если ваш процесс упадёт после создания задачи, вы можете восстановиться, повторно прочитав сохранённый taskId и возобновив GET /v1/tasks/<id> — задача продолжит выполняться на сервере независимо от того, опрашиваете вы её или нет.

Ошибки, с которыми вы реально столкнётесь

Симптом	Значение	Исправление
400 и error_code: "INVALID_REQUEST"	Ввод не прошёл валидацию схемы; message укажет конкретное поле, например duration: maximum: got 20, want 15	Исправьте это поле; допускаются только четыре поля из таблицы выше
401 и error.code: "permission_denied"	Ключ недействителен или действителен, но не включён для этой модели	Проверьте ключ в панели управления; права на модели настраиваются отдельно для каждого ключа
404 при GET и "task not found"	Неверный id задачи или задача принадлежит другому аккаунту	Используйте taskId, возвращённый при создании, и тот же аккаунт
Состояние задачи "fail" с объектом error	Сама генерация не удалась	Прочитайте error.code/error.message; скорректируйте промпт и повторите

Обратите внимание на две обёртки ошибок: ошибки валидации помещают message на верхний уровень, а ошибки аутентификации вложены в error. Если вы пишете универсальное промежуточное ПО, нужно обрабатывать оба случая.

Когда подходит seedance-2.0-fast

Если вам нужен вывод в 1080p или 4K, используйте полную версию seedance-2.0 — тот же эндпоинт, тот же процесс, более высокий предел разрешения (и она требует явного указания aspect_ratio). Для более полного сравнения семейства Seedance с другими видеомоделями платформы обратитесь к сравнению видеомоделей. Полный справочник параметров каждой модели смотрите в документации, а страница модели отслеживает текущие возможности и статус ценообразования.

Часто задаваемые вопросы

Какие разрешения поддерживает seedance-2.0-fast? 480p и 720p. Это цена за скорость — полная версия seedance-2.0 в том же процессе /v1/tasks достигает 1080p и 4k.

Можно ли использовать seedance-2.0-fast для генерации видео из изображения? Нет. Входная схема принимает только prompt, duration, resolution и aspect_ratio; поля изображений будут отклонены ошибкой валидации. О вариантах генерации видео из изображения на hiapi см. руководство по рабочему процессу генерации видео из изображений.

Какой длины может быть сгенерированное видео? duration принимает целые числа от 4 до 15 секунд. Значения вне этого диапазона не пройдут валидацию до создания задачи (отклонённые запросы не тарифицируются).

Мне опрашивать или использовать callback? Для скриптов и низкой нагрузки достаточно опроса примерно каждые ~5 секунд. В production передавайте при создании callback: {"url": ..., "when": "final"}, чтобы hiapi отправлял вам терминальное состояние — один запрос вместо десятков.

Почему ключ, который работает с другими моделями, здесь возвращает 401 permission_denied? Доступ к моделям ограничивается отдельно для каждого ключа. 401 с permission_denied на этой модели означает, что ключ существует, но не включён для seedance-2.0-fast — проверьте права на модели для этого ключа в панели управления.

Как долго действителен выходной URL? Это подписанный URL, который истекает. Сразу после успешного завершения задачи скачайте MP4 и сохраните его у себя; не встраивайте исходный выходной URL в какие-либо долговременные места.