뮤직비디오

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

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

인증

Authorization   string   필수

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

Authorization: Bearer <BEATAPI_API_KEY>

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

요청 본문

mv_tier   enum<string>   선택

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

사용 가능한 옵션: standard, premium
기본값: "standard"

images   string[]   선택

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

개수: 0~7개

audio_url   string   필수

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

형식: uri

prompt   string   선택

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

길이: 최대 3000자

language   enum<string>   선택

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

사용 가능한 옵션: en, zh

quality   enum<string>   선택

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

사용 가능한 옵션: standard, high
기본값: "standard"

style   string   선택

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

길이: 최대 200자

aspect_ratio   enum<string>   선택

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

사용 가능한 옵션: 1:1, 16:9, 9:16, 4:3, 3:4

resolution   enum<string>   선택

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

사용 가능한 옵션: 540p, 720p, 1080p
기본값: "720p"

lip_sync   boolean   선택

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

기본값: false

lip_ref_url   string   선택

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

형식: uri

add_subtitle   boolean   선택

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

기본값: false

subtitle_color   string   선택

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

srt_url   string   선택

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

형식: uri

duration   integer   선택

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

범위: 10~300

compose_mode   enum<string>   선택

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

사용 가능한 옵션: auto, manual
기본값: "auto"

mv_mode   enum<string>   선택

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

사용 가능한 옵션: sing, sing_perform, dance, perform

lip_ref_urls   string[]   선택

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

개수: 1~2개

응답

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

{
  "data": {
    "id": "task_8K2qA",
    "object": "task",
    "task_kind": "workflow",
    "capability_id": "music-video",
    "capability_version": 1,
    "workflow": "music-video",
    "status": "queued",
    "stage": "queued",
    "storyboard": {
      "shots": []
    },
    "created_at": 1782210000,
    "updated_at": 1782210000,
    "completed_at": null,
    "output": null,
    "usage": {
      "credits_reserved": 1.5,
      "credits_charged": 1.5,
      "billable_duration_seconds": 15,
      "credits_settled": 0,
      "credits_refunded": 0
    },
    "request_id": "req_abc123",
    "error_code": null,
    "error_message": null
  }
}

수동 검토 워크플로

compose_mode가 manual이면 작업이 requires_action에 도달할 때까지 폴링한 뒤, 반환된 스토리보드와 샷 ID를 사용하세요:

1. 샷 프롬프트나 Premium 참조 이미지를 조정해야 하면 POST /v1/music-video/tasks/{task_id}/shots/{shot_id}/edit을 호출하세요.
2. 검토용 호스팅 미리보기가 필요하면 GET /v1/music-video/tasks/{task_id}/shots/{shot_id}/media를 호출하세요.
3. 선택한 샷이 준비되면 POST /v1/music-video/tasks/{task_id}/compose를 호출하세요.

편집이나 합성 작업 후에도 같은 상위 작업을 계속 폴링하세요. 자동 합성에는 이러한 수동 호출이 필요하지 않습니다.

다음 단계

접수 응답에서 data.id를 저장하고, status가 succeeded 또는 failed가 될 때까지 5–10초마다 GET /v1/tasks/{task_id}를 폴링하세요. 완료된 결과물은 data.output.media에서 읽습니다.

오류