> 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. # 뮤직비디오 > 이미지, 오디오, 크리에이티브 제어로 Music Video 워크플로 작업을 만듭니다. `POST https://api.beatapi.io/v1/music-video/tasks` 이미지, 오디오, 크리에이티브 제어로 Music Video 워크플로 작업을 만듭니다. ## 인증 `Authorization`   `string`   **필수** BeatAPI API 키를 Bearer 토큰으로 보내세요. 키는 [대시보드](https://beatapi.io/dashboard)에서 만들 수 있습니다. ``` Authorization: Bearer ``` 영구 API 키는 신뢰할 수 있는 서버에만 보관하세요. 요청 본문에는 `Content-Type: application/json`이 필요합니다. `Idempotency-Key`는 엔드포인트가 지원하는 경우 선택 사항이며, 완전히 같은 본문으로 안전하게 재시도하려면 사용하는 것이 좋습니다. ## 요청 본문 `mv_tier`   `enum`   **선택** 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`   **선택** Standard 워크플로에서 쓰는 대사와 가사 언어입니다. **사용 가능한 옵션:** `en`, `zh` --- `quality`   `enum`   **선택** 생성 품질 등급입니다. 540p에서는 high quality를 사용할 수 없습니다. **사용 가능한 옵션:** `standard`, `high` \ **기본값:** `"standard"` --- `style`   `string`   **선택** cinematic, anime, documentary, fashion editorial처럼 짧게 적는 시각 스타일입니다(선택 사항). **길이:** 최대 200자 --- `aspect_ratio`   `enum`   **선택** 목표 출력 배치입니다. 대상 플레이어나 소셜 피드에 맞게 명시적으로 설정하세요. **사용 가능한 옵션:** `1:1`, `16:9`, `9:16`, `4:3`, `3:4` --- `resolution`   `enum`   **선택** 최상위 출력 해상도입니다. 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`   **선택** auto는 최종 Music Video를 합성하고, manual은 합성 전에 샷을 검토하거나 편집할 수 있도록 `requires_action`에서 일시 정지합니다. **사용 가능한 옵션:** `auto`, `manual` \ **기본값:** `"auto"` --- `mv_mode`   `enum`   **선택** 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`을 반환합니다. ```json { "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`에서 읽습니다. ## 오류 | 상태 | 의미 | | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | JSON 형식이 잘못되었거나, 이 엔드포인트가 받지 않는 필드·값·조합이 있거나(`bad_request`, 메시지에 해당 필드가 표시됨), 입력이 콘텐츠 검수에서 거부되었습니다(`content_policy_violation`). 그대로 재시도할 수 없습니다. | | `401` | API 키가 없거나(`missing_api_key`), 키가 잘못되었거나 만료, 비활성화, 소진되었습니다(`invalid_api_key`, 메시지에 원인이 표시됨). `Authorization: Bearer ` 형식으로 보내세요. 키는 `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를 반환하지 않습니다. |