영상 분석

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

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

인증

Authorization   string   필수

BeatAPI API 키를 Bearer 토큰으로 보내세요. 키는 대시보드에서 만들 수 있습니다.

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을 반환합니다.

{
  "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 페이지와 /pricing에 있습니다. 이 페이지는 요청 계약만 다룹니다.

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

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

다음 단계

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

오류