> 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. # 상품 영상 > 제품 이미지와 명시적인 출력 길이로 Ecommerce Video 워크플로 작업을 만듭니다. `POST https://api.beatapi.io/v1/ecommerce-video/tasks` 제품 이미지와 명시적인 출력 길이로 Ecommerce Video 워크플로 작업을 만듭니다. ## 인증 `Authorization`   `string`   **필수** BeatAPI API 키를 Bearer 토큰으로 보내세요. 키는 [대시보드](https://beatapi.io/dashboard)에서 만들 수 있습니다. ``` Authorization: Bearer ``` 영구 API 키는 신뢰할 수 있는 서버에만 보관하세요. 요청 본문에는 `Content-Type: application/json`이 필요합니다. `Idempotency-Key`는 엔드포인트가 지원하는 경우 선택 사항이며, 완전히 같은 본문으로 안전하게 재시도하려면 사용하는 것이 좋습니다. ## 요청 본문 `images`   `string[]`   **필수** 대표 제품 또는 장면 이미지를 먼저 넣고, 그 뒤에 공개 HTTPS PNG, JPEG, WebP 제품·라이프스타일 이미지를 최대 6장 추가합니다. 로컬 파일은 `POST /v1/files`로 업로드하고 반환된 `data.url`을 사용하세요. **개수:** 1\~7개 --- `duration`   `integer`   **필수** 필수 목표 출력 길이(초)이며 USD 계산의 기준입니다. 허용 범위는 10-60초입니다. **범위:** 10\~60 --- `prompt`   `string`   **선택** 크리에이티브 방향, 대상 고객, 제품 장점, 혜택, 톤, 장면 또는 행동 유도 문구입니다(선택 사항). 최대 2000자. **길이:** 최대 2000자 --- `aspect_ratio`   `enum`   **선택** 목표 출력 배치입니다. 가로는 16:9, 세로 소셜은 9:16, 정사각형은 1:1을 사용하세요. 안정적인 레이아웃을 위해 명시적으로 설정하세요. **사용 가능한 옵션:** `16:9`, `9:16`, `1:1` --- `language`   `enum`   **선택** 대사와 내레이션 언어입니다. 영어는 `en`, 중국어는 `zh`를 사용하세요. 프롬프트에 여러 언어가 섞여 있으면 명시적으로 설정하세요. **사용 가능한 옵션:** `en`, `zh` ## 응답 요청에 성공하면 HTTP `201`을 반환합니다. ```json { "data": { "id": "task_p9Lm2", "object": "task", "task_kind": "workflow", "capability_id": "ecommerce-video", "capability_version": 1, "workflow": "ecommerce-video", "status": "queued", "stage": "queued", "created_at": 1782210000, "updated_at": 1782210000, "completed_at": null, "output": null, "usage": { "credits_reserved": 4.5, "credits_charged": 4.5, "billable_duration_seconds": 15, "credits_settled": 0, "credits_refunded": 0 }, "request_id": "req_def456", "error_code": null, "error_message": null } } ``` ## 다음 단계 접수 응답에서 `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를 반환하지 않습니다. |