Effect API

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

Create an asynchronous image or video Effect task using a versioned BeatAPI effect.

Authorization

Authorization   string   required

Send your BeatAPI API key as a Bearer token. Create one on the Dashboard.

Authorization: Bearer <BEATAPI_API_KEY>

Keep permanent API keys on trusted servers. Content-Type: application/json is required for the request body. Idempotency-Key is optional when the endpoint exposes it and is recommended for safe retries with the exact same body.

Request body

effect_id   string   required

Stable published Effect ID from GET /v1/effects.

effect_version   integer   optional

Optional immutable version. Omit to use the current published version.

Range: x >= 1

images   string[]   required

Public HTTPS input images in the order required by the selected Effect version. Read GET /v1/effects/{effect_id} for the exact count and accepted media rules; upload local files with POST /v1/files.

Count: 1 to 7 items

options   object   optional

Optional controls supported by the selected Effect version. Omit unsupported controls; the catalog is the source of truth.

options.aspect_ratio   string   optional

Requested output aspect ratio when the selected Effect exposes this option.

options.resolution   string   optional

Requested output resolution when the selected Effect exposes this option.

options.duration   integer   optional

Requested video duration in seconds when the selected Effect exposes this option.

options.bgm   boolean   optional

Include background music when supported by the selected Effect.

options.seed   integer   optional

Optional deterministic seed when supported by the selected Effect.

Response

A successful request returns HTTP 201.

1
{
2
  "data": {
3
    "id": "task_effect123",
4
    "object": "task",
5
    "task_kind": "effect",
6
    "capability_id": "video-muscle-max",
7
    "capability_version": 1,
8
    "effect_id": "video-muscle-max",
9
    "effect_version": 1,
10
    "status": "queued",
11
    "stage": "queued",
12
    "created_at": 1782210000,
13
    "updated_at": 1782210000,
14
    "completed_at": null,
15
    "output": null,
16
    "usage": {
17
      "credits_reserved": 1.2,
18
      "credits_charged": 1.2,
19
      "credits_settled": 0,
20
      "credits_refunded": 0
21
    },
22
    "request_id": "req_effect123",
23
    "error_code": null,
24
    "error_message": null
25
  }
26
}

Next step

Save data.id from the accepted response and poll GET /v1/tasks/{task_id} every 5–10 seconds until status is succeeded or failed. Read finished assets from data.output.media.

Errors