Effect API | BeatAPI API Documentation

curl -X POST https://api.beatapi.io/v1/effects/tasks \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "effect_id": "video-muscle-max",
  "images": [
    "https://media.beatapi.io/samples/portrait.png"
  ],
  "options": {
    "resolution": "720p",
    "duration": 12
  }
}'

{
  "data": {
    "id": "task_effect123",
    "object": "task",
    "task_kind": "effect",
    "capability_id": "video-muscle-max",
    "capability_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,
    "effect_id": "video-muscle-max",
    "effect_version": 1
  }
}

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

Before creating a task, read the Effect catalog to confirm image count, output type, supported options, and version. If an input is local, upload a local input. Save data.id, poll the Task, and follow the error and retry policy.

Create an asynchronous image or video Effect task using a versioned BeatAPI effect. Before creating a task, read the Effect catalog to confirm image count, output type, supported options, and version. If an input is local, [upload a local input](/quick-guide#upload-an-input-file). Save `data.id`, [poll the Task](/quick-guide#get-task-status), and follow the [error and retry policy](/quick-guide#errors-and-retry-policy).

Authentication

AuthorizationBearer

Send your API key as Authorization: Bearer <BEATAPI_API_KEY>.

Request

This endpoint expects an object.

effect_idstringRequired

Stable published Effect ID from GET /v1/effects.

imageslist of stringsRequired

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.

effect_versionintegerOptional>=1

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

optionsobjectOptional

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

Response

Effect task accepted

dataobject

Accepted or current BeatAPI task state.

Errors

400

Bad Request Error

401

Unauthorized Error

402

Payment Required Error

404

Not Found Error

409

Conflict Error

429

Too Many Requests Error

Authentication

Headers

Request

Response

Errors