Workflow API

単一のモデル仕様ではなく、安定した BeatAPI の機能を使いたい場合は Workflow API を利用します。

ワークフローは非同期です。

1. タスクを作成し data.id を保存します。
2. GET /v1/tasks/{task_id} を 5–10 秒ごとに確認します。
3. succeeded または failed で終了します。Music Video の手動確認は requires_action で停止する場合があります。
4. ポーリングが動作したら、署名付き Webhook で通知を受け取ります。

全フィールドの仕様は Music Video、Ecommerce Video、Video Analysis を参照してください。

ワークフローの種類を取得する

GET /v1/workflows

この公開エンドポイントにパラメーターはなく、認証も不要です。

curl https://api.beatapi.io/v1/workflows

{
  "data": {
    "object": "list",
    "data": [
      {
        "id": "music-video",
        "object": "workflow",
        "name": "Music Video API",
        "description": "Generate short music video clips from audio, lyrics, and visual direction."
      },
      {
        "id": "ecommerce-video",
        "object": "workflow",
        "name": "Ecommerce Video API",
        "description": "Generate product ad videos from product images and a short creative brief."
      },
      {
        "id": "video-analysis",
        "object": "workflow",
        "name": "Video Analysis API",
        "description": "Analyze an uploaded video with timestamp-aware multimodal reasoning."
      }
    ]
  }
}

429 rate_limit_exceeded には Retry-After と error.retry_after_seconds が含まれる場合があります。指定時間以上待ってから再試行してください。

共通の本番利用ルール

• ベース URL は https://api.beatapi.io。
• 長期利用する API キーは信頼できるサーバーに保存します。
• 入力は公開され、アクセス可能である必要があります。ローカル素材は POST /v1/files を使います。
• 作成リクエストはクレジットを仮確保し、共通形式の Task を返します。
• request_id、利用量、ステータス、エラー、最終出力 URL を記録します。
• 冪等ヘッダーが文書化されていない作成リクエストは、結果が不明でも無条件で再試行しないでください。

1 回の生成で、自分でモデルを選びたい場合は、モデル単位の Video API または Image API を使います。