> 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. # エフェクト API > バージョン管理された BeatAPI エフェクトを使用して、画像または動画の非同期エフェクトタスクを作成します。 `POST https://api.beatapi.io/v1/effects/tasks` バージョン管理された BeatAPI エフェクトを使用して、画像または動画の非同期エフェクトタスクを作成します。 ## 認証 `Authorization`   `string`   **必須** BeatAPI の API キーを Bearer トークンとして送信します。API キーは[ダッシュボード](https://beatapi.io/dashboard)で作成できます。 ``` Authorization: Bearer ``` 通常の 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` が返されます。 ```json { "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` から取得します。 ## エラー | ステータスコード | 意味と対処方法 | | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | JSON の形式が不正、またはフィールド・値・組み合わせが未対応です（`bad_request`。メッセージにフィールド名が記載されます）。入力がコンテンツ審査で拒否された場合は `content_policy_violation` です。修正せずに再試行しても成功しません。 | | `401` | API キーが未指定（`missing_api_key`）、またはキーが不正・期限切れ・無効・上限到達です（`invalid_api_key`。理由はメッセージに記載されます）。`Authorization: Bearer ` で送信してください。`sk-` 接頭辞の有無にかかわらず使えます。そのまま再試行しないでください。 | | `402` | 残高不足です（`insufficient_credits`）。残高がゼロ、またはこのリクエストの料金に足りません。残高をチャージしてから再度送信してください。それまでは再試行しないでください。 | | `403` | キーまたはアカウントに、この呼び出しの権限がありません（`forbidden`）。例として、無料クレジットでは利用できないモデル（チャージすると利用可能）、キーの IP 許可リスト外からのリクエスト、キーのグループに含まれないモデルがあります。そのまま再試行しないでください。 | | `404` | エフェクトまたは指定したバージョンを利用できません（`not_found`）。 | | `409` | `Idempotency-Key` が別のリクエストボディで使用済み、または同じキーの最初のリクエストが処理中です（`idempotency_conflict`）。そのまま再試行しないでください。 | | `429` | リクエスト数が上限を超えています（無料モデルの制限を含む `rate_limit_exceeded`）、または同時処理中のタスクが多すぎます（`user_concurrency_exceeded`）。`Retry-After` の秒数だけ待ってから再試行できます。同じ値は `error.retry_after_seconds` にも含まれます。 | | `500` | 予期しない内部エラーです（`internal_error`）。再試行できます。繰り返し発生する場合は、`request_id` を控えてサポートに連絡してください。 | | `503` | リクエストを完了できませんでした（`processing_unavailable`、`processing_timeout`、`processing_failed`、`result_transfer_failed`）。課金されていません。待機時間を段階的に延ばして再試行できます。待機時間が判明している場合は `Retry-After` が返されます。BeatAPI は 502 や 504 を返しません。 |