商品紹介動画

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

商品画像と明示的な出力の長さを指定して、商品紹介動画のワークフロータスクを作成します。

認証

Authorization   string   必須

BeatAPI の API キーを Bearer トークンとして送信します。API キーはダッシュボードで作成できます。

Authorization: Bearer <BEATAPI_API_KEY>

通常の API キーは、信頼できるサーバーで管理してください。リクエストボディには Content-Type: application/json が必要です。対応するエンドポイントでは Idempotency-Key は任意ですが、同一のリクエストボディで安全に再試行するために指定を推奨します。

リクエストボディ

images   string[]   必須

メインの商品画像またはシーン画像を最初に指定し、続けて最大 6 枚の商品・利用シーン画像を指定します。公開 HTTPS の PNG・JPEG・WebP に対応しています。ローカルファイルは POST /v1/files でアップロードし、返された data.url を使用してください。

要素数: 1 – 7 件

duration   integer   必須

出力動画の目標の長さを秒単位で指定します。必須フィールドで、米ドル建て料金の計算基準にもなります。指定できる範囲は 10～60 秒です。

範囲: 10 – 60

prompt   string   任意

制作方針、対象ユーザー、商品の利点、オファー、トーン、シーン、行動を促すメッセージなどを任意で指定します。最大 2000 文字です。

文字数: 最大 2000 文字

aspect_ratio   enum<string>   任意

掲載先に合わせた出力のアスペクト比です。横長には 16:9、縦型 SNS 動画には 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 から取得します。

エラー