HiAPI
Блог

Руководство

Как вызвать API преобразования текста в видео veo-3.1: примеры на curl и Python

Практическое руководство по интеграции для разработчиков

Nov 17, 2026
Плоский гранёный минеральный срез для обложки в глубоких нефтяных, бирюзовых и малахитовых тонах для руководства по API преобразования текста в видео veo-3.1.
На этой странице

Что veo-3.1/text-to-video умеет делать для вас

veo-3.1/text-to-video — это модель генерации видео из текста, предоставляемая через единый API HiAPI. Вы отправляете текстовый промпт, выбираете некоторые параметры вывода и получаете сгенерированное видео. Она находится на HiAPI вместе с другими эндпоинтами генерации, поэтому, если вы уже используете возможности работы с изображениями или чатом на этой платформе, такая схема интеграции покажется вам знакомой: один HTTP-запрос с аутентификацией возвращает задачу, и вы опрашиваете её до завершения.

Этот эндпоинт подходит, когда у вас есть текстовое описание сцены и вы хотите сгенерировать короткое видео, не управляя инфраструктурой самостоятельно. Вам не нужно самостоятельно заниматься распределением GPU, весами моделей или очередями. Плата за это — асинхронность генерации: вы отправляете задачу и возвращаетесь позже за результатом. Для видео это нормально, поскольку рендеринг занимает больше времени, чем один цикл запроса/ответа.

Используйте преобразование текста в видео, когда основным входом является промпт. Если позже вам понадобится генерация с условием по изображению или видео, обратитесь к соответствующим эндпоинтам в каталоге моделей. Структура запроса здесь (аутентификация, отправка задачи, опрос) совпадает с той схемой, которую вы будете повторно использовать в медиаэндпоинтах HiAPI, поэтому изучив её один раз, вы получите долгосрочную выгоду. Полные сведения о модели вы найдёте на странице модели veo-3.1/text-to-video.

Эндпоинт, аутентификация и структура запроса

Все запросы HiAPI используют HTTPS и bearer-токен. Храните свой API-ключ в переменной окружения, а не в коде, и отправляйте его в заголовке Authorization:

Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json

Запрос преобразования текста в видео — это JSON-объект, содержащий поле model и объект input. Объект input содержит промпт и любые элементы управления выводом. Минимальное тело запроса выглядит так:

{
  "model": "veo-3.1/text-to-video",
  "input": {
    "prompt": "Ночью по мокрому от дождя неоновому переулку, медленный наезд камеры"
  }
}

Возвращается не итоговое видео, а конверт задачи. Обычно он содержит идентификатор задачи, поле статуса и метку времени. Его структура примерно такая:

{
  "id": "job_abc123",
  "status": "queued",
  "created_at": "2025-01-01T00:00:00Z"
}

Точные имена полей уточняйте по фактическому ответу, но структура неизменна: вам нужен id для опроса, а status сообщает, находится ли задача в очереди, выполняется или завершена. Не считайте задачу завершённой только потому, что вызов отправки вернул 200 — это означает лишь, что задача принята.

Выбор параметров: нативное аудио и уровни разрешения

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

Нативное аудио

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

Уровни разрешения

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

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

Готовый к запуску запрос curl

Эта команда curl отправляет задачу преобразования текста в видео. Она задаёт тип содержимого JSON, передаёт bearer-токен из переменной окружения и отправляет тело запроса с model и input.

curl -X POST https://api.hiapi.ai/v1/videos/generations \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1/text-to-video",
    "input": {
      "prompt": "Ночью по мокрому от дождя неоновому переулку, медленный наезд камеры",
      "duration": 5,
      "resolution": "720p"
    }
  }'

Успешный вызов возвращает JSON-объект с id и status задачи. Запишите этот id — он понадобится при опросе. Если вы пишете скрипт, можно извлечь id из вывода с помощью обработчика JSON:

JOB_ID=$(curl -s -X POST https://api.hiapi.ai/v1/videos/generations \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"veo-3.1/text-to-video","input":{"prompt":"Ночью по мокрому от дождя неоновому переулку, медленный наезд камеры"}}' \
  | jq -r '.id')
echo "$JOB_ID"

Скорректируйте путь эндпоинта, имена параметров и любые необязательные поля в соответствии с ожиданиями фактического API. Эта схема — POST с JSON-телом, чтение id из ответа — лежит в основе каждого последующего примера.

Отправка того же запроса на Python

Версия на Python делает то же самое с помощью стандартной библиотеки requests. Читайте ключ из окружения, формируйте payload и отправляйте.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = "https://api.hiapi.ai/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

payload = {
    "model": "veo-3.1/text-to-video",
    "input": {
        "prompt": "Ночью по мокрому от дождя неоновому переулку, медленный наезд камеры",
    },
}

response = requests.post(
    f"{BASE_URL}/videos/generations",
    headers=headers,
    json=payload,
    timeout=60,
)
response.raise_for_status()

job = response.json()
job_id = job["id"]
print(f"Задача отправлена: {job_id} (статус: {job.get('status')})")

Стоит подчеркнуть два момента. Во-первых, response.raise_for_status() превращает ошибки HTTP в исключения, благодаря чему сбой сразу становится заметным, а неисправный payload не проходит молча. Во-вторых, timeout=60 предотвращает блокировку скрипта из-за зависшего соединения. Сама отправка быстрая; фактическое видео рендерится асинхронно, поэтому ждать файла здесь не нужно. Далее вы будете использовать job_id для опроса завершения.

Опрос асинхронной задачи до готовности видео

После отправки опрашивайте эндпоинт задачи, пока статус не укажет на завершение или сбой. Простой цикл с короткой паузой вполне подходит для начала.

import time

while True:
    res = requests.get(
        f"{BASE_URL}/videos/generations/{job_id}",
        headers=headers,
        timeout=30,
    )
    res.raise_for_status()
    state = res.json().get("status")
    print(f"Статус: {state}")

    if state == "succeeded":
        video_url = res.json().get("output", {}).get("url")
        print(f"Видео готово: {video_url}")
        break
    if state == "failed":
        raise RuntimeError(f"Задача завершилась ошибкой: {res.json()}")

    time.sleep(5)

Несколько полезных улучшений: начинайте с короткого интервала, затем постепенно увеличивайте паузу, чтобы сократить лишние запросы; добавьте максимальное число попыток или дедлайн, чтобы избежать бесконечного цикла при зависшей задаче; и осторожно относитесь к любым неожиданным статусам, не предполагая, что они означают «продолжать ждать». Распространённые значения статуса: queued, running, succeeded и failed. При успехе ответ обычно содержит URL вывода; скачайте и сохраните файл вовремя, поскольку подписанные URL могут истекать.

Сделайте опрос идемпотентным и записывайте id задачи при каждом изменении статуса. Если ваш процесс перезапустится, вы сможете возобновить работу по id без повторной отправки. В продакшене, если платформа предоставляет webhook, рассмотрите его использование, а опрос оставьте как резервный вариант.

Диагностика типичных ошибок

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

Ошибки аутентификации (401/403)

Проверьте, что заголовок Authorization присутствует и правильно отформатирован как Bearer <key>, а также что переменная окружения действительно задана в оболочке или процессе, откуда выполняется запрос. Частая ловушка — запуск скрипта в окружении, где ключ есть в одной оболочке, но отсутствует в другой.

Ошибки валидации (400/422)

Такие ошибки возвращают структурированные сведения о том, какое поле некорректно. Частые причины: отсутствует prompt, не поддерживаемое значение resolution или duration, либо неверный уровень вложенности параметров. Воспринимайте сообщение об ошибке буквально — обычно оно указывает на проблемное поле. Сначала отправьте минимальный payload, затем добавляйте по одному параметру за раз.

Ограничение скорости (429)

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

Тайм-ауты и сетевые ошибки

Клиентский тайм-аут при отправке редко связан с самой задачей — задача выполняется на сервере. Используйте разумные тайм-ауты как для отправки, так и для запросов опроса, и повторяйте идемпотентные GET-запросы. Никогда не повторяйте POST вслепую, не проверив, была ли исходная задача уже создана.

Задача никогда не завершается

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

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

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

Все статьи →

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

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

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