Видео

Понимание видео

Запросы с видео идут в POST https://api.aitunnel.ru/v1/chat/completions с параметром messages в формате multi-part. video_url.url может быть публичным URL или data-URI с base64. Несколько роликов — отдельные элементы массива content. Текст лучше ставить первым, затем видео.

Модель должна уметь видео во входе: в каталоге у неё modalities.input содержит video. Пример ниже — gemini-3.7-flash.

Использование URL видео

curl https://api.aitunnel.ru/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-aitunnel-xxx" \
  -d '{
    "model": "gemini-3.7-flash",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "Опиши, что происходит в этом видео."},
          {
            "type": "video_url",
            "video_url": {"url": "https://www.youtube.com/watch?v=aqz-KE-bpKQ"}
          }
        ]
      }
    ]
  }'

Использование видео в формате Base64

Для локально хранящихся видео отправьте их как data-URI data:video/mp4;base64,... (подставьте MIME файла).

# url — data-URI: data:video/mp4;base64,<...>
curl https://api.aitunnel.ru/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-aitunnel-xxx" \
  -d '{
    "model": "gemini-3.7-flash",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "Что происходит в этом видео?"},
          {
            "type": "video_url",
            "video_url": {"url": "data:video/mp4;base64,AAAA..."}
          }
        ]
      }
    ]
  }'

Поддерживаемые типы видео:

• video/mp4
• video/mpeg
• video/mov
• video/webm

Какие чат-модели видят видео — группа chat публичного каталога, фильтр по modalities.input:

curl https://api.aitunnel.ru/public/aitunnel/models/chat

Видеофайлы бывают большими: сжимайте, обрезайте до нужного фрагмента, не гоните 4K, если хватает 720p. Длинный ролик лучше резать на сегменты — у моделей разные потолки длительности.

Генерация видео

AITUNNEL поддерживает генерацию видео по текстовому промпту (text-to-video), по опорному изображению (image-to-video), по референсу (reference-to-video) и правку существующего видео (video-to-video) через асинхронный API.

Процесс состоит из трёх шагов:

1. Отправить задачу: POST /v1/videos — мгновенно возвращает id, polling_url и status: "pending".
2. Опрашивать статус: GET /v1/videos/{id} — повторять каждые 15–30 секунд до completed или failed.
3. Скачать результат: GET /v1/videos/{id}/content — возвращает MP4.

Поддерживаемые модели

Актуальный список моделей генерации видео вместе с их возможностями (размеры, aspect ratio, длительности, поддержка аудио, image-to-video, референсов, video-to-video, passthrough-параметров и тарификации) доступен через публичный эндпоинт:

curl https://api.aitunnel.ru/public/aitunnel/models/videos

Также его можно посмотреть на странице моделей.

Каждая запись содержит поля:

Тарификация

Стоимость зависит от модели, разрешения и длительности. У части моделей (например, flux-video-upscale) тариф — за мегапиксель-секунду выходного ролика: цена за единицу лежит в price_per_megapixel_second (Precise) и price_per_megapixel_second_creative (Creative). Резерв у них считается по самому большому исходнику, который мы принимаем (15 с, 1080p, умноженные на upscale_factor), а после завершения разница возвращается. Учтите, что min_price_per_second / max_price_per_second у них равны потолку, а не реальной цене вашего запроса.

• В момент отправки задачи мы резервируем максимальную возможную стоимость запроса (worst-case) на вашем балансе. Резерв — это не списание: пока задача не завершилась, деньги удержаны, но ещё не потрачены, и в истории расходов их нет.
• Когда задача завершается (completed), мы списываем фактическую стоимость и возвращаем разницу на баланс.
• Если задача упала (failed), истекла (expired) или была отменена провайдером (cancelled) — вся зарезервированная сумма возвращается автоматически, а списания не появляется вообще.
• Больше зарезервированной суммы с вас не спишут никогда. Если провайдер выставил нам больше — разницу оплачиваем мы.
• Расчёт делает сервер, а не ваш опрос: каждую минуту планировщик проверяет незавершённые задачи, поэтому резерв освобождается сам — даже если вы больше не обращались к API.
• У каждой задачи есть жёсткий срок (поле expires_at, три часа для видео). Если к этому времени провайдер не отдал результат, задача переводится в expired и резерв возвращается полностью. Зависнуть в pending навсегда задача не может.
• Итоговая стоимость приходит в usage.cost_rub и usage.cost — одно и то же число в рублях — ответа GET /v1/videos/{id}, но только после расчёта.

Отправка задачи

Базовый text-to-video

# 1. Отправить задачу
curl -X POST "https://api.aitunnel.ru/v1/videos" \
  -H "Authorization: Bearer sk-aitunnel-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-fast",
    "prompt": "A golden retriever playing fetch on a sunny beach",
    "size": "1280x720",
    "duration": 5
  }'
# => { "id": "abc123", "polling_url": "https://api.aitunnel.ru/v1/videos/abc123", "status": "pending" }

# 2. Опросить статус (повторять до completed/failed)
curl "https://api.aitunnel.ru/v1/videos/abc123" \
  -H "Authorization: Bearer sk-aitunnel-xxx"

# 3. Скачать видео после completed
curl -L "https://api.aitunnel.ru/v1/videos/abc123/content?index=0" \
  -H "Authorization: Bearer sk-aitunnel-xxx" \
  --output video.mp4

Параметры запроса

Поддерживаемые разрешения и aspect ratio

Общий набор значений по всем моделям (конкретные опции зависят от модели — сверяйтесь с её supported_resolutions / supported_aspect_ratios / supported_sizes):

• Разрешения: 360p, 480p, 720p, 768p, 1080p, 1K, 2K, 4K
• Aspect ratios: 16:9, 9:16, 1:1, 4:3, 3:4, 21:9, 9:21

Image-to-Video (опорные кадры)

Передайте массив frame_images с первым и/или последним кадром — модель сгенерирует переход между ними (или продолжение первого кадра).

{
  "model": "wan-2.7",
  "prompt": "A character walking through a misty forest",
  "frame_images": [
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/first-frame.png" },
      "frame_type": "first_frame"
    }
  ],
  "resolution": "1080p",
  "duration": 5
}

Для указания последнего кадра используйте "frame_type": "last_frame". Поддерживаемые типы опорных кадров для модели указаны в поле supported_frame_images публичного эндпоинта.

Reference-to-Video (визуальный референс)

input_references — референсные изображения для стиля или содержания, а не покадровая основа. Поддерживается моделями, у которых supports_input_references: true.

Референсов может быть несколько: передайте массив, порядок сохраняется. AITUNNEL их количество не ограничивает — сколько принимает конкретная модель, решает провайдер, и при переборе запрос завершится ошибкой от него. У seedance-2.0 это порядка девяти изображений, у seedance-2.5 — заметно больше.

У части моделей референсы меняют тариф. Например, у heygen-video-1 ролик с input_references стоит вдвое дороже обычного: 6,80 ₽/сек в 480p, 10,20 ₽/сек в 768p и 30,60 ₽/сек в 2K против 3,40, 5,10 и 15,30 ₽/сек. Резерв с референсами берётся по их ставке, а фактическое списание приходит в usage.cost_rub. Звук (речь, фон, эффекты) эта модель генерирует всегда, у неё generate_audio: null.

{
  "model": "seedance-2.0",
  "prompt": "Покупатели рассматривают витрину, мягкий вечерний свет, медленный проезд камеры",
  "input_references": [
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/hall.jpg" }
    },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/counter.jpg" }
    },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/window.jpg" }
    }
  ],
  "resolution": "1080p",
  "duration": 6
}

В личном кабинете (/panel/video) слоты для референсов добавляются по одному, без потолка по количеству; ограничение там одно — суммарный вес вложений до 40 МБ, потому что из панели файлы уходят base64 внутри запроса. Больше — только публичными URL через API.

Video-to-Video (правка видео)

Модели, у которых в каталоге modalities.input содержит "video" (например, flux-video-edit, aleph-2, hailuo-3), принимают исходное видео в input_references с типом video_url. Промпт описывает правку: заменить объект, сменить фон, переосмыслить стиль, освещение и т.п.

URL может быть публичной HTTPS-ссылкой или data URL (data:video/mp4;base64,…). Провайдер принимает только HTTPS для video_url / audio_url — при data URL AITUNNEL сам выкладывает файл во временное хранилище и подставляет публичный URL перед отправкой.

{
  "model": "flux-video-edit",
  "prompt": "Make it look like a vintage hand-painted animation",
  "duration": 8,
  "input_references": [
    {
      "type": "video_url",
      "video_url": { "url": "https://example.com/source.mp4" }
    }
  ]
}

У flux-video-edit выход повторяет длительность, пропорции и звук исходника (клипы до 15 с; вход выше 720p провайдер уменьшает до 720p). duration и size слать не нужно: резерв считается за 15 секунд (максимальная длина исходника), а после завершения списывается реальная стоимость и разница возвращается.

Можно комбинировать исходное видео с image-референсом (стиль / ключевой кадр), если модель это допускает:

{
  "model": "hailuo-3",
  "prompt": "Transfer the motion from the source clip onto this character",
  "size": "1280x720",
  "duration": 6,
  "input_references": [
    {
      "type": "video_url",
      "video_url": { "url": "https://example.com/motion-source.mp4" }
    },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/character.png" }
    }
  ]
}

Видео-референс в Seedance

seedance-2.0, seedance-2.0-fast, seedance-2.0-mini и seedance-2.5 принимают готовый ролик в input_references (type: "video_url") как референс: модель учитывает его содержание и движение, но создаёт новый ролик. Длительность и пропорции выхода задаются явно, как при обычной генерации, и от исходника не зависят: ролик на 10 секунд с "duration": 5 даст 5 секунд результата.

{
  "model": "seedance-2.0-fast",
  "prompt": "Красный автомобиль едет по ночному городу, камера движется так же, как в референсе",
  "resolution": "480p",
  "aspect_ratio": "16:9",
  "duration": 5,
  "input_references": [
    {
      "type": "video_url",
      "video_url": { "url": "https://example.com/source.mp4" }
    }
  ]
}

• Режима редактирования, где выход повторяет длину и пропорции исходника, через API нет. Провайдер включает его сам, если промпт описывает правку существующего ролика («замени автомобиль на красный»), и тогда требует aspect_ratio: "adaptive" и duration: -1 (ошибки «ratio must be adaptive», «duration must be -1»). Эти значения через наш API передать нельзя, мы отклоняем их с ошибкой 400. Описывайте в промпте результат, а не правку исходника.
• duration — из supported_durations модели (4–15 секунд, у seedance-2.5 до 30), aspect_ratio — из supported_aspect_ratios.
• Исходный ролик — от 4 до 30 секунд. У seedance-2.0-fast в кадре должно быть не меньше 407 696 пикселей (854×480 проходит, 320×176 провайдер отклоняет). URL — публичная HTTPS-ссылка или data URL, как в разделе про Video-to-Video.

Резерв. Провайдер считает токены и исходного ролика, а его длину по ссылке мы прочитать не можем, поэтому резерв берётся с запасом на исходник максимальной длины по тарифу «с видео на входе». Например, seedance-2.0-fast, 480p, 16:9, 5 секунд — около 81 ₽ резерва; у seedance-2.5 с теми же параметрами — около 366 ₽. Это верхняя граница, а не цена: после completed списывается фактическая стоимость из usage.cost_rub, остаток возвращается. Если баланса не хватает на резерв, API вернёт 402.

Апскейл видео

Модели с полем upscale_factor (например, flux-video-upscale) увеличивают один исходный ролик, сохраняя длительность. Промпт необязателен (prompt_optional). Исходное видео передайте в input_references с type: "video_url". Масштаб — upscale_factor в диапазоне каталога, режим — creativity (0 Precise / 1 Creative).

{
  "model": "flux-video-upscale",
  "upscale_factor": 2,
  "creativity": 0,
  "input_references": [
    {
      "type": "video_url",
      "video_url": { "url": "https://example.com/source.mp4" }
    }
  ]
}

size и duration не нужны: размер и длительность результата определяет сам исходник, и провайдеру эти поля не уходят (billing_only_parameters). upscale_factor — число в диапазоне каталога; без него берётся максимум.

Резерв считается по самому большому исходнику, который мы принимаем: 15 секунд 1080p, умноженные на upscale_factor по каждой стороне, по тарифу Creative. Для 2× это около 8,3 Мп на кадр. После завершения списывается реальная стоимость, остаток резерва возвращается на баланс.

Passthrough-параметры провайдера

Некоторые модели принимают специфичные опции через поле provider.options.<slug>.parameters:

{
  "model": "veo-3.1",
  "prompt": "A time-lapse of a flower blooming",
  "provider": {
    "options": {
      "google-vertex": {
        "parameters": {
          "personGeneration": "allow",
          "negativePrompt": "blurry, low quality"
        }
      }
    }
  }
}

Разрешённые ключи для каждой модели приходят в поле allowed_passthrough_parameters публичного эндпоинта моделей. Содержимое parameters уходит провайдеру как есть: мы не фильтруем ключи и не проверяем типы значений.

Поэтому ключ не из списка, опечатка в имени или значение неверного типа чаще всего не вызывают ошибку — провайдер молча игнорирует параметр, и вы получаете готовое (и уже оплаченное) видео без ожидаемого эффекта. Сверяйте с документацией провайдера не только имена параметров, но и тип каждого значения. Например, у avatar-iv (HeyGen) expressiveness — это строка high/medium/low, а не число, а caption — объект { "file_format": "srt", "style": "default" }, а не true; со style субтитры вжигаются в кадр, без него отдаётся только отдельный файл субтитров.

Формат ответов

POST /v1/videos — отправка (202 Accepted)

{
  "id": "abc123",
  "polling_url": "https://api.aitunnel.ru/v1/videos/abc123",
  "status": "pending"
}

На этом шаге usage не возвращается — итоговая стоимость известна только после completed.

GET /v1/videos/{id} — статус

Поля расширяются по мере прогресса задачи.

Pending / in_progress:

{
  "id": "abc123",
  "polling_url": "https://api.aitunnel.ru/v1/videos/abc123",
  "status": "in_progress"
}

Completed:

{
  "id": "abc123",
  "polling_url": "https://api.aitunnel.ru/v1/videos/abc123",
  "status": "completed",
  "unsigned_urls": [
    "https://api.aitunnel.ru/v1/videos/abc123/content?index=0"
  ],
  "model": "seedance-2.0-fast",
  "usage": {
    "cost_rub": 47.92
  }
}

Failed:

{
  "id": "abc123",
  "status": "failed",
  "error": "Provider rejected the prompt due to content policy",
  "model": "seedance-2.0-fast",
  "usage": {
    "cost_rub": 0
  }
}

Возможные статусы

Скачивание видео

После completed — используйте либо URL из unsigned_urls[0], либо обращайтесь напрямую к content-эндпоинту:

curl -L "https://api.aitunnel.ru/v1/videos/abc123/content?index=0" \
  -H "Authorization: Bearer sk-aitunnel-xxx" \
  --output video.mp4

Параметр index по умолчанию 0. Используйте другие значения, если модель вернула несколько выходных видео.

Ссылки в unsigned_urls указывают на наш content-эндпоинт и не имеют срока действия с истекающей подписью — они работают, пока задача доступна у нас. Это не временные подписанные ссылки провайдера.

Задачи хранятся у нас 3 месяца, потом завершённые удаляются (списания в истории расходов остаются). Сам файл живёт у провайдера и может стать недоступен раньше, поэтому скачивайте нужное видео сразу, а не рассчитывайте на ссылку как на хранилище.

Прямая ссылка с токеном в URL

Если нужно скачать видео по обычной ссылке без заголовка Authorization (например, чтобы Telegram или браузер могли забрать файл по прямому URL), передайте API-ключ в query-параметре token:

# Без заголовка Authorization — ключ прямо в URL
curl -L "https://api.aitunnel.ru/v1/videos/abc123/content?index=0&token=sk-aitunnel-xxx" \
  --output video.mp4

Такую ссылку можно отдать, например, Telegram Bot API (sendVideo с video=<URL>), который скачает файл сам.

Список задач

Если id потерялся или нужно понять, что ещё выполняется, задачи можно перечислить.

# Только видео, новые сверху
curl "https://api.aitunnel.ru/v1/videos?limit=20" \
  -H "Authorization: Bearer sk-aitunnel-xxx"

# Только те, что ещё держат резерв
curl "https://api.aitunnel.ru/v1/videos?active=true" \
  -H "Authorization: Bearer sk-aitunnel-xxx"

Параметры: status, active=true, limit (до 100), after — id последней задачи предыдущей страницы. Ответ содержит data, has_more и last_id.

Все асинхронные задачи любого типа — видео и Batch — доступны одним запросом:

curl "https://api.aitunnel.ru/v1/jobs?active=true" \
  -H "Authorization: Bearer sk-aitunnel-xxx"

GET /v1/jobs дополнительно отвечает на главный вопрос по деньгам: active_count и active_reserved_rub — сколько задач ещё выполняется и сколько рублей они держат. У каждой записи есть kind (video / batch), reserved_rub, а после расчёта — cost и cost_rub (одно и то же число в рублях) и refunded_rub. GET /v1/jobs/{id} возвращает одну задачу любого типа.

Задачи видны любому ключу своего аккаунта. id задачи из другого аккаунта вернёт 404 — так же, как id другого типа: пакет в /v1/videos/{id} или видео в /v1/batches/{id}. Задачу любого типа отдаёт GET /v1/jobs/{id}.

В личном кабинете

То же самое без кода — на странице Логи → Задачи:

• сколько денег сейчас в резерве и сколько задач выполняется;
• статус каждой задачи, фактическое списание и сумма возврата;
• фильтры по типу и статусу;
• готовое видео можно посмотреть прямо в браузере и скачать, а результаты Batch — выгрузить в JSON.

Списания живут в соседней вкладке «Запросы»: там только фактически потраченное, резервы туда не попадают.

Лучшие практики

• Подробные промпты — указывайте движение, ракурс, освещение, композицию сцены.
• Разумный duration — чем короче, тем дешевле и быстрее. Задавайте явно, чтобы не резервировать максимум.
• Интервал опроса — 15–30 секунд. Генерация занимает от 30 секунд до нескольких минут.
• Не бойтесь прекратить опрос — задачу мы досчитаем сами. Сохраните id и вернитесь за результатом позже; никакого «брошенного» резерва от этого не возникнет.
• Обрабатывайте все терминальные статусы, а не только failed: expired и cancelled для вашего кода означают то же самое — результата нет, деньги вернулись.
• Качество референсов — для image-to-video и reference-to-video используйте изображения с разрешением, близким к выходному size. Для video-to-video исходный клип лучше держать коротким и в том же aspect ratio, что и выход.

Устранение неполадок

Задача надолго зависла в pending?

• Нормально для тяжёлых моделей (veo-3.1 на 1080p) — генерация может занять несколько минут.
• Продолжайте опрос на обычном интервале либо просто вернитесь позже: навсегда задача не зависнет — до expires_at она либо завершится, либо станет expired с полным возвратом резерва.
• Проверить, что именно держит деньги, можно в кабинете: Логи → Задачи показывает все незавершённые задачи и сумму резерва.

402 на POST /v1/videos?

• Не хватает на резерв задачи. error.type — insufficient_balance (баланс) или budget_exceeded (бюджет ключа), в error.metadata — available_rub и required_rub: сколько есть и сколько резервируется.
• Резерв меньше при явном duration и size — см. тарификацию.

504 или 502 на POST /v1/videos?

• Провайдер не принял задачу: не ответил за 60 секунд (504) или ответил ошибкой. Резерв возвращается сразу и полностью — можно повторять. В списке задач такая попытка остаётся со статусом failed и нулевой стоимостью.
• 503 с типом service_unavailable — временный сбой на нашей стороне, ничего не зарезервировано. Повторите через несколько секунд.

404 на GET /v1/videos/{id}/content?

• Видео отдаётся только у задачи в статусе completed. Пока она выполняется, а также после failed / expired / cancelled файла нет.

400 Bad Request на POST /v1/videos?

• Проверьте, что size / resolution / aspect_ratio / duration входят в capability-лист модели (supported_sizes, supported_resolutions, supported_aspect_ratios, supported_durations из эндпоинта моделей).
• Для моделей с supports_input_references: false поле input_references вернёт 400.
• Поле frame_images работает только для моделей с непустым supported_frame_images.

status: "failed"?

• Проверьте поле error — чаще всего это content-policy отказ или недоступное опорное изображение.
• Убедитесь, что все URL в frame_images / input_references публично доступны по HTTPS (или data URL — для video_url / audio_url AITUNNEL сам конвертирует в HTTPS) и в поддерживаемом формате (изображения: JPEG / PNG / WebP; видео: MP4 / WebM / MOV). Для video-to-video модель должна иметь "video" в modalities.input.
• Резерв уже возвращён на баланс — можно смело повторять.

Модель не найдена?

• Используйте ID модели без префикса провайдера (например, seedance-2.0, а не bytedance/seedance-2.0).
• Актуальный список доступен по GET https://api.aitunnel.ru/public/aitunnel/models/videos и на странице моделей.

Видео не обрабатывается в чате?

• Проверьте, что модель поддерживает видео-вход (modalities.input включает "video").
• Если URL не работает, попробуйте base64. У Gemini по ссылке обычно YouTube.
• Проверьте формат файла и что он не повреждён.

Смотрите также

• Понимание видео в чате — раздел выше на этой странице
• Картинки — понимание и генерация изображений
• Аудио — аудио в чате
• Распознавание речи — аудио в текст
• Ошибки и отладка