Генерация видео API: задачи, статус и результат
Видео по тексту или картинке. Одни модели отвечают сразу, другие создают задачу, а готовый файл можно получить отдельным запросом.
Обзор
Результат зависит от модели. Часть моделей отвечает сразу: код 200 и готовое видео в теле ответа. Остальные создают задачу: код 202 и идентификатор, по которому проверяется статус и забирается файл.
Для создания задачи и проверки её статуса передайте ключ в заголовке Authorization: Bearer или x-api-key. Статус задачи видят все ключи одного аккаунта.
Создание задачи
POST https:// принимает запрос на видео. Если модель создаёт задачу, шлюз сразу отвечает кодом 202, идентификатором и статусом queued.
Шлюз читает поля model и duration_seconds (целое число секунд от 1 до 600). Если длительность не указана, берётся длительность по умолчанию для модели. Остальное, например prompt, уходит модели без изменений.
У модели без длительности по умолчанию поле duration_seconds обязательно, иначе ответ 400.
Пример запроса и ответа.
curl https://relay-llm.ru/v1/videos \
-H "Authorization: Bearer $RELAY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "MODEL_ID",
"prompt": "A fox runs through fresh snow at dawn",
"duration_seconds": 8
}'Вместо MODEL_ID подставьте идентификатор модели из каталога. Примеры читают ключ из переменной окружения RELAY_API_KEY, адрес API уже подставлен.
{
"id": "019976a0-5b3c-7d4e-9f01-0123456789ab",
"status": "queued"
}Синхронный ответ
Если POST / вернул 200, видео готово в этом ответе. Закодированные байты находятся в data[0].b64_json; идентификатора задачи и ссылки на файл при таком ответе нет.
Сохраните тело ответа в video.json. Скопируйте код ниже в save_video.py в той же папке, затем запустите python3 save_video.py в macOS/Linux или py save_video.py в Windows.
JSON
{
"created": 1758700000,
"data": [
{
"b64_json": "AAAAIGZ0eXBpc29tAAACAGlz..."
}
],
"usage": {
"video_seconds": 8
}
}Python
import base64
import json
from pathlib import Path
response = json.loads(Path("video.json").read_text(encoding="utf-8"))
encoded = response["data"][0]["b64_json"]
Path("video.mp4").write_bytes(base64.b64decode(encoded))Статус задачи
GET https:// показывает задачу. Запрос не стоит денег и не обращается к модели: статус хранится у нас.
| Статус | Что значит |
|---|---|
queued | Задача принята и ждёт запуска. |
running | Видео генерируется. |
completed | Видео готово. Используйте GET / до expires_at. |
failed | Задача не выполнена. В ответе есть объект error с кодом: request_timeout, если задача не уложилась в 30 минут, иначе upstream_error. Поле error.type здесь всегда api_error, в том числе для request_timeout. |
Скрипт Python создаёт асинхронную задачу и опрашивает её до статуса completed или failed. Он рассчитан на модель, которая отвечает кодом 202: для модели с синхронным ответом используйте сохранение из предыдущего раздела. Укажите RELAY_API_KEY и MODEL_ID в окружении.
running
{
"id": "019976a0-5b3c-7d4e-9f01-0123456789ab",
"status": "running",
"created_at": "2026-10-01T12:00:00Z"
}completed
{
"id": "019976a0-5b3c-7d4e-9f01-0123456789ab",
"status": "completed",
"created_at": "2026-10-01T12:00:00Z",
"completed_at": "2026-10-01T12:04:10Z",
"video_seconds": 8,
"content_url": "https://relay-llm.ru/v1/videos/019976a0-5b3c-7d4e-9f01-0123456789ab/content",
"expires_at": "2026-10-02T12:04:10Z"
}failed
{
"id": "019976a0-5b3c-7d4e-9f01-0123456789ab",
"status": "failed",
"created_at": "2026-10-01T12:00:00Z",
"error": {
"type": "api_error",
"code": "upstream_error",
"message": "Video generation failed upstream. See https://relay-llm.ru/docs/errors#upstream_error",
"request_id": "019976a0-5b3c-7d4e-9f01-0123456789ab"
}
}Python
import json
import os
import time
from urllib.request import Request, urlopen
base_url = "https://relay-llm.ru/v1"
headers = {
"Authorization": f"Bearer {os.environ['RELAY_API_KEY']}",
"Content-Type": "application/json",
}
def send(method, path, body=None):
request = Request(base_url + path, data=body, headers=headers, method=method)
with urlopen(request) as response:
return json.load(response)
payload = json.dumps({
"model": os.environ["MODEL_ID"],
"prompt": "A fox runs through fresh snow at dawn",
"duration_seconds": 8,
}).encode("utf-8")
job = send("POST", "/videos", payload)
if job.get("status") != "queued":
raise RuntimeError("this model answers at once, save the video from the response body")
while True:
status = send("GET", f"/videos/{job['id']}")
if status["status"] == "completed":
print(base_url + f"/videos/{job['id']}/content")
break
if status["status"] == "failed":
raise RuntimeError(status["error"]["code"])
time.sleep(2)Опрашивайте статус с паузой в несколько секунд. Запросы статуса идут в окне служебных методов, 120 запросов в минуту на ключ, и лимит запросов к моделям не тратят. Неизвестный или чужой идентификатор даёт ответ 404 с кодом not_found.
Готовый файл
Готовое видео выдаёт GET https://. Передайте тот же ключ в заголовке Authorization или x-api-key.
У части моделей статус задачи и content доступны 30 минут после создания. У остальных моделей видео хранится отдельно, его срок задаёт expires_at. После истечения соответствующего срока приходит 404 с кодом not_found. Файл поддерживает диапазоны (Range), а один ключ может читать его до 60 раз в минуту.
Оплата
Видео оплачивается за секунду готового ролика по цене из каталога. Резерв при создании задачи считается по заказанной длительности и подчиняется тому же правилу, что и для текста.
Статус failed не обещает бесплатный запрос. Сверьте фактическое списание в истории usage и балансе.
Генерация видео станет доступна, когда сумма оплаченных пополнений достигнет $10. До этого запрос получит 402 с кодом new_account_limit. Приветственный бонус не учитывается.