탐색으로 건너뛰기

BeatAPI 영상 API

영상 API

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

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

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

사용 가능한 모델 목록

GET /v1/media/models

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

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

curl "https://api.beatapi.io/v1/media/models?media_type=video"
{
  "data": {
    "object": "list",
    "data": [
      {
        "id": "minimax-h3",
        "object": "generation_model",
        "name": "MiniMax H3",
        "media_type": "video",
        "input_modes": ["text", "frames", "reference"]
      }
    ]
  }
}
필드타입의미
idstring고정된 공개 모델 별칭
objectstringgeneration_model
namestring표시 이름
media_typestringimage 또는 video
input_modesstring[]text, image, frames, reference 중 하나 이상

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

공통 생성 계약

POST /v1/videos/tasks

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

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

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공통 코드클라이언트 조치
400bad_request필드, 값, 조합, 개수 또는 미디어 URL을 수정하세요
400content_policy_violation프롬프트나 입력을 바꾸세요. 그대로 다시 보내지 마세요
401missing_api_key / invalid_api_keyBearer 키를 보내거나, 잘못되었거나 만료·비활성화·소진된 키를 교체하세요
402insufficient_credits새 작업을 만들기 전에 충전하세요
403forbidden이 키나 계정에 허용되지 않습니다. 예: 무료 크레딧으로 쓸 수 없는 모델
409idempotency_conflict본문이 완전히 같을 때만 키를 재사용하세요
429rate_limit_exceededRetry-After를 따르세요
500internal_error백오프를 두고 한 번 재시도하세요
503processing_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에 있습니다. 모든 코드와 재시도 규칙은 오류를 참고하세요. 실제로 적용되는 요청 계약은 아래 각 모델 페이지에 있습니다.