> 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.

# BeatAPI Workflow API

> タスク、ポーリング、署名付き Webhook で Music Video、Ecommerce Video、Video Analysis のワークフローを構築します。

# Workflow API

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

| ワークフロー ID         | 必須入力                                        | 主な設定                                           | 結果                             |
| ----------------- | ------------------------------------------- | ---------------------------------------------- | ------------------------------ |
| `music-video`     | 音声と、利用するグレードに必要な視覚参照                        | Standard/Premium、品質、解像度、モード、字幕、リップシンク、確認・編集・合成 | ホストされた Music Video と絵コンテのメタデータ |
| `ecommerce-video` | 商品画像 1–7 枚と長さ 10–60 秒                       | プロンプト、アスペクト比、言語                                | ホストされた 1080p の商品動画             |
| `video-analysis`  | `/v1/files` でアップロードした MP4 または MOV 1 本とプロンプト | Standard/deep の分析深度、出力トークンの予算                  | 分析テキストとトークン利用量                 |

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

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

全フィールドの仕様は [Music Video](/workflow-api/music-video)、[Ecommerce Video](/workflow-api/ecommerce-video)、[Video Analysis](/workflow-api/video-analysis) を参照してください。

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

`GET /v1/workflows`

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

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

```json
{
  "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."
      }
    ]
  }
}
```

| フィールド                     | 型         | 意味                                               |
| ------------------------- | --------- | ------------------------------------------------ |
| `data.object`             | string    | `list`                                           |
| `data.data`               | object\[] | 利用可能なワークフロー                                      |
| `data.data[].id`          | string    | `music-video`、`ecommerce-video`、`video-analysis` |
| `data.data[].object`      | string    | `workflow`                                       |
| `data.data[].name`        | string    | 表示名                                              |
| `data.data[].description` | string    | ワークフローの概要                                        |

`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](/video-api) または [Image API](/image-api) を使います。