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

# 영상 분석

> 업로드한 MP4 또는 MOV를 standard 또는 deep 타임스탬프 인식 멀티모달 추론으로 분석합니다.

`POST https://api.beatapi.io/v1/video-analysis/tasks`

업로드한 MP4 또는 MOV를 standard 또는 deep 타임스탬프 인식 멀티모달 추론으로 분석합니다.

## 인증

`Authorization`   `string`   **필수**

BeatAPI API 키를 Bearer 토큰으로 보내세요. 키는 [대시보드](https://beatapi.io/dashboard)에서 만들 수 있습니다.

```
Authorization: Bearer <BEATAPI_API_KEY>
```

영구 API 키는 신뢰할 수 있는 서버에만 보관하세요. 요청 본문에는 `Content-Type: application/json`이 필요합니다. `Idempotency-Key`는 엔드포인트가 지원하는 경우 선택 사항이며, 완전히 같은 본문으로 안전하게 재시도하려면 사용하는 것이 좋습니다.

## 요청 본문

`video_url`   `string`   **필수**

현재 계정에서 POST /v1/files가 반환한 BeatAPI 호스팅 MP4 또는 MOV 입력 URL입니다. 검증된 최대 길이는 600초입니다.

**형식:** `uri`

---

`prompt`   `string`   **필수**

분석 지시문입니다. 시간 정밀도가 중요하면 타임스탬프가 있는 출력을 요청하세요.

**길이:** 1\~12000자

---

`analysis_depth`   `enum<string>`   **선택**

standard는 저비용 기본 경로이고, deep은 더 높은 추론 경로를 사용합니다.

**사용 가능한 옵션:** `standard`, `deep`  \
**기본값:** `"standard"`

---

`max_output_tokens`   `integer`   **선택**

요청한 답변 한도입니다. 모델이 보고하는 출력 사용량에는 이 값을 넘는 숨은 추론 토큰이 포함될 수 있으며, BeatAPI는 그 차이를 감사용으로 기록하고 작업 보류 금액 안에서 실제 보고된 사용량으로 정산합니다.

**기본값:** `2048`  \
**범위:** 256\~8192

## 응답

요청에 성공하면 HTTP `201`을 반환합니다.

```json
{
  "data": {
    "id": "task_va8K2qA",
    "object": "task",
    "task_kind": "workflow",
    "capability_id": "video-analysis",
    "capability_version": 1,
    "workflow": "video-analysis",
    "status": "queued",
    "stage": "queued",
    "created_at": 1787385600,
    "updated_at": 1787385600,
    "completed_at": null,
    "output": null,
    "usage": {
      "credits_reserved": 0.01,
      "credits_charged": 0.01,
      "billable_duration_seconds": 60,
      "credits_settled": 0,
      "credits_refunded": 0
    },
    "request_id": "req_va123",
    "error_code": null,
    "error_message": null
  }
}
```

## 분석 깊이와 과금

`standard`는 요약, 구간 분할, 타임스탬프, 추출을 위한 기본 경로입니다. 움직임, 접촉, 연속성, 모호한 이벤트에 대해 더 촘촘한 추론이 필요하면 `deep`을 사용하세요.

BeatAPI는 같은 계정이 `POST /v1/files`로 업로드한 최대 600초의 MP4 또는 MOV 입력만 받습니다. 검증된 트랙 길이로 보수적인 입력 토큰 보류량을 정하고, 완료된 작업은 검증된 실제 입력·출력 토큰 보고값으로 정산합니다.

현재 단가는 [Video Analysis API 페이지](https://www.beatapi.io/video-analysis-api)와 `/pricing`에 있습니다. 이 페이지는 요청 계약만 다룹니다.

생성 엔드포인트는 최대 요청 금액을 보류한 뒤 대기 중인 작업을 반환합니다. 사용하지 않은 보류 금액은 검증된 실제 토큰 사용량이 정산될 때 반환됩니다. 공용 USD 잔액은 센트 단위로 정산되므로 완료된 작업은 각각 가장 가까운 \$0.01 단위로 올림됩니다.

모델은 기본적으로 일반 영상을 약 1 FPS로 샘플링합니다. 빠른 동작과 잦은 컷은 놓칠 수 있으므로, 프레임 단위 움직임이 중요하면 타임스탬프를 요청하고 더 짧은 클립을 사용하세요.

## 다음 단계

완료된 분석은 `data.output.text`에서, 토큰 사용량은 `data.output.usage`에서 읽으세요. 작업이 처리 용량 때문에 대기 중이면 성공하거나 실패할 때까지 `GET /v1/tasks/{task_id}`를 폴링하세요.

## 오류

| 상태    | 의미                                                                                                                                                                                                                                    |
| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | JSON 형식이 잘못되었거나, 이 엔드포인트가 받지 않는 필드·값·조합이 있거나(`bad_request`, 메시지에 해당 필드가 표시됨), 입력이 콘텐츠 검수에서 거부되었습니다(`content_policy_violation`). 그대로 재시도할 수 없습니다.                                                                                      |
| `401` | API 키가 없거나(`missing_api_key`), 키가 잘못되었거나 만료, 비활성화, 소진되었습니다(`invalid_api_key`, 메시지에 원인이 표시됨). `Authorization: Bearer <key>` 형식으로 보내세요. 키는 `sk-` 접두사가 있어도 없어도 동작합니다. 재시도할 수 없습니다.                                                       |
| `402` | 잔액이 부족합니다(`insufficient_credits`). 계정 잔액이 0이거나 이 요청의 가격보다 적습니다. 충전한 뒤 다시 보내세요. 충전 전에는 재시도할 수 없습니다.                                                                                                                                    |
| `403` | 이 키나 계정으로는 이 호출을 할 수 없습니다(`forbidden`). 예를 들어 무료 크레딧으로 쓸 수 없는 모델(충전하면 사용 가능), 키의 IP 허용 목록 밖에서 보낸 요청, 키의 그룹에 속하지 않은 모델이 해당합니다. 재시도할 수 없습니다.                                                                                            |
| `409` | `Idempotency-Key`가 24시간 안에 다른 요청 본문이나 경로에 이미 사용되었거나, 이 키를 사용한 첫 요청이 아직 처리 중입니다(`idempotency_conflict`). 그대로 재시도할 수 없습니다.                                                                                                              |
| `429` | 요청이 너무 많습니다(`rate_limit_exceeded`, 무료 모델 한도 포함). `Retry-After`(또는 `error.retry_after_seconds`)에 표시된 초만큼 기다린 뒤 재시도할 수 있습니다.                                                                                                            |
| `500` | 예상하지 못한 내부 오류입니다(`internal_error`). 재시도할 수 있으며, 문제가 계속되면 지원 요청 시 `request_id`를 함께 알려 주세요.                                                                                                                                             |
| `503` | 요청을 완료하지 못했습니다(`processing_unavailable`, `processing_timeout`, `processing_failed` 또는 `result_transfer_failed`). 과금되지 않았습니다. 백오프를 적용해 재시도할 수 있습니다. 503에는 `Retry-After` 헤더도 `retry_after_seconds`도 없습니다. BeatAPI는 502나 504를 반환하지 않습니다. |