> 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. # API эффектов > Создайте асинхронную задачу эффекта для изображения или видео, используя версию эффекта BeatAPI. `POST https://api.beatapi.io/v1/effects/tasks` Создайте асинхронную задачу эффекта для изображения или видео, используя версию эффекта BeatAPI. ## Авторизация `Authorization`   `string`   **обязательный** Передавайте API-ключ BeatAPI как токен Bearer. Создать ключ можно в [панели управления](https://beatapi.io/dashboard). ``` Authorization: Bearer ``` Храните постоянные API-ключи на доверенных серверах. Для тела запроса обязателен `Content-Type: application/json`. Если метод принимает `Idempotency-Key`, этот заголовок необязателен, но рекомендуется для безопасных повторных попыток с точно таким же телом. ## Тело запроса `effect_id`   `string`   **обязательный** Постоянный опубликованный ID эффекта из `GET /v1/effects`. --- `effect_version`   `integer`   **необязательный** Необязательная неизменяемая версия. Если не указана, используется текущая опубликованная версия. **Диапазон:** x >= 1 --- `images`   `string[]`   **обязательный** Общедоступные HTTPS-ссылки на входные изображения в порядке, требуемом выбранной версией эффекта. Точное число и ограничения медиа приведены в `GET /v1/effects/{effect_id}`. Локальные файлы загружайте через `POST /v1/files`. **Количество:** 1 – 7 элементов --- `options`   `object`   **необязательный** Необязательные настройки, поддерживаемые выбранной версией эффекта. Не передавайте неподдерживаемые настройки; ориентируйтесь на каталог. --- `options.aspect_ratio`   `string`   **необязательный** Соотношение сторон результата, если выбранный эффект поддерживает эту настройку. --- `options.resolution`   `string`   **необязательный** Разрешение результата, если выбранный эффект поддерживает эту настройку. --- `options.duration`   `integer`   **необязательный** Длительность видео в секундах, если выбранный эффект поддерживает эту настройку. --- `options.bgm`   `boolean`   **необязательный** Добавить фоновую музыку, если выбранный эффект это поддерживает. --- `options.seed`   `integer`   **необязательный** Необязательное начальное значение генератора для воспроизводимости, если выбранный эффект его поддерживает. ## Ответ Успешный запрос возвращает HTTP `201`. ```json { "data": { "id": "task_effect123", "object": "task", "task_kind": "effect", "capability_id": "video-muscle-max", "capability_version": 1, "effect_id": "video-muscle-max", "effect_version": 1, "status": "queued", "stage": "queued", "created_at": 1782210000, "updated_at": 1782210000, "completed_at": null, "output": null, "usage": { "credits_reserved": 1.2, "credits_charged": 1.2, "credits_settled": 0, "credits_refunded": 0 }, "request_id": "req_effect123", "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 `; ключ работает с префиксом `sk-` и без него. Повторять без исправления не следует. | | `402` | Недостаточно средств (`insufficient_credits`): баланс равен нулю или меньше стоимости запроса. Пополните баланс, затем отправьте запрос снова. До пополнения повтор не поможет. | | `403` | Операция запрещена ключу или аккаунту (`forbidden`): например, модель недоступна за счёт регистрационного бонуса (пополнение открывает доступ), IP-адрес не входит в разрешённый список ключа или модель недоступна его группе. Повторять без исправления не следует. | | `404` | Эффект или запрошенная версия недоступны (`not_found`). | | `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. |