> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# Рекламное видео товара

> Создайте задачу Ecommerce Video из изображений товара, явно указав длительность результата.

`POST https://api.beatapi.io/v1/ecommerce-video/tasks`

Создайте задачу Ecommerce Video из изображений товара, явно указав длительность результата.

## Авторизация

`Authorization`   `string`   **обязательный**

Передавайте API-ключ BeatAPI как токен Bearer. Создать ключ можно в [панели управления](https://beatapi.io/dashboard).

```
Authorization: Bearer <BEATAPI_API_KEY>
```

Храните постоянные API-ключи на доверенных серверах. Для тела запроса обязателен `Content-Type: application/json`. Если метод принимает `Idempotency-Key`, этот заголовок необязателен, но рекомендуется для безопасных повторных попыток с точно таким же телом.

## Тело запроса

`images`   `string[]`   **обязательный**

Сначала основное изображение товара или сцены, затем до шести дополнительных общедоступных HTTPS-ссылок на PNG, JPEG или WebP с товаром либо его использованием. Локальные файлы загрузите через `POST /v1/files` и используйте возвращённый `data.url`.

**Количество:** 1 – 7 элементов

---

`duration`   `integer`   **обязательный**

Обязательная длительность готового видео в секундах; используется для расчёта стоимости в USD. Допустимый диапазон — 10-60 секунд.

**Диапазон:** 10 – 60

---

`prompt`   `string`   **необязательный**

Необязательные указания по идее, аудитории, преимуществу товара, предложению, тону, сценам или призыву к действию. Максимум 2000 символов.

**Длина:** не более 2000 символов

---

`aspect_ratio`   `enum<string>`   **необязательный**

Формат размещения видео: 16:9 для горизонтального, 9:16 для вертикальных соцсетей, 1:1 для квадратного. Задайте явно, чтобы компоновка была предсказуемой.

**Допустимые значения:** `16:9`, `9:16`, `1:1`

---

`language`   `enum<string>`   **необязательный**

Язык диалогов и закадрового текста. `en` — английский, `zh` — китайский. Задавайте явно, если промпт содержит несколько языков.

**Допустимые значения:** `en`, `zh`

## Ответ

Успешный запрос возвращает HTTP `201`.

```json
{
  "data": {
    "id": "task_p9Lm2",
    "object": "task",
    "task_kind": "workflow",
    "capability_id": "ecommerce-video",
    "capability_version": 1,
    "workflow": "ecommerce-video",
    "status": "queued",
    "stage": "queued",
    "created_at": 1782210000,
    "updated_at": 1782210000,
    "completed_at": null,
    "output": null,
    "usage": {
      "credits_reserved": 4.5,
      "credits_charged": 4.5,
      "billable_duration_seconds": 15,
      "credits_settled": 0,
      "credits_refunded": 0
    },
    "request_id": "req_def456",
    "error_code": null,
    "error_message": null
  }
}
```

## Следующий шаг

Сохраните `data.id` из ответа о принятии задачи и опрашивайте `GET /v1/tasks/{task_id}` каждые 5–10 секунд, пока `status` не станет `succeeded` или `failed`. Готовые файлы находятся в `data.output.media`.

## Ошибки

| Статус | Значение                                                                                                                                                                                                                                                                                      |
| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Некорректный JSON либо недопустимое поле, значение или сочетание параметров (`bad_request`; сообщение указывает поле), либо входные данные отклонены модерацией (`content_policy_violation`). Повтор без изменений не поможет.                                                                |
| `401`  | Ключ не передан (`missing_api_key`), неверен, просрочен, отключён или исчерпал лимит (`invalid_api_key`; точная причина указана в сообщении). Передавайте `Authorization: Bearer <key>`; ключ работает с префиксом `sk-` и без него. Повторять без исправления не следует.                    |
| `402`  | Недостаточно средств (`insufficient_credits`): баланс равен нулю или меньше стоимости запроса. Пополните баланс, затем отправьте запрос снова. До пополнения повтор не поможет.                                                                                                               |
| `403`  | Операция запрещена ключу или аккаунту (`forbidden`): например, модель недоступна за счёт регистрационного бонуса (пополнение открывает доступ), IP-адрес не входит в разрешённый список ключа или модель недоступна его группе. Повторять без исправления не следует.                         |
| `409`  | В течение 24 часов `Idempotency-Key` уже использован с другим телом или путём запроса либо первый запрос с этим ключом ещё выполняется (`idempotency_conflict`). Повтор без изменений не поможет.                                                                                             |
| `429`  | Слишком много запросов (`rate_limit_exceeded`, в том числе лимит бесплатной модели). Повторите через число секунд из `Retry-After` (также указано в `error.retry_after_seconds`).                                                                                                             |
| `500`  | Непредвиденная внутренняя ошибка (`internal_error`). Запрос можно повторить; если ошибка сохраняется, сохраните `request_id` для поддержки.                                                                                                                                                   |
| `503`  | Запрос не удалось выполнить (`processing_unavailable`, `processing_timeout`, `processing_failed` или `result_transfer_failed`). Средства не списаны. Повторяйте с увеличивающейся задержкой; у 503 нет заголовка `Retry-After` и поля `retry_after_seconds`. BeatAPI не возвращает 502 и 504. |