> 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 영상 API

> BeatAPI 영상 생성 모델의 지원 입력 방식, 길이, 해상도, 오디오 제어, 모델별 요청 계약을 비교합니다.

# 영상 API

안정적인 BeatAPI 모델 ID로 비동기 영상 생성 작업을 하나 만듭니다.

| 모델                                                                | 입력 모드                                | 필수 필드                                 | 주요 설정                                                        |
| ----------------------------------------------------------------- | ------------------------------------ | ------------------------------------- | ------------------------------------------------------------ |
| [`minimax-h3`](/video-api/minimax-h3)                             | 원래 ID이며 Fast 계약과 가격을 유지              | `model`, `prompt`                     | 4–15초, 최대 2K                                                 |
| [`minimax-h3-fast`](/video-api/minimax-h3-fast)                   | `minimax-h3`의 명시적 Fast 별칭            | `model`, `prompt`                     | 원래 ID와 입력 제한·가격 동일                                           |
| [`minimax-h3-normal`](/video-api/minimax-h3-normal)               | 더 느리고 저렴한 텍스트, 프레임 또는 시각 참조          | `model`, `prompt`                     | 5–15초, 480p/768p/1080p, 네이티브 오디오, 오디오 입력 없음                  |
| [`grok-imagine-video-1.5`](/video-api/grok-imagine-video-1-5)     | 텍스트, 첫 프레임, 최대 7장의 참조 이미지            | `model`, `prompt`                     | 1–15초, 480p/720p/1080p, 1080p는 이미지 최대 1장                     |
| [`seedance-2`](/video-api/seedance-2)                             | 텍스트, 첫/마지막 프레임, 멀티모달 참조              | `model`, `prompt`                     | 4–15초, 최대 4K, 생성 오디오                                         |
| [`seedance-2-fast`](/video-api/seedance-2-fast)                   | 텍스트, 첫/마지막 프레임, 멀티모달 참조              | `model`, `prompt`                     | 4–15초, 480p/720p, 생성 오디오                                     |
| [`seedance-2-mini`](/video-api/seedance-2-mini)                   | 텍스트, 첫/마지막 프레임, 멀티모달 참조              | `model`, `prompt`                     | 4–15초, 480p/720p, `generate_audio` 필드 없음                     |
| [`veo-3.1`](/video-api/veo-3-1)                                   | 텍스트, 첫/마지막 프레임, 참조 이미지               | `model`, `prompt`                     | `duration` 필드 없음, `quality` Quality/Fast/Lite, 720p/1080p/4K |
| [`seedance-2.5`](/video-api/seedance-2-5)                         | 텍스트, 첫/마지막 프레임, 더 큰 멀티모달 참조 구성       | `model`, `prompt`                     | 4–30초, 480p/720p/1080p, 생성 오디오와 시드                           |
| [`kling-v3`](/video-api/kling-v3)                                 | 텍스트, 첫/마지막 프레임, 멀티샷, 재사용 가능한 요소      | `model`, `prompt`                     | 3–15초, `std`(720p) 또는 `pro`(1080p), 선택적 소리                   |
| [`kling-v4`](/video-api/kling-v4)                                 | 텍스트, 시간순 프레임, 참조 이미지·영상·음성, 이름 있는 요소 | `model`, `prompt`                     | 3–30초, 720p/1080p, 오디오 항상 생성                                 |
| [`kling-2.6-motion-control`](/video-api/kling-2-6-motion-control) | 업로드한 인물 이미지 1장 + 업로드한 동작 영상 1개       | `model`, `images`, `reference_videos` | 3–30초 동작 영상, 720p/1080p, 초 단위 과금                             |
| [`kling-3-motion-control`](/video-api/kling-3-motion-control)     | 방향과 배경 제어가 있는 동작 전이                  | `model`, `images`, `reference_videos` | 3–30초 동작 영상, 720p/1080p, 초 단위 과금                             |
| [`wan-3.0`](/video-api/wan-3-0)                                   | 텍스트, 첫 프레임, 참조 영상과 오디오               | `model`, `prompt`                     | 2–30초, 480p/720p/1080p                                       |
| [`wan-3.0-prime`](/video-api/wan-3-0-prime)                       | Wan 3.0과 같은 입력, 별도 모델 ID와 가격         | `model`, `prompt`                     | 4–30초, 480p/720p/1080p                                       |
| [`happyhorse-1.0`](/video-api/happyhorse-1-0)                     | 이미지로 영상 생성만 가능, 최대 9개 소스 각도          | `model`, `prompt`, `images`           | 3–15초, 720p/1080p                                            |
| [`happyhorse-1.1`](/video-api/happyhorse-1-1)                     | 1.0과 같은 계약, 더 낮은 초당 요금               | `model`, `prompt`, `images`           | 3–15초, 720p/1080p                                            |
| [`gemini-omni-1.1-flash`](/video-api/gemini-omni-1-1-flash)       | 텍스트, 첫/마지막 프레임, 참조 이미지와 선택적 참조 영상    | `model`, `prompt`                     | 3–10초, 720p/1080p/4K, 소리 항상 생성                               |
| [`gemini-omni-1.2-flash`](/video-api/gemini-omni-1-2-flash)       | 텍스트, 첫/마지막 프레임, 참조 이미지와 선택적 참조 영상    | `model`, `prompt`                     | 3–15초, 720p/1080p/4K, 소리 항상 생성                               |
| [`minimax-h3-max`](/video-api/minimax-h3-max)                     | 텍스트, 첫 프레임, 첫 프레임과 마지막 프레임           | `model`, `prompt`                     | 5–15초, 480P/768P/1080P, 시드                                   |
| [`minimax-h3-max-turbo`](/video-api/minimax-h3-max-turbo)         | H3 Max와 같은 계약                        | `model`, `prompt`                     | 5–15초, 480P/768P/1080P, 초당 요금 절반                             |

필드, 기본값, 열거값, 조합 규칙, 요청 예시, 응답, 오류 동작은 각 모델 페이지에서 확인하세요.

## 사용 가능한 모델 목록

`GET /v1/media/models`

| 파라미터         | 위치 | 타입     | 필수  | 허용 값             |
| ------------ | -- | ------ | --- | ---------------- |
| `media_type` | 쿼리 | string | 아니요 | `image`, `video` |

이 공개 엔드포인트는 인증이 필요하지 않습니다.

```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"]
      }
    ]
  }
}
```

| 필드            | 타입        | 의미                                             |
| ------------- | --------- | ---------------------------------------------- |
| `id`          | string    | 고정된 공개 모델 별칭                                   |
| `object`      | string    | `generation_model`                             |
| `name`        | string    | 표시 이름                                          |
| `media_type`  | string    | `image` 또는 `video`                             |
| `input_modes` | string\[] | `text`, `image`, `frames`, `reference` 중 하나 이상 |

내부 라우팅은 공개 계약에 포함되지 않습니다.

## 공통 생성 계약

`POST /v1/videos/tasks`

| 헤더                | 타입     | 필수      | 규칙                          |
| ----------------- | ------ | ------- | --------------------------- |
| `Authorization`   | string | 예       | `Bearer <BEATAPI_API_KEY>`  |
| `Content-Type`    | string | 예       | `application/json`          |
| `Idempotency-Key` | string | 아니요, 권장 | 최대 255자. 논리적 생성 요청 하나당 키 하나 |

본문은 정확히 하나의 모델 스키마와 일치해야 합니다. `model`이 구분자이며, 알 수 없는 필드는 거부됩니다.

```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"
  }'
```

유효한 요청은 `data.id`, `task_kind="video"`, 선택한 `model`, `status="queued"`, 사용량 지표, `request_id`와 함께 `201 Created`를 반환합니다. `succeeded` 또는 `failed`가 될 때까지 5\~10초마다 `GET /v1/tasks/{task_id}`를 폴링하세요. 성공한 영상은 `data.output.media[]`와 `data.output.r2_url`에 있습니다.

완전히 같은 멱등 재요청은 이미 접수된 작업을 반환합니다. 같은 키를 다른 본문으로 재사용하면 `409 idempotency_conflict`가 반환됩니다.

## 공통 오류

| HTTP  | 공통 코드                                                                                            | 클라이언트 조치                                    |
| ----- | ------------------------------------------------------------------------------------------------ | ------------------------------------------- |
| `400` | `bad_request`                                                                                    | 필드, 값, 조합, 개수 또는 미디어 URL을 수정하세요             |
| `400` | `content_policy_violation`                                                                       | 프롬프트나 입력을 바꾸세요. 그대로 다시 보내지 마세요              |
| `401` | `missing_api_key` / `invalid_api_key`                                                            | Bearer 키를 보내거나, 잘못되었거나 만료·비활성화·소진된 키를 교체하세요 |
| `402` | `insufficient_credits`                                                                           | 새 작업을 만들기 전에 충전하세요                          |
| `403` | `forbidden`                                                                                      | 이 키나 계정에 허용되지 않습니다. 예: 무료 크레딧으로 쓸 수 없는 모델   |
| `409` | `idempotency_conflict`                                                                           | 본문이 완전히 같을 때만 키를 재사용하세요                     |
| `429` | `rate_limit_exceeded`                                                                            | `Retry-After`를 따르세요                         |
| `500` | `internal_error`                                                                                 | 백오프를 두고 한 번 재시도하세요                          |
| `503` | `processing_unavailable` / `processing_timeout` / `processing_failed` / `result_transfer_failed` | 백오프를 두고 재시도하세요. 비용은 청구되지 않았습니다              |

오류 응답에는 `error.code`, 영어 `error.message`, `error.retryable`, `error.request_id`, 그리고 `429`일 때 `error.retry_after_seconds`가 포함됩니다. 접수된 뒤 실패한 작업도 조회하면 `200`을 반환하며, 실패 코드는 `data.error_code`에 있습니다. 모든 코드와 재시도 규칙은 [오류](/errors)를 참고하세요. 실제로 적용되는 요청 계약은 아래 각 모델 페이지에 있습니다.