---
canonical_url: "https://docs.composio.dev/toolkits/beatapi"
markdown_url: "https://docs.composio.dev/toolkits/beatapi.md"
product: "platform"
version: null
last_updated: null
---

# BeatAPI

BeatAPI provides asynchronous APIs for AI image and video generation, video analysis, music and ecommerce video workflows, file uploads, usage, and webhooks.

- **Category:** ai content generation
- **Auth:** API_KEY
- **Composio-managed OAuth available?** N/A
- **Tools:** 10
- **Triggers:** 0
- **Slug:** `BEATAPI`
- **Version:** 00000000_00

## Tools

### Create Ecommerce Video Task

**Slug:** `BEATAPI_CREATE_ECOMMERCE_VIDEO_TASK`

Start a paid asynchronous BeatAPI product-ad video task from uploaded product images, and return its task ID for status polling.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `images` | array | Yes | One to seven BeatAPI-hosted HTTPS product or lifestyle image URLs. Put the primary product or scene image first. |
| `prompt` | string | No | Optional creative direction, audience, product benefit, offer, tone, scenes, or call to action, up to 2,000 characters. |
| `duration` | integer | Yes | Requested output duration in seconds, from 10 to 60. |
| `language` | string ("en" | "zh") | No | Language for generated dialogue and narration: en for English or zh for Chinese. |
| `aspect_ratio` | string ("16:9" | "9:16" | "1:1") | No | Output placement: 16:9 landscape, 9:16 vertical, or 1:1 square. |
| `idempotency_key` | string | No | Stable unique key for safe retries of this paid request. Reuse it only with the identical request body. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Image Generation Task

**Slug:** `BEATAPI_CREATE_IMAGE_GENERATION_TASK`

Start a paid asynchronous BeatAPI image generation task with one exact model-specific contract, and return its task ID for status polling.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `generation` | string | Yes | Complete request for one image model. Include model and prompt, then only the controls supported by that model. |
| `idempotency_key` | string | No | Stable unique key for safe retries of this paid request. Reuse it only with an identical generation request. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Video Analysis Task

**Slug:** `BEATAPI_CREATE_VIDEO_ANALYSIS_TASK`

Start a paid asynchronous analysis of an account-owned uploaded video and return its task ID for status polling.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | Question or analysis instructions for the video, from 1 to 12,000 characters. |
| `video_url` | string | Yes | BeatAPI-hosted MP4 or MOV URL returned by Upload File for the connected account. The verified video duration may be at most 600 seconds. |
| `analysis_depth` | string ("standard" | "deep") | No | Reasoning depth. Standard is the lower-cost default; deep may cost more and take longer. |
| `idempotency_key` | string | No | Stable unique key for safe retries of this paid request. Reuse it only with the identical request body. |
| `max_output_tokens` | integer | No | Requested maximum answer budget in tokens, from 256 to 8,192. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Video Generation Task

**Slug:** `BEATAPI_CREATE_VIDEO_GENERATION_TASK`

Start a paid asynchronous BeatAPI video generation task with an exact model-specific request. Save the returned task ID and use Get Task to poll until succeeded or failed.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `generation` | string | Yes | Exact model-specific video request. Select a model and provide only the controls exposed by that variant. |
| `idempotency_key` | string | No | Stable unique key for safe retries of this paid request. Reuse it only with the identical request body. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Task

**Slug:** `BEATAPI_GET_TASK`

Read the current status, stage, storyboard, output, usage, or failure details for one asynchronous BeatAPI task. This performs one status read, not an automatic polling loop. When polling, wait 5-10 seconds with jitter between calls, stop at succeeded or failed, and honor Retry-After on rate limits.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `task_id` | string | Yes | Task ID returned by a BeatAPI task-creation tool. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Usage

**Slug:** `BEATAPI_GET_USAGE`

Get the connected account's USD balance, task totals, concurrency, and usage breakdowns before or after paid work.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `period` | string ("24h" | "7d" | "30d" | "all") | No | Window ending now for counts and breakdowns; all covers the account's complete history. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Effects

**Slug:** `BEATAPI_LIST_EFFECTS`

List currently published image and video effects with each effect's exact input and option contract.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `category` | string | No | Return only effects in this provider-defined category. |
| `output_type` | string ("image" | "video") | No | Return only effects that produce this media type. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Generation Models

**Slug:** `BEATAPI_LIST_GENERATION_MODELS`

List currently available image and video generation models, optionally filtered by media type, before creating a generation task.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `media_type` | string ("image" | "video") | No | Return only image or video models; omit to return both types. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Workflows

**Slug:** `BEATAPI_LIST_WORKFLOWS`

List BeatAPI's available high-level workflows and what each workflow produces.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Upload File

**Slug:** `BEATAPI_UPLOAD_FILE`

Upload an image, audio file, subtitle file, or short video to BeatAPI and return an account-owned URL for generation or analysis inputs.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `file` | object | Yes | File to upload. Supported formats are PNG, JPEG, WebP, MP3, WAV, AAC, M4A, MP4, MOV, and SRT. Images, audio, and subtitles may be up to 50 MB; motion videos may be up to 100 MB. |
| `purpose` | string | No | Upload purpose; BeatAPI currently accepts only input. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |