탐색으로 건너뛰기
BeatAPIMusic VideoWorkflow API

뮤직비디오

이미지, 오디오, 크리에이티브 제어로 Music Video 워크플로 작업을 만듭니다.

입력이 로컬 파일이면 로컬 입력을 업로드하고 반환된 data.url을 사용하세요. data.id를 저장하고, 작업을 폴링하며, 오류 및 재시도 정책을 따르세요.

인증

AuthorizationBearer

API 키를 Authorization: Bearer <BEATAPI_API_KEY>로 보내세요.

헤더

Idempotency-Keystring선택 사항

재시도용 키입니다(선택 사항). 같은 요청 본문에 같은 키를 다시 쓰면 접수된 작업을 반환하고, 다른 본문에 쓰면 409 idempotency_conflict를 반환합니다.

요청

This endpoint expects an object.
audio_urlstring필수형식: "uri"

최상위 공개 HTTPS 오디오 URL입니다. Standard는 10-180초, Premium은 10-300초를 받습니다.

mv_tierenum선택 사항기본값 standard

Music Video 등급을 선택합니다. Standard는 이 필드를 생략하고, Premium 요청은 premium을 설정해야 합니다.

허용된 값:
imageslist of strings선택 사항

최상위 장면 이미지입니다. Standard는 1-7장이 필요합니다. Premium sing 모드는 0-6장을 받고, Premium dance와 perform은 공개 HTTPS PNG, JPEG, WebP URL이 정확히 6장 필요합니다.

promptstring선택 사항<=3000 characters

스토리, 배경, 퍼포먼스, 카메라, 조명, 페이스에 대한 크리에이티브 방향입니다(선택 사항). 최대 3000자.

languageenum선택 사항

Standard 워크플로에서 쓰는 대사와 가사 언어입니다.

허용된 값:
qualityenum선택 사항기본값 standard

생성 품질 등급입니다. 540p에서는 high quality를 사용할 수 없습니다.

허용된 값:
stylestring선택 사항<=200 characters

cinematic, anime, documentary, fashion editorial처럼 짧게 적는 시각 스타일입니다(선택 사항).

aspect_ratioenum선택 사항

목표 출력 배치입니다. 대상 플레이어나 소셜 피드에 맞게 명시적으로 설정하세요.

허용된 값:
resolutionenum선택 사항기본값 720p

최상위 출력 해상도입니다. Standard는 540p, 720p 또는 1080p를 받고, Premium은 720p로 고정됩니다.

허용된 값:
lip_syncboolean선택 사항기본값 false

립싱크 퍼포먼스를 생성합니다. true이면 lip_ref_url이 필수입니다.

lip_ref_urlstring선택 사항형식: "uri"

Standard 립싱크에 쓰는 정면 얼굴 클로즈업 이미지의 공개 HTTPS URL입니다.

add_subtitleboolean선택 사항기본값 false

생성되었거나 제공한 자막을 최종 영상에 입힙니다.

subtitle_colorstring선택 사항형식: "^#[0-9A-Fa-f]{6}$"

여섯 자리 16진수 값으로 지정하는 자막 텍스트 색상입니다. 자막을 켰을 때 사용됩니다.

srt_urlstring선택 사항형식: "uri"

공개 HTTPS .srt 자막 파일입니다(선택 사항). 로컬 자막은 POST /v1/files로 업로드하세요.

durationinteger선택 사항10-300

최상위 과금 대체값일 뿐이며, 감지된 오디오 길이가 우선합니다. Standard는 10-180초, Premium은 10-300초를 받습니다.

compose_modeenum선택 사항기본값 auto

auto는 최종 Music Video를 합성하고, manual은 합성 전에 샷을 검토하거나 편집할 수 있도록 requires_action에서 일시 정지합니다.

허용된 값:
mv_modeenum선택 사항

Premium 퍼포먼스 모드입니다. sing 모드는 lip_ref_urls가 필요하고, dance와 perform은 images가 정확히 6장 필요합니다.

허용된 값:
lip_ref_urlslist of strings선택 사항

sing과 sing_perform에 필수이며, dance와 perform에서는 생략하세요. 정면 얼굴 클로즈업 이미지의 공개 HTTPS URL을 한두 개 제공하세요.

응답

작업 접수됨

dataobject

접수되었거나 현재의 BeatAPI 작업 상태입니다.

오류

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
409
Conflict Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error