Как использовать veo-3.1-lite/text-to-video через hiapi API: curl, Python и один рабочий запрос

veo-3.1-lite/text-to-video генерирует короткие видеоролики из одного текстового промпта — начальное изображение не требуется. В этом руководстве приведены готовые к копированию и вставке примеры на curl и Python для реального API задач hiapi, точная входная схема (проверенная на живом эндпоинте), а также формы ошибок, с которыми вы действительно столкнётесь в продакшене.

1. Предварительные требования

• Аккаунт hiapi и API-ключ (формата sk-...), полученный на панели API Keys.
• curl или Python 3 с установленным requests (pip install requests).
• Больше ничего не нужно — text-to-video требует только строку промпта.

Каждая модель генерации на hiapi работает через один и тот же унифицированный асинхронный API задач: POST /v1/tasks создаёт задачу, затем вы опрашиваете её или ожидаете callback для получения результата. veo-3.1-lite/text-to-video вызывается точно так же, как любая другая видеомодель — те же заголовки аутентификации, тот же жизненный цикл задачи — отличаются только model и input. Идентификатор модели — veo-3.1-lite/text-to-video с суффиксом /text-to-video; в той же линейке также доступна veo-3.1-lite/image-to-video — отдельный идентификатор модели для анимации исходного изображения.

2. Минимальный рабочий пример

2.1 Создание задачи (curl)

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-lite/text-to-video",
    "input": {
      "prompt": "a paper boat drifting down a rain-slicked city street at night, neon signs reflecting on wet asphalt",
      "duration": 6,
      "resolution": "720p",
      "aspect_ratio": "16:9",
      "generate_audio": true
    }
  }'

При успешном вызове сразу возвращается идентификатор задачи — генерация выполняется асинхронно:

{"code":200,"data":{"taskId":"tk-hiapi-01XXXXXXXXXXXXXXXXXXXXXXXX"},"message":"success"}

2.2 Опрос результата

curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-01XXXXXXXXXXXXXXXXXXXXXXXX \
  -H "Authorization: Bearer sk-<your-api-key>"

Пока ролик рендерится, status равен "handling". По завершении:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01XXXXXXXXXXXXXXXXXXXXXXXX",
    "model": "veo-3.1-lite/text-to-video",
    "status": "success",
    "storage": "temp",
    "output": [
      {"artifactId": "...", "type": "video", "url": "https://temp.hiapi.ai/.../result.mp4", "expireAt": 1786932195}
    ]
  },
  "message": "success"
}

output[0].url — это временная ссылка с истекающим сроком действия: скачайте файл до наступления expireAt (или перенесите результат в постоянное хранилище).

2.3 Полный пример на Python

import time
import requests

API_KEY = "sk-<your-api-key>"
BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def create_task(prompt: str) -> str:
    resp = requests.post(BASE, headers=HEADERS, json={
        "model": "veo-3.1-lite/text-to-video",
        "input": {
            "prompt": prompt,
            "duration": 6,
            "resolution": "720p",
            "aspect_ratio": "16:9",
        },
    }, timeout=30)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


def wait_for_result(task_id: str, poll_seconds: int = 5, timeout_seconds: int = 600) -> str:
    deadline = time.time() + timeout_seconds
    while time.time() < deadline:
        resp = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        data = resp.json()["data"]
        if data["status"] == "success":
            return data["output"][0]["url"]
        if data["status"] == "failed":
            raise RuntimeError(f"task {task_id} failed: {data}")
        time.sleep(poll_seconds)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_seconds}s")


if __name__ == "__main__":
    tid = create_task("a paper boat drifting down a rain-slicked city street at night")
    video_url = wait_for_result(tid)
    print(video_url)

3. Входная схема

Все перечисленные ниже поля находятся внутри input. Схема строгая — отправка несуществующего поля возвращает 400 (additional properties '<field>' not allowed), что является хорошим способом быстро проверить запрос до рендеринга.

Поле	Тип	Обязательное	Описание
prompt	string	Да	Описание сцены; конкретно указывайте субъект, движение и поведение камеры.
duration	integer	Нет	Одно из значений 4, 6, 8 (секунды).
resolution	string	Нет	"720p" или "1080p".
aspect_ratio	string	Нет	"16:9" или "9:16".
generate_audio	boolean	Нет	Включать в рендеринг синхронизированный фоновый/звуковой ряд.
negative_prompt	string	Нет	Элементы содержимого, которых рендеринг должен избегать.
seed	integer	Нет	Фиксированное значение для воспроизведения той же композиции/движения между попытками.

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

4. Шаблоны для продакшена

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

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

{
  "model": "veo-3.1-lite/text-to-video",
  "input": {"prompt": "..."},
  "callback": {"url": "https://your-app.example.com/webhooks/hiapi", "when": "final"}
}

callback.url должен быть доступным URL http(s), а when принимает только "final" — hiapi отправит один POST, когда задача достигнет терминального состояния (success или failed). Это позволяет не тратить квоту запросов на циклы опроса и получать результат в момент его готовности, что особенно важно для видео (рендеринг занимает больше времени, чем генерация изображений).

Идемпотентность и повторные попытки

Если ваш исполнитель задач может повторять отправку (сбой, тайм-аут, повторное развёртывание), фиксируйте собственный ключ идемпотентности вместе с возвращённым taskId до отправки запроса, чтобы при повторной попытке можно было проверить «отправлял ли я уже это?», а не создавать дублирующий рендеринг и платить дважды.

Обработка ошибок

На практике встречаются две разные формы ошибок:

• Некорректные входные данные (400) — ошибка валидации тела запроса:

  {"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: prompt: missing required field \"prompt\""}
  

• Ошибка аутентификации/прав доступа (401) — ключ отсутствует, недействителен или недостаточно прав:

  {"error":{"code":"permission_denied","message":"This API key cannot use the selected model...","request_id":"...","type":"hiapi_error"}}
  

Сначала ветвитесь по HTTP-статусу, затем проверяйте тело ответа — 400 почти всегда означает ошибку в имени поля или значении (исправьте запрос), а 401 означает, что нужно разобраться с самим ключом (права на панели или новый ключ).

5. Связанные страницы

• Страница модели veo-3.1-lite/text-to-video — актуальные цены и встроенная в браузер песочница, где можно протестировать промпты перед написанием кода интеграции.
• Страница модели veo-3.1-lite/image-to-video — родственная модель, обусловленная изображением, для анимации существующего кадра, а не для старта с текста.
• Введение в унифицированный асинхронный API — жизненный цикл задач, общий для всех моделей hiapi (изображения, видео, аудио).
• Документация по аутентификации — формат API-ключа и детали заголовков запросов.
• Руководство по API seedance-2.5/text-to-video — вторая модель текст-в-видео на том же API задач, полезная для сравнения схем и цен.

Частые вопросы

Требует ли veo-3.1-lite/text-to-video начальное изображение? Нет. Он генерирует полностью на основе строки prompt. Если у вас есть исходное изображение, которое нужно анимировать, используйте отдельный идентификатор модели veo-3.1-lite/image-to-video.

Какие разрешения и длительности поддерживаются? resolution — "720p" или "1080p"; duration — 4, 6 или 8 секунд. Отправка любого другого значения вернёт 400 со списком допустимых значений.

Могут ли сгенерированные ролики содержать звук? Да — установите "generate_audio": true в input, чтобы включить синхронизированный фоновый/звуковой ряд.

Как избежать опроса в цикле? Передайте объект callback с вашим webhook url и "when": "final". По завершении задачи hiapi отправит POST на этот URL, и вам не придётся периодически заново проверять GET /v1/tasks/<id>.

Почему мой запрос возвращает 401, а не 400? 401 с error_code/code равным "permission_denied" означает, что сам API-ключ недействителен или не имеет доступа к модели — проверьте панель API Keys. 400 означает, что тело запроса имеет неверный формат при действительном ключе.

Возвращаемый URL видео постоянный? Нет — output[0].url является временной ссылкой с меткой времени expireAt. Скачайте файл или перенесите его в постоянное хранилище до истечения срока действия.