Видеогенерация

ZvenoAI предоставляет OpenAI-совместимый видео-API: один эндпоинт, одна авторизация, оплата в рублях. Если у выбранного провайдера сбой — запрос автоматически уходит к резервному, а с баланса списывается только фактическая стоимость.

Как это устроено

В отличие от чат-комплишена видеогенерация асинхронна: ни один провайдер в индустрии не отдаёт видео синхронно — генерация занимает от десятков секунд до нескольких минут. ZvenoAI унифицирует жизненный цикл задачи в три шага.

Быстрый старт

import os, time, requests

BASE = "https://api.zveno.ai"
KEY = os.environ["ZVENO_API_KEY"]
H = {"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"}

# 1. Отправка задачи
job = requests.post(f"{BASE}/v1/videos", headers=H, json={
    "model": "openai/sora-2",
    "prompt": "Wide shot of a child flying a red kite at sunset",
    "size": "1280x720",
    "duration": 8,
}).json()
print("отправлено:", job["id"], job["status"])

# 2. Опрос (терминальные статусы: completed | failed)
while job["status"] in ("pending", "in_progress"):
    time.sleep(5)
    job = requests.get(job["polling_url"], headers=H).json()
    print("статус:", job["status"])

if job["status"] != "completed":
    raise SystemExit(f"{job['status']}: {job.get('error') or '—'}")

# 3. Скачивание
video_url = job["unsigned_urls"][0]
with requests.get(video_url, headers=H, stream=True) as r:
    with open("output.mp4", "wb") as f:
        for chunk in r.iter_content(1 << 20):
            f.write(chunk)

print(f"готово. стоимость: {job['usage']['cost']} RUB")

const BASE = 'https://api.zveno.ai'
const KEY = process.env.ZVENO_API_KEY
const H = { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' }

// 1. Отправка задачи
let job = await fetch(`${BASE}/v1/videos`, {
  method: 'POST',
  headers: H,
  body: JSON.stringify({
    model: 'openai/sora-2',
    prompt: 'Wide shot of a child flying a red kite at sunset',
    size: '1280x720',
    duration: 8,
  }),
}).then((r) => r.json())

// 2. Опрос (терминальные статусы: completed | failed)
while (['pending', 'in_progress'].includes(job.status)) {
  await new Promise((r) => setTimeout(r, 5000))
  job = await fetch(job.polling_url, { headers: H }).then((r) => r.json())
}
if (job.status !== 'completed') throw new Error(`${job.status}: ${job.error ?? '—'}`)

// 3. Скачивание
const res = await fetch(job.unsigned_urls[0], { headers: H })
const fs = await import('node:fs')
const { Readable } = await import('node:stream')
const { pipeline } = await import('node:stream/promises')
await pipeline(Readable.fromWeb(res.body), fs.createWriteStream('output.mp4'))

console.log(`готово. стоимость: ${job.usage.cost} RUB`)

# 1. Отправка задачи
JOB=$(curl -sS https://api.zveno.ai/v1/videos \
  -H "Authorization: Bearer $ZVENO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/sora-2","prompt":"a child flying a red kite","size":"1280x720","duration":8}')

JOB_ID=$(echo "$JOB" | jq -r .id)

# 2. Опрос (терминальные статусы: completed | failed)
while :; do
  STATUS=$(curl -sS "https://api.zveno.ai/v1/videos/$JOB_ID" \
    -H "Authorization: Bearer $ZVENO_API_KEY" | jq -r .status)
  echo "статус: $STATUS"
  case "$STATUS" in completed|failed) break ;; esac
  sleep 5
done

# 3. Скачивание (только если completed)
[[ "$STATUS" == "completed" ]] && curl -fsS "https://api.zveno.ai/v1/videos/$JOB_ID/content" \
  -H "Authorization: Bearer $ZVENO_API_KEY" \
  -o output.mp4

Поиск моделей

Идентификатор модели — всегда в формате vendor/model (например, openai/sora-2, google/veo-3.1). Найти подходящую модель можно двумя способами:

Поля видеомодели

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

Разрешения

Соотношения сторон

Использование изображений

Многие модели принимают изображения как часть подсказки. Поддерживаются два разных режима — у них разный смысл и не пересекающаяся семантика.

Генерация из изображения (frame_images)

Задаёт первый и/или последний кадр, провайдер достраивает движение между ними. Подходит для оживления статичной картинки или плавного перехода между двумя сценами.

{
  "model": "google/veo-3.1",
  "prompt": "transitioning from morning to night over the same valley",
  "frame_images": [
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/morning.png" },
      "frame_type": "first_frame"
    },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/night.png" },
      "frame_type": "last_frame"
    }
  ],
  "resolution": "1080p"
}

Какие frame_type доступны для конкретной модели — в её поле supported_frame_images. Значение null означает, что генерация из кадра не поддерживается.

Стилевые референсы (input_references)

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

{
  "model": "google/veo-3.1",
  "prompt": "a colossal solar flare beside a planet",
  "input_references": [
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/style-ref.png" }
    }
  ],
  "resolution": "1080p"
}

Передача параметров провайдеру

Каждый провайдер поддерживает свой набор расширенных параметров — например, negativePrompt, personGeneration, enhancePrompt у Google Veo. ZvenoAI готов пробрасывать их через provider.options.<provider-slug>.parameters, но допускает только параметры из белого списка модели — поля allowed_passthrough_parameters в каталоге.

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

Выбор провайдера

Если одна и та же модель доступна у нескольких провайдеров, ZvenoAI по умолчанию выбирает одного из них случайно с весом, обратно пропорциональным квадрату цены — в среднем дешевле, но не «всегда самый дешёвый», чтобы распределять нагрузку.

Поведение настраивается блоком provider.preferences (совместим с OpenRouter):

{
  "model": "openai/sora-2-pro",
  "prompt": "...",
  "provider": {
    "preferences": {
      "order": ["openrouter", "together"],
      "only": ["openrouter"],
      "ignore": ["together"],
      "sort": "price",
      "max_price": { "video": 500.0 },
      "allow_fallbacks": true
    }
  }
}

Реакция на сбой провайдера

Если провайдер только что вернул ошибку, ZvenoAI понижает его приоритет (но не блокирует) примерно на 30 секунд и пробует следующего. Это уменьшает p99-задержку без жёстких health-проверок.

Жизненный цикл задачи

отправка → pending → in_progress → completed  ─→  готово к скачиванию
                                 └→ failed    ─→  возврат средств

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

Ответ на отправку (202 Accepted)

{
  "id": "vj_5f3a2c8e",
  "polling_url": "https://api.zveno.ai/v1/videos/vj_5f3a2c8e",
  "status": "pending"
}

Ответ опроса (200 OK, статус completed)

{
  "id": "vj_5f3a2c8e",
  "polling_url": "https://api.zveno.ai/v1/videos/vj_5f3a2c8e",
  "status": "completed",
  "generation_id": "vj_5f3a2c8e",
  "unsigned_urls": ["https://api.zveno.ai/v1/videos/vj_5f3a2c8e/content"],
  "usage": {
    "cost": 87.5,
    "is_byok": false
  }
}

Ответ опроса при ошибке

{
  "id": "vj_8a1b...",
  "polling_url": "https://api.zveno.ai/v1/videos/vj_8a1b...",
  "status": "failed",
  "error": "content policy violation: requested content is not allowed"
}

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

GET /v1/videos/{id}/content стримит MP4. Заголовок Range пробрасывается к провайдеру:

# скачать первый мегабайт (например, чтобы прочитать заголовок видео)
curl -sS https://api.zveno.ai/v1/videos/vj_5f3a2c8e/content \
  -H "Authorization: Bearer $ZVENO_API_KEY" \
  -H "Range: bytes=0-1048575" \
  -o head.mp4

Если провайдер поддерживает Range, сервер ответит 206 Partial Content с Content-Range — HTML5-плеер сможет перематывать видео по таймлайну и возобновлять прерванные загрузки. Если провайдер Range не поддерживает, придёт обычный 200 OK с полным телом.

Биллинг и стоимость

Стоимость видео в рублях зависит от параметров генерации: длительности, разрешения и наличия аудио. Цена не за токены — это явное отличие от чата. Конкретные ставки за секунду по моделям и провайдерам — в каталоге /models (фильтр «Видео»).

Каждой паре «модель + провайдер» сопоставлено правило биллинга в одном из двух режимов:

• Native. Стоимость считается по фактической цене провайдера за выполненную задачу. Источник цены — поле usage.cost из ответа провайдера.
• Manual. Стоимость считается по фиксированной ставке в рублях за секунду, умноженной на длительность. Используется, когда провайдер не возвращает фактическую цену, либо для нормализации по моделям.

Биллинг двухфазный:

1. Резерв. При отправке задачи маршрутизатор выбирает первого подходящего провайдера и резервирует на счёте оценочную стоимость по параметрам запроса (duration, resolution, generate_audio) и применённому правилу. Если средств не хватает — пробуется следующий по приоритету. Когда ни один из кандидатов не проходит проверку баланса, ответ 402 insufficient_funds ещё до похода к провайдеру.
2. Списание / возврат. После completed резерв заменяется итоговой стоимостью, рассчитанной по тому же правилу с фактическими параметрами и usage.cost провайдера; при failed сумма возвращается полностью.

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

Видео-эндпоинты возвращают тот же envelope, что и остальной API — см. Обработку ошибок. Тело:

{
  "error": {
    "code": 404,
    "message": "video is not ready yet"
  }
}

При upstream-ошибках провайдера (502/503) в error.metadata приходит provider_name и raw — формат описан в разделе Provider error.

Provider moderation

Провайдеры видеогенерации могут отказать в обработке запроса по своим content policy. Чаще всего это:

• фото реальных людей в input_references или frame_images (privacy);
• сцены, защищённые авторским правом (узнаваемые персонажи, кадры из фильмов);
• запрещённый контент в промпте (sexual, violence и пр.).

Отказы приходят в одной из двух форм — в зависимости от того, когда провайдер обнаружил проблему:

• Submit-time — провайдер отверг запрос ещё до старта генерации (как правило, по входным данным: privacy на изображениях, запрещённый промпт). POST /v1/videos сразу возвращает HTTP 400 с заполненным error.metadata.provider_name и error.metadata.raw, где провайдер отдаёт свой код в raw.error.code:

  {
    "error": {
      "code": 400,
      "message": "Provider rejected input: image may contain a real person",
      "metadata": {
        "provider_name": "openrouter",
        "raw": {
          "error": {
            "code": "InputImageSensitiveContentDetected.PrivacyInformation",
            "message": "The request failed because the input image may contain a real person"
          }
        }
      }
    }
  }

• Async — провайдер обнаружил нарушение уже после 202 Accepted (например, фильтр авторских прав на сгенерированный видеоряд). POST отвечает успешно, а узнаёте о проблеме при опросе: GET /v1/videos/{id} отдаёт status: "failed" и причину в строковом поле error ответа задачи (это строка, а не envelope — см. пример ответа при ошибке). Структурированный metadata.raw для пост-202 отказов пока не заполняется — ориентируйтесь на текст и перезапускайте с изменённым промптом/входом.

Известные классы кодов (формат и имя зависят от провайдера — не закладывайтесь на конкретные значения, используйте для логов и подбора реакции):

Парсинг submit-time ошибки в клиенте (учитывает, что формат raw зависит от провайдера и не гарантирован):

resp = requests.post(f"{BASE}/v1/videos", headers=H, json=body)
if resp.status_code == 400:
    err = resp.json().get("error") or {}
    meta = err.get("metadata") or {}
    raw = meta.get("raw") if isinstance(meta.get("raw"), dict) else {}
    raw_err = raw.get("error") if isinstance(raw, dict) else None
    if not isinstance(raw_err, dict):
        raw_err = {}
    code = str(raw_err.get("code") or "")  # провайдер может отдать int — нормализуем
    if code.startswith("InputImageSensitiveContent"):
        raise SystemExit("замените изображение — провайдер заблокировал по privacy/контенту")
    print(f"{meta.get('provider_name')} вернул {code or '?'}: "
          f"{raw_err.get('message') or err.get('message')}")

Хорошие практики

• Подробный промпт. Описывайте сцену, ракурс, освещение, движение камеры. Видео-модели чувствительнее к деталям, чем чат-модели.
• Адекватное разрешение. Чем выше — тем дольше генерация и дороже. Для предпросмотра запускайте 720p, для финального результата — 1080p/4K.
• Интервал опроса. 5–10 секунд обычно достаточно: воркер ZvenoAI всё равно ходит к провайдеру с собственным rate-limit'ом, более частые запросы клиента не ускорят результат.
• Обработка ошибок. Терминальные статусы — только completed и failed. При failed поле error несёт причину; резерв возвращается автоматически — повторная попытка списывает заново.
• Фиксация провайдера на повторных запусках. Для воспроизводимости в проде используйте provider.preferences.only, чтобы seed имел смысл (между провайдерами он не переносится).
• Контроль стоимости. Если у проекта есть ценовой потолок на видео — задавайте provider.preferences.max_price.video, чтобы маршрутизатор отказался дороже лимита (503), а не списал больше ожидаемого.

Решение типичных проблем

Чего пока нет

• Webhook-уведомления — только опрос через GET /v1/videos/{id}.
• Несколько видео на одну задачу — index > 0 вернёт 400.
• Specialized-эндпоинты провайдеров (remix, extend, lipsync) пока не проксируются.
• Удаление задач — DELETE /v1/videos/{id} пока не реализован.

SDK

Видео-API не входит в официальный OpenAI SDK (openai.videos ходит только к OpenAI). Используйте обычный HTTP-клиент: на большинстве языков ~30 строк кода покрывают отправку, опрос статуса и скачивание (см. быстрый старт).

Что дальше

• Список эндпоинтов и схемы запросов
• Каталог видеомоделей на сайте
• Каталог видеомоделей через API
• Маршрутизация и предпочтения провайдеров