상품 영상

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

제품 이미지와 명시적인 출력 길이로 Ecommerce Video 워크플로 작업을 만듭니다.

인증

Authorization   string   필수

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

Authorization: Bearer <BEATAPI_API_KEY>

영구 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<string>   선택

목표 출력 배치입니다. 가로는 16:9, 세로 소셜은 9:16, 정사각형은 1:1을 사용하세요. 안정적인 레이아웃을 위해 명시적으로 설정하세요.

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

language   enum<string>   선택

대사와 내레이션 언어입니다. 영어는 en, 중국어는 zh를 사용하세요. 프롬프트에 여러 언어가 섞여 있으면 명시적으로 설정하세요.

사용 가능한 옵션: en, zh

응답

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

{
  "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에서 읽습니다.

오류