Видео в API

Создайте задачу

Видео готовится минуты, поэтому запрос не ждёт результата. POST /v1/tasks принимает описание и сразу возвращает задачу, а ролик вы забираете позже. Модели с видео отдаёт GET /v1/models?type=video.

curl https://epicai.ru/v1/tasks \
  -H "Authorization: Bearer sk-epic-ВАШ_КЛЮЧ" \
  -H "Idempotency-Key: clip-0001" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling",
    "prompt": "Кошка идёт по подоконнику, за окном дождь",
    "parameters": {
      "scenario": "t2v",
      "engine": "v3",
      "quality": "std",
      "duration": 5,
      "aspect_ratio": "16:9"
    }
  }'

Ответ 201 содержит задачу. Заголовок Location ведёт на её адрес.

{
  "id": "task_7fa4be5e14351e3dff994aa3",
  "object": "task",
  "type": "video",
  "model": "kling",
  "status": "in_progress",
  "created_at": 1793114499,
  "started_at": 1793114499,
  "finished_at": null,
  "price": {"tokens": 75000, "charged": 0},
  "parameters": {"scenario": "t2v", "engine": "v3", "quality": "std", "duration": 5,
                 "aspect_ratio": "16:9", "sound": false, "shots_mode": "off"}
}

В price.tokens стоит цена в TOK, она зафиксирована при создании и зарезервирована на балансе целиком. В parameters видно, с какими значениями работает задача, включая подставленные по умолчанию. Заголовок Idempotency-Key защищает от двойного запуска. Повтор с тем же ключом и телом вернёт ту же задачу с кодом 200.

Заберите готовый ролик

Опрашивайте GET /v1/tasks/{id}, пока статус queued или in_progress. Чаще раза в 3 секунды спрашивать не нужно, на видео хватает паузы в 10 секунд.

import os
import time
import requests

API = "https://epicai.ru/v1"
headers = {"Authorization": "Bearer " + os.environ["EPICAI_API_KEY"]}

created = requests.post(
    API + "/tasks",
    headers={**headers, "Idempotency-Key": "clip-0001"},
    json={
        "model": "kling",
        "prompt": "Кошка идёт по подоконнику, за окном дождь",
        "parameters": {"scenario": "t2v", "quality": "std", "duration": 5},
    },
    timeout=60,
)
created.raise_for_status()
task_id = created.json()["id"]

while True:
    time.sleep(10)
    task = requests.get(API + "/tasks/" + task_id, headers=headers, timeout=60).json()
    if task["status"] == "succeeded":
        print(task["output"][0]["url"])
        break
    if task["status"] == "failed":
        print(task["error"]["code"], task["error"]["message"])
        break

У готовой задачи в output лежит файл mp4 с полями type, url, mime и bytes, а в price.charged списанная сумма. Ссылка открывается без ключа и действует 7 суток, срок записан в expires_at. Скачайте ролик сразу.

Время работы зависит от модели и длины ролика. Пятисекундный ролик готовится от пары минут до десяти и дольше. Задача, не закончившаяся за 100 минут, получает статус failed с кодом task_timeout. Опрос можно заменить вебхуком. Для этого добавьте в запрос webhook_url, а подпись и повторы объясняет статья Вебхуки. Все статусы и поля задачи собраны в статье Задачи.

У ключа может быть не больше 20 задач в работе. Двадцать первая даёт 429 too_many_active_tasks с заголовком Retry-After: 10, подробнее в статье Лимиты.

Выберите сценарий

Параметр scenario определяет, что создаёт модель, и от него зависят остальные параметры и входные файлы. Таблица показывает сценарии модели kling.

Сценарий	Что делает	Входные файлы
t2v	Видео по описанию	не нужны
i2v	Оживляет картинку	одна картинка — первый кадр
frames	Переход между двумя кадрами	две картинки — первый и последний кадр
refs	Видео по референсам	до 7 картинок
restyle	Перерисовывает видео	одно видео и до 4 картинок
motion	Переносит движение с видео на персонажа	одно видео и одна картинка

У других моделей набор сценариев свой, например v2v или avatar. Список лежит в parameters.properties.scenario.enum описания модели, а сколько файлов нужно каждому сценарию — в поле inputs_by. Оно показывает максимум по каждому виду файлов, например {"image": 2, "video": 0, "audio": 0} для frames. Если не хватает первого кадра или исходного видео, запрос получит 400 invalid_input с подсказкой, что добавить.

Сценарий avatar есть у модели omnihuman-2-0 (OmniHuman 2.0). Ему нужны одна фотография человека в images и одна запись речи или песни в audios, WAV или MP3 длиной от 4 секунд до 5 минут. Описание в prompt необязательно. Длину ролика задаёт запись, поэтому цена зависит от её длины.

Прочтите схему параметров

Схема в parameters описания модели содержит пометки, которые связывают параметры между собой. Они же объясняют, почему значение недопустимо.

Поле схемы	Что значит
enum, default, minimum, maximum	Допустимые значения, значение по умолчанию и границы чисел
x-enum-titles	Названия значений, как на сайте. У quality значение std подписано «720p»
x-affects-price	Параметр меняет цену
x-show-if	Параметр действует, только если другие параметры имеют перечисленные значения. У duration это сценарии t2v, i2v, frames и refs. Когда условие не выполнено, запрос параметр принимает, но в задаче и цене его нет
x-options-by	Допустимые значения зависят от другого параметра. Версия engine зависит от scenario, качество quality от версии

Если параметр не указан, берётся значение по умолчанию, подогнанное под остальные. Для motion версия станет mc. Сочетание, которое схема не допускает, например версию turbo со сценарием refs, отклоняет 400 invalid_parameter. Поле param называет проблемный параметр, например parameters.engine.

Передайте исходные файлы

Файлы идут в полях images, videos и audios запроса, по строке на файл. Картинка — ссылка http(s) или data:image/png;base64,…, до 10 МБ. Видео и запись — ссылка или data:video/mp4;base64,… и data:audio/mpeg;base64,….

{
  "model": "kling",
  "prompt": "Перерисуй как акварельный мультфильм",
  "parameters": {"scenario": "restyle", "engine": "omni", "quality": "std"},
  "videos": ["https://example.com/source.mp4"]
}

Тело запроса не больше 12 МБ, поэтому видео передавайте ссылкой. Видео и записи epicai скачивает на свой сервер сам, меряет длительность и кладёт временную копию, которая стирается по завершении задачи.

Ссылка должна быть публичной. Адреса внутренних сетей, порты кроме 80 и 443 и ссылки с логином не принимаются. Допустимые типы и размеры зависят от модели. Для kling в сценариях restyle и motion исходное видео должно длиться от 3 до 30 секунд. Несоответствие и слишком большой файл дают 400 invalid_input. Тело запроса больше 12 МБ даёт 413 request_too_large.

Узнайте цену до запуска

Цена зависит от параметров, а у части сценариев ещё и от длины исходных файлов. Перерисовка видео стоит пропорционально секундам исходника, оживление аватара — секундам записи. Модели с такой ценой помечены pricing.depends_on_inputs: true. Узнать сумму без запуска помогает POST /v1/quote. Файлы в нём можно заменить секундами числом.

curl https://epicai.ru/v1/quote \
  -H "Authorization: Bearer sk-epic-ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling",
    "parameters": {"scenario": "restyle", "engine": "omni", "quality": "std"},
    "videos": [10]
  }'

Ответ содержит price.tokens и price.base (цена без акции), а также parameters с подставленными умолчаниями. Без длины файла цену не посчитать, и запрос получит 400 unsupported_parameters. Примеры цен по типичным сочетаниям лежат в pricing.examples описания модели. Как считается цена и почему она не меняется после запуска, рассказывает статья Цена задачи.

Если ролик не получился, резерв снимается и TOK не списываются.

Оживите картинку в Midjourney

Модель midjourney-video принимает одну картинку в images и за одну задачу отдаёт четыре ролика. Параметр resolution принимает 480p (125 000 TOK) и 720p (400 000 TOK). Чтобы потом продолжить или улучшить ролик, создайте его операцией video модели midjourney, см. статью Операции над готовым результатом.

Чего нет в API

Раскадровки вручную и персонажей-элементов Kling. Параметр shots_mode принимает только off и auto, полей для кадров и элементов нет, и запрос с ними вернёт 400 invalid_parameter.