エフェクト API

POST https://api.beatapi.io/v1/effects/tasks

バージョン管理された BeatAPI エフェクトを使用して、画像または動画の非同期エフェクトタスクを作成します。

認証

Authorization   string   必須

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

Authorization: Bearer <BEATAPI_API_KEY>

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

リクエストボディ

effect_id   string   必須

GET /v1/effects で取得した、公開済みエフェクトの固定 ID です。

effect_version   integer   任意

公開後に内容が変更されないバージョンを任意で指定します。省略すると、現在公開されているバージョンが使われます。

範囲: x >= 1

images   string[]   必須

選択したエフェクトのバージョンが要求する順序で、公開 HTTPS 入力画像を指定します。正確な枚数と対応するメディアのルールは GET /v1/effects/{effect_id} で確認してください。ローカルファイルは POST /v1/files でアップロードします。

要素数: 1 – 7 件

options   object   任意

選択したエフェクトのバージョンが対応する任意の設定です。未対応の設定は省略してください。設定の可否はカタログに記載された情報に従ってください。

options.aspect_ratio   string   任意

選択したエフェクトが対応する場合に、出力のアスペクト比を指定します。

options.resolution   string   任意

選択したエフェクトが対応する場合に、出力解像度を指定します。

options.duration   integer   任意

選択したエフェクトが対応する場合に、出力動画の長さを秒単位で指定します。

options.bgm   boolean   任意

選択したエフェクトが対応する場合に、BGM を付けます。

options.seed   integer   任意

選択したエフェクトが対応する場合に、再現性のための seed を任意で指定します。

レスポンス

リクエストが成功すると、HTTP 201 が返されます。

{
  "data": {
    "id": "task_effect123",
    "object": "task",
    "task_kind": "effect",
    "capability_id": "video-muscle-max",
    "capability_version": 1,
    "effect_id": "video-muscle-max",
    "effect_version": 1,
    "status": "queued",
    "stage": "queued",
    "created_at": 1782210000,
    "updated_at": 1782210000,
    "completed_at": null,
    "output": null,
    "usage": {
      "credits_reserved": 1.2,
      "credits_charged": 1.2,
      "credits_settled": 0,
      "credits_refunded": 0
    },
    "request_id": "req_effect123",
    "error_code": null,
    "error_message": null
  }
}

次の手順

受付レスポンスの data.id を保存し、status が succeeded または failed になるまで、5～10 秒ごとに GET /v1/tasks/{task_id} をポーリングします。完成した素材は data.output.media から取得します。

エラー