> 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.

# BeatAPI Video API

> Compare BeatAPI video generation models, supported input modes, durations, resolutions, audio controls, and model-specific request contracts.

# Video API

Create one asynchronous video generation task with a stable BeatAPI model ID.

| Model                                                             | Input modes                                                                     | Required fields                       | Main controls                                                   |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------- | --------------------------------------------------------------- |
| [`minimax-h3`](/video-api/minimax-h3)                             | Original ID, retains Fast contract and prices                                   | `model`, `prompt`                     | 4–15s, up to 2K                                                 |
| [`minimax-h3-fast`](/video-api/minimax-h3-fast)                   | Explicit Fast alias of `minimax-h3`                                             | `model`, `prompt`                     | Same input limits and prices as the original ID                 |
| [`minimax-h3-normal`](/video-api/minimax-h3-normal)               | Slower, half-price text, frames, or visual references                           | `model`, `prompt`                     | 5–15s; 480p/768p/1080p; native audio, no audio input            |
| [`grok-imagine-video-1.5`](/video-api/grok-imagine-video-1-5)     | Text, first frame, up to seven reference images                                 | `model`, `prompt`                     | 1–15s, 480p/720p/1080p; 1080p accepts at most one image         |
| [`seedance-2`](/video-api/seedance-2)                             | Text, first/last frames, multimodal references                                  | `model`, `prompt`                     | 4–15s, up to 4K, generated audio                                |
| [`seedance-2-fast`](/video-api/seedance-2-fast)                   | Text, first/last frames, multimodal references                                  | `model`, `prompt`                     | 4–15s, 480p/720p, generated audio                               |
| [`seedance-2-mini`](/video-api/seedance-2-mini)                   | Text, first/last frames, multimodal references                                  | `model`, `prompt`                     | 4–15s, 480p/720p, no `generate_audio` field                     |
| [`veo-3.1`](/video-api/veo-3-1)                                   | Text, first/last frames, reference images                                       | `model`, `prompt`                     | No `duration` field; `quality` Quality/Fast/Lite; 720p/1080p/4K |
| [`seedance-2.5`](/video-api/seedance-2-5)                         | Text, first/last frames, larger multimodal reference sets                       | `model`, `prompt`                     | 4–30s, 480p/720p/1080p, generated audio and seed                |
| [`kling-v3`](/video-api/kling-3)                                  | Text, first/last frames, multi-shot, reusable elements                          | `model`, `prompt`                     | 3–15s, `std` (720p) or `pro` (1080p), optional sound            |
| [`kling-v4`](/video-api/kling-v4)                                 | Text, frames in time order, reference images, videos and voices, named elements | `model`, `prompt`                     | 3–30s, 720p/1080p, audio always generated                       |
| [`kling-2.6-motion-control`](/video-api/kling-2-6-motion-control) | One uploaded character image + one uploaded motion video                        | `model`, `images`, `reference_videos` | 3–30s motion video, 720p/1080p, billed per second               |
| [`kling-3-motion-control`](/video-api/kling-3-motion-control)     | Motion transfer with orientation and background controls                        | `model`, `images`, `reference_videos` | 3–30s motion video, 720p/1080p, billed per second               |
| [`wan-3.0`](/video-api/wan-3-0)                                   | Text, first frame, reference videos and audio                                   | `model`, `prompt`                     | 2–30s, 720p/1080p                                               |
| [`wan-3.0-prime`](/video-api/wan-3-0-prime)                       | Same inputs as Wan 3.0, on a faster queue                                       | `model`, `prompt`                     | 2–30s, 720p/1080p, same price as Wan 3.0                        |
| [`happyhorse-1.0`](/video-api/happyhorse-1-0)                     | Image to video only, up to nine source angles                                   | `model`, `prompt`, `images`           | 3–15s, 720p/1080p                                               |
| [`happyhorse-1.1`](/video-api/happyhorse-1-1)                     | Same contract as 1.0 at a lower per-second rate                                 | `model`, `prompt`, `images`           | 3–15s, 720p/1080p                                               |
| [`minimax-h3-max`](/video-api/minimax-h3-max)                     | Text, first frame, first and last frames                                        | `model`, `prompt`                     | From 5s, 480P/768P, seed                                        |
| [`minimax-h3-max-turbo`](/video-api/minimax-h3-max-turbo)         | Same contract as H3 Max                                                         | `model`, `prompt`                     | From 5s, 480P/768P, half the per-second rate                    |

Open the matching model page for every field, default, enum, combination rule, request example, response, and error behavior.

## List available models

`GET /v1/media/models`

| Parameter    | Location | Type   | Required | Allowed values   |
| ------------ | -------- | ------ | -------- | ---------------- |
| `media_type` | Query    | string | No       | `image`, `video` |

This public endpoint does not require authentication.

```bash
curl "https://api.beatapi.io/v1/media/models?media_type=video"
```

```json
{
  "data": {
    "object": "list",
    "data": [
      {
        "id": "minimax-h3",
        "object": "generation_model",
        "name": "MiniMax H3",
        "media_type": "video",
        "input_modes": ["text", "frames", "reference"]
      }
    ]
  }
}
```

| Field         | Type      | Meaning                                       |
| ------------- | --------- | --------------------------------------------- |
| `id`          | string    | Stable public model alias                     |
| `object`      | string    | `generation_model`                            |
| `name`        | string    | Display name                                  |
| `media_type`  | string    | `image` or `video`                            |
| `input_modes` | string\[] | Any of `text`, `image`, `frames`, `reference` |

Internal provider routing is not part of the public contract.

## Shared create contract

`POST /v1/videos/tasks`

| Header            | Type   | Required        | Rules                                            |
| ----------------- | ------ | --------------- | ------------------------------------------------ |
| `Authorization`   | string | Yes             | `Bearer <BEATAPI_API_KEY>`                       |
| `Content-Type`    | string | Yes             | `application/json`                               |
| `Idempotency-Key` | string | No, recommended | Up to 255 characters; one key per logical create |

The body must match exactly one model schema. `model` is the discriminator; unknown fields are rejected.

```bash
curl https://api.beatapi.io/v1/videos/tasks \
  -X POST \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Idempotency-Key: video-seedance-2-5-001" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5",
    "prompt": "A cinematic tracking shot through a rain-lit night market.",
    "duration": 5,
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }'
```

A valid request returns `201 Created` with `data.id`, `task_kind="video"`, the selected `model`, `status="queued"`, usage metrics, and `request_id`. Poll `GET /v1/tasks/{task_id}` every 5–10 seconds until `succeeded` or `failed`; successful video is in `data.output.media[]` and `data.output.r2_url`.

An exact idempotent replay returns the accepted task. Reusing a key with a different body returns `409 idempotency_conflict`.

## Shared errors

| HTTP  | Common code                                                                                      | Client action                                                                          |
| ----- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
| `400` | `bad_request`                                                                                    | Fix fields, values, combinations, counts, or media URLs                                |
| `400` | `content_policy_violation`                                                                       | Change the prompt or input; do not resend unchanged                                    |
| `401` | `missing_api_key` / `invalid_api_key`                                                            | Send the Bearer key, or replace a wrong, expired, disabled, or exhausted one           |
| `402` | `insufficient_credits`                                                                           | Top up before creating a new task                                                      |
| `403` | `forbidden`                                                                                      | Not allowed for this key or account — for example a model not available on free credit |
| `409` | `idempotency_conflict`                                                                           | Reuse the key only with the exact same body                                            |
| `429` | `rate_limit_exceeded`                                                                            | Honor `Retry-After`                                                                    |
| `500` | `internal_error`                                                                                 | Retry once with backoff                                                                |
| `503` | `processing_unavailable` / `processing_timeout` / `processing_failed` / `result_transfer_failed` | Retry with backoff; nothing was charged                                                |

Error responses include `error.code`, an English `error.message`, `error.retryable`, `error.request_id`, and `error.retry_after_seconds` on a `429`. A task that fails after it was accepted is still read with `200`: see `data.error_code` and [Errors](/errors) for every code and retry rule. The per-model pages below are the production request contracts.