Видео

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

Запросы с видео идут в 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). Для таких моделей size обязателен — по нему считается точный резерв, а кадр больше max_output_megapixels мы отклоняем с ошибкой 400. Учтите, что min_price_per_second / max_price_per_second у них равны потолку, а не реальной цене вашего запроса.

• В момент отправки задачи мы резервируем максимальную возможную стоимость запроса (worst-case) на вашем балансе. Резерв — это не списание: пока задача не завершилась, деньги удержаны, но ещё не потрачены, и в истории расходов их нет.
• Когда задача завершается (completed), мы списываем фактическую стоимость и возвращаем разницу на баланс.
• Если задача упала (failed), истекла (expired) или была отменена провайдером (cancelled) — вся зарезервированная сумма возвращается автоматически, а списания не появляется вообще.
• Больше зарезервированной суммы с вас не спишут никогда. Если провайдер выставил нам больше — разницу оплачиваем мы.
• Расчёт делает сервер, а не ваш опрос: каждую минуту планировщик проверяет незавершённые задачи, поэтому резерв освобождается сам — даже если вы больше не обращались к API.
• У каждой задачи есть жёсткий срок (поле expires_at, три часа для видео). Если к этому времени провайдер не отдал результат, задача переводится в expired и резерв возвращается полностью. Зависнуть в pending навсегда задача не может.
• Итоговая стоимость в рублях приходит в поле usage.cost_rub ответа 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):

• Разрешения: 480p, 720p, 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 — заметно больше.

{
  "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 обязателен — по нему считается резерв (5,1 ₽/сек) — но провайдеру не уходит (billing_only_parameters). size слать не нужно.

Можно комбинировать исходное видео с 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" }
    }
  ]
}

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

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

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

Два обязательных параметра:

• size — размер результата (исходные размеры, умноженные на upscale_factor). По нему считается стоимость, поэтому без него запрос вернёт 400, а кадр больше max_output_megapixels (4K для flux-video-upscale) отклоняется. Хотите 3× — берите исходник не больше 720p.
• duration — длительность исходного ролика: supported_durations пустой, потому что модель сохраняет длительность, а не выбирает её.

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

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 публичного эндпоинта моделей. Всё, что не входит в этот список, будет отфильтровано и залогировано, но не приведёт к ошибке.

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

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",
  "generation_id": "gen-1234567890-abcdef",
  "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_rub и refunded_rub. GET /v1/jobs/{id} возвращает одну задачу любого типа.

Задачи доступны только владельцу ключа: чужой id вернёт 404.

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

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

• сколько денег сейчас в резерве и сколько задач выполняется;
• статус каждой задачи, фактическое списание и сумма возврата;
• фильтры по типу и статусу;
• готовое видео можно посмотреть прямо в браузере и скачать, а результаты 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, sora-2-pro на 1080p) — генерация может занять несколько минут.
• Продолжайте опрос на обычном интервале либо просто вернитесь позже: навсегда задача не зависнет — до expires_at она либо завершится, либо станет expired с полным возвратом резерва.
• Проверить, что именно держит деньги, можно в кабинете: Статистика → Задачи показывает все незавершённые задачи и сумму резерва.

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.
• Проверьте формат файла и что он не повреждён.

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

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