HappyHorse 1.0

Анимируйте одно или несколько изображений в видео длительностью 3–15 секунд в 720p или 1080p. Изображение обязательно.

• Асинхронная обработка: запрос создания возвращает ID задачи. Видео будет доступно после её успешного завершения.
• Только видео по изображению: images обязательно, от 1 до 9 ссылок. Режима генерации только по тексту нет.
• Ролики длиной 3–15 секунд; duration — целое число секунд.
• Цена зависит от разрешения и запрошенного числа секунд. Задача, завершившаяся ошибкой, не оплачивается.

Открывает модель в API Explorer. Введите свой API-ключ BeatAPI, чтобы создать задачу. Это настоящий запрос: его стоимость спишется с вашего баланса.

Идентификаторы моделей

Обе модели HappyHorse используют один адрес API. Версия 1.0 создаёт видео только по изображению; 1.1 также принимает только текст или референсные изображения. Значения ниже взяты непосредственно из контракта шлюза.

Адрес API и авторизация

POST https://api.beatapi.io/v1/videos/tasks

Передавайте тело запроса в JSON с заголовком Content-Type: application/json. Idempotency-Key необязателен. Для каждого логического запроса используйте уникальное значение длиной не более 255 символов и повторно используйте его только для отправки точно такого же тела. В течение 24 часов повтор с тем же ключом и телом возвращает первый ответ с заголовком Idempotent-Replayed: true. Тот же ключ с другим телом возвращает 409 idempotency_conflict. Ответы, отличные от 2xx, не сохраняются, поэтому повтор после 400 или 402 выполняется заново.

Как выполняется запрос

Режимы ввода

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

Ограничения входных материалов

До создания задачи шлюз проверяет каждый входной материал. Если ограничение нарушено, возвращается 400 bad_request с указанием материала. Средства не списываются.

• При создании задачи шлюз не читает изображения, поэтому для этой модели не проверяются ограничения размера файла, разрешения или формата. Применяются только правила полей, указанные выше.
• Если модель не может скачать или использовать материал по ссылке, уже созданная задача завершается ошибкой, обычно bad_request, либо content_policy_violation при отказе модерации. Средства возвращаются полностью.
• Файл находится на вашем устройстве? Загрузите его через POST /v1/files и передайте полученный data.url. Поддерживаются png, jpg, jpeg и webp до 50 MB.

Параметры, которые модель не принимает

Эти параметры не игнорируются, а отклоняются до списания средств:

• reference_images, reference_videos, reference_audios, generate_audio, seed, quality, sound, task_type, output_format, watermark и другие поля видеомоделей → field "reference_videos" is not supported by model happyhorse-1.0 (с именем переданного поля). Изображения передавайте в images.
• Поле, вообще неизвестное видео-API → unknown field: <name>.

Примеры запросов

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "happyhorse-1.0",
  "prompt": "The singer turns toward the camera and smiles, hair moving in the breeze, warm spotlights",
  "images": [
    "https://cdn.beatapi.io/samples/neon-singer.png"
  ],
  "duration": 5,
  "aspect_ratio": "9:16",
  "resolution": "720p"
}'

Видео по изображению

Вертикальный ролик длиной 5 секунд в 720p по одному изображению.

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "happyhorse-1.0",
  "prompt": "The singer turns toward the camera and smiles, hair moving in the breeze, warm spotlights",
  "images": [
    "https://cdn.beatapi.io/samples/neon-singer.png"
  ],
  "duration": 5,
  "aspect_ratio": "9:16",
  "resolution": "720p"
}'

Несколько изображений

Два изображения передаются модели в порядке списка; результат — ролик длиной 10 секунд в 1080p.

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "happyhorse-1.0",
  "prompt": "The camera pushes in from the bottle on the table to the singer on a neon stage in one continuous move",
  "images": [
    "https://cdn.beatapi.io/samples/smart-bottle.png",
    "https://cdn.beatapi.io/samples/neon-singer.png"
  ],
  "duration": 10,
  "aspect_ratio": "16:9",
  "resolution": "1080p"
}'

Ответы

Создание задачи (201)

Объект задачи. Поле output равно null, пока задача не завершится успешно. Поля с пометкой «во время выполнения» исчезают после завершения задачи.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "video",
    "capability_id": "happyhorse-1.0",
    "capability_version": 1,
    "media_type": "video",
    "model": "happyhorse-1.0",
    "status": "queued",
    "stage": "queued",
    "created_at": 1791993600,
    "updated_at": 1791993600,
    "completed_at": null,
    "poll_after_seconds": 8,
    "output": null,
    "usage": {
      "credits_reserved": 0.7,
      "credits_settled": 0,
      "credits_refunded": 0,
      "credits_charged": 0.7,
      "billable_duration_seconds": 5
    },
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": null,
    "error_message": null
  }
}

Успешно завершённая задача

GET /v1/tasks/{task_id} возвращает HTTP 200 со status: "succeeded" и результатом в data.output.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "video",
    "capability_id": "happyhorse-1.0",
    "capability_version": 1,
    "media_type": "video",
    "model": "happyhorse-1.0",
    "status": "succeeded",
    "stage": "succeeded",
    "created_at": 1791993600,
    "updated_at": 1791993690,
    "completed_at": 1791993690,
    "output": {
      "media": [
        {
          "type": "video",
          "url": "https://media.beatapi.io/outputs/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ/0.mp4",
          "mime_type": "video/mp4"
        }
      ],
      "r2_url": "https://media.beatapi.io/outputs/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ/0.mp4"
    },
    "usage": {
      "credits_reserved": 0.7,
      "credits_settled": 0.7,
      "credits_refunded": 0,
      "credits_charged": 0.7,
      "billable_duration_seconds": 5
    },
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": null,
    "error_message": null
  }
}

Поля результата

Задача, завершившаяся ошибкой

Если задача завершилась ошибкой, GET /v1/tasks/{task_id} всё равно возвращает HTTP 200: сведения об ошибке находятся в теле ответа. Зарезервированная сумма возвращается полностью, поэтому списания нет.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "video",
    "capability_id": "happyhorse-1.0",
    "capability_version": 1,
    "media_type": "video",
    "model": "happyhorse-1.0",
    "status": "failed",
    "stage": "failed",
    "created_at": 1791993600,
    "updated_at": 1791993690,
    "completed_at": 1791993690,
    "output": null,
    "usage": {
      "credits_reserved": 0.7,
      "credits_settled": 0,
      "credits_refunded": 0.7,
      "credits_charged": 0,
      "billable_duration_seconds": 5
    },
    "retryable": true,
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": "processing_failed",
    "error_message": "The task failed during processing on our side. Retry; a failed task is refunded."
  }
}

Полный пример

Создайте задачу, дождитесь её завершения с интервалом опроса, указанным сервером, и выведите ссылки на результаты. Задайте BEATAPI_API_KEY в переменной окружения и установите requests.

import os
import time
import uuid
import requests
API = "https://api.beatapi.io"
HEADERS = {"Authorization": f"Bearer {os.environ['BEATAPI_API_KEY']}"}
def create_task(body: dict) -> dict:
    # One Idempotency-Key per logical request: a retry with the same key cannot create a second task.
    headers = {**HEADERS, "Idempotency-Key": str(uuid.uuid4())}
    for attempt in range(3):
        response = requests.post(f"{API}/v1/videos/tasks", headers=headers, json=body, timeout=60)
        if response.status_code in (429, 503) and attempt < 2:
            time.sleep(int(response.headers.get("Retry-After", 10)))
            continue
        break
    try:
        payload = response.json()
    except ValueError:  # an edge error page is not JSON
        response.raise_for_status()
        raise
    if not response.ok:
        error = payload["error"]
        raise RuntimeError(f"{response.status_code} {error['code']}: {error['message']} (request_id={error.get('request_id')})")
    return payload["data"]
def wait_for_task(task_id: str, timeout_seconds: int = 1800) -> dict:
    deadline = time.monotonic() + timeout_seconds
    while time.monotonic() < deadline:
        response = requests.get(f"{API}/v1/tasks/{task_id}", headers=HEADERS, timeout=30)
        if response.status_code == 429 or response.status_code >= 500:
            time.sleep(int(response.headers.get("Retry-After", 10)))
            continue
        response.raise_for_status()
        task = response.json()["data"]
        if task["status"] in ("succeeded", "failed"):
            return task
        time.sleep(task.get("poll_after_seconds", 5))
    raise TimeoutError(f"task {task_id} is still running; keep polling later")
task = create_task({
  "model": "happyhorse-1.0",
  "prompt": "The singer turns toward the camera and smiles, hair moving in the breeze, warm spotlights",
  "images": [
    "https://cdn.beatapi.io/samples/neon-singer.png"
  ],
  "duration": 5,
  "aspect_ratio": "9:16",
  "resolution": "720p"
})
print("created", task["id"])
task = wait_for_task(task["id"])
if task["status"] == "failed":
    raise SystemExit(f"{task['error_code']}: {task['error_message']}")
for item in task["output"]["media"]:
    print(item["url"])

Оплата

• Эти цены действуют после появления модели в списке. До этого запрос создания отклоняется без списания средств.
• Цена зависит от разрешения и запрошенного числа секунд (duration, либо 5, если параметр не указан). Секунда в 1080p дороже, чем в 720p. aspect_ratio и число изображений на цену не влияют.
• В таблице ниже указана цена 8-секундных роликов. Другая длительность оплачивается посекундно по тому же тарифу выбранного разрешения.
• Цена резервируется при создании задачи. Поле data.usage.billable_duration_seconds показывает длительность, по которой она рассчитана.
• Если задача завершилась ошибкой, в том числе из-за модерации после отправки, средства возвращаются полностью.

Текущие базовые цены совпадают с указанными на странице цен. Если для аккаунта согласована скидка, стоимость будет ниже. Фактически списанная сумма всегда указана в data.usage задачи.

Частые ошибки

Краткий справочник HTTP-ошибок

Ошибки до создания задачи возвращаются с HTTP-статусом, отличным от 2xx, без списания средств. Обрабатывайте error.code или error.retryable; причина указана в message. Полный список и правила повторов приведены в разделе ошибок.

{
  "error": {
    "code": "bad_request",
    "message": "\"prompt\" is required",
    "retryable": false,
    "request_id": "req_5f0c2a9e4b7d4e31"
  }
}