> 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 クイックガイド

> キーの作成、最初の画像・動画タスク、結果確認、ファイルのアップロード、Webhook、本番での安全な再試行を説明します。

# クイックガイド

BeatAPI は、Text、Workflow、Realtime、Video、Image、Effect API を 1 つのサーバー側 API キーで利用します。まず次の 3 ステップで始めてください。その後、同期テキスト応答、共通タスクフィールド、アップロード、上限、本番のエラーについて読み進められます。

## 3 ステップで最初のタスクを実行する

### 1. API キーを作成する

[ダッシュボード → API キー](https://beatapi.io/dashboard/apikeys)で作成し、コマンド履歴に残さずシェルに読み込みます。

```bash
read -rsp "BeatAPI API key: " BEATAPI_API_KEY && echo
export BEATAPI_API_KEY
```

すべてのリクエストで、ベース URL `https://api.beatapi.io` と次のヘッダーを使います。

```http
Authorization: Bearer <BEATAPI_API_KEY>
```

### 2. タスクを作成する

最小の画像リクエストは `POST /v1/images/tasks` です。

```bash
curl https://api.beatapi.io/v1/images/tasks \
  -X POST \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana",
    "prompt": "Editorial product photograph on a warm stone pedestal."
  }'
```

有効なリクエストには `201 Created` が返ります。返された `data.id` を保存してください。

### 3. 結果をポーリングする

```bash
curl https://api.beatapi.io/v1/tasks/task_8K2qA \
  -H "Authorization: Bearer $BEATAPI_API_KEY"
```

`task_8K2qA` をステップ 2 の `data.id` に置き換えます。ジッターを付けて 5–10 秒ごとに確認します。`succeeded` なら `data.output.media` を読み、停止します。`failed` なら `data.error_code` と `data.error_message` を読み、停止します。

> **Note**
>
> 長期利用する API キーは信頼できるサーバーに保存してください。ブラウザーやモバイルのコード、スクリプト、ログ、スクリーンショットに含めないでください。Realtime のブラウザーには、サーバーが作成した短寿命の `client_secret` だけを渡します。

## API を選ぶ

| API                       | 作成操作                             | 入力                                     | 結果                           |
| ------------------------- | -------------------------------- | -------------------------------------- | ---------------------------- |
| Text（GPT-5.6）             | `POST /v1/responses`             | テキスト、画像、ツール、推論設定                       | 同期 JSON またはストリーミングのテキスト応答    |
| Workflow — Music Video    | `POST /v1/music-video/tasks`     | 音声とグレード別の視覚参照                          | 完成した Music Video と絵コンテのメタデータ |
| Workflow — Ecommerce      | `POST /v1/ecommerce-video/tasks` | 商品画像、長さ、制作指示                           | 完成した商品動画                     |
| Workflow — Video Analysis | `POST /v1/video-analysis/tasks`  | アップロード動画、分析プロンプト、深度                    | 分析テキストとトークン利用量               |
| Realtime                  | `POST /v1/realtime/sessions`     | ブラウザーのオリジンと固定の長さ、その後ライブの `MediaStream` | リアルタイム生成の WebRTC 動画          |
| Video                     | `POST /v1/videos/tasks`          | モデル別のプロンプトとメディア参照                      | ホストされた動画 1 本                 |
| Image                     | `POST /v1/images/tasks`          | モデル別のプロンプトと任意の参照                       | ホストされた画像 1 枚                 |
| Effect                    | `POST /v1/effects/tasks`         | 公開 Effect ID、画像、対応オプション                | ホストされた画像または動画のエフェクト結果        |

テキストは同期、または Server-Sent Events で返します。Realtime は短寿命の Session を作成します。Workflow、Video、Image、Effect の作成は非同期の Task を返すため、`data.id` を保存し、共通タスクエンドポイントを確認します。上限は API キーごとに毎分 120 リクエストです。

GPT-5.6 の選択、SDK 互換形式、ストリーミング例は [GPT-5.6 ガイド](/text-api/gpt-5-6)を参照してください。

## タスクのステータスを取得する

`GET /v1/tasks/{task_id}`

| パラメーター    | 場所 | 型      | 必須 | ルール                    |
| --------- | -- | ------ | -- | ---------------------- |
| `task_id` | パス | string | はい | 作成レスポンスの `data.id` を使用 |

### ステータス

| ステータス              | 意味                     | クライアントの操作                 |
| ------------------ | ---------------------- | ------------------------- |
| `queued`           | 受け付け済み、待機中             | ポーリングを続ける                 |
| `processing`       | 生成中                    | ポーリングを続ける                 |
| `storyboard_ready` | Music Video の絵コンテが利用可能 | 自動フローでは続行する場合がある。必要に応じて確認 |
| `requires_action`  | Music Video の手動確認待ち    | ショットを編集、または合成             |
| `editing`          | Music Video のショット編集中   | ポーリングを続ける                 |
| `composing`        | Music Video の合成中       | ポーリングを続ける                 |
| `succeeded`        | ホストされた出力が完成            | `data.output` を読み、停止      |
| `failed`           | エラーで終了                 | エラーと返金を読み、停止              |

### 共通形式の Task フィールド

| フィールド                | 型               | 存在条件        | 意味                                  |
| -------------------- | --------------- | ----------- | ----------------------------------- |
| `id`                 | string          | 常に          | 安定したタスク ID                          |
| `object`             | string          | 常に          | `task`                              |
| `task_kind`          | string          | 常に          | `workflow`、`effect`、`image`、`video` |
| `capability_id`      | string          | 常に          | 安定したワークフロー、Effect、生成モデル ID          |
| `capability_version` | integer or null | 常に          | バージョン管理されている場合の不変バージョン              |
| `workflow`           | string          | ワークフロー      | `music-video` または `ecommerce-video` |
| `effect_id`          | string          | エフェクト       | 安定したエフェクト ID                        |
| `effect_version`     | integer         | エフェクト       | 選択した不変のエフェクトバージョン                   |
| `media_type`         | string          | 画像・動画       | `image` または `video`                 |
| `model`              | string          | 画像・動画       | 安定したモデルエイリアス                        |
| `status`             | string          | 常に          | 現在のライフサイクル状態                        |
| `stage`              | string          | 常に          | 現在の処理段階                             |
| `storyboard`         | object          | Music Video | 利用可能な場合のショットメタデータ                   |
| `created_at`         | integer         | 常に          | Unix タイムスタンプ                        |
| `updated_at`         | integer         | 常に          | Unix タイムスタンプ                        |
| `completed_at`       | integer or null | 常に          | 終了時の Unix タイムスタンプ                   |
| `output`             | object or null  | 常に          | 成功まで `null`                         |
| `usage`              | object          | 常に          | クレジットと課金対象の長さ                       |
| `request_id`         | string          | 常に          | サポート・デバッグ用の照合 ID                    |
| `error_code`         | string or null  | 常に          | 機械可読のタスク失敗コード                       |
| `error_message`      | string or null  | 常に          | 人が読むタスク失敗の説明                        |

### 利用量と出力

> **Note**
>
> `credits_reserved` などの公開フィールド名は API 互換性のため維持しています。クレジットと残高はすべて米ドル建ての小数の台帳金額です。1 Credit = $1 USD。ダッシュボードも同じ値を `$\` 付きで表示します。

| フィールド                             | 型                 | 意味                  |
| --------------------------------- | ----------------- | ------------------- |
| `usage.credits_reserved`          | number            | 操作で仮確保した米ドル金額       |
| `usage.credits_charged`           | number            | 受け付け時に課金した米ドル金額     |
| `usage.billable_duration_seconds` | integer, optional | 米ドル料金の計算に使う長さ       |
| `usage.credits_settled`           | number            | 成功後に確定した米ドル金額       |
| `usage.credits_refunded`          | number            | 返金対象の失敗後に戻した米ドル金額   |
| `output.media`                    | object\[]         | ホストされた結果ファイル        |
| `output.media[].type`             | string            | `image` または `video` |
| `output.media[].url`              | string            | ホストされた結果 URL        |
| `output.media[].mime_type`        | string            | 結果の MIME タイプ        |
| `output.r2_url`                   | string            | 主な結果 URL            |

## 入力ファイルをアップロードする

`POST /v1/files`

公開 HTTPS URL にないローカルの入力素材をアップロードします。正確な `Content-Length` が必要です。通常の `curl`、ブラウザー、SDK は自動で設定します。長さを宣言しないチャンク転送は、本文をバッファーする前に拒否されます。

### Multipart フィールド

| フィールド     | 型      | 必須  | 初期値     | ルール                                |
| --------- | ------ | --- | ------- | ---------------------------------- |
| `file`    | binary | はい  | —       | 対応ファイル 1 つ。動画最大 100 MB、その他最大 50 MB |
| `purpose` | string | いいえ | `input` | `input` のみ対応                       |

```bash
curl https://api.beatapi.io/v1/files \
  -X POST \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -F "file=@./song.mp3" \
  -F "purpose=input"
```

素材の `Content-Type` を指定して、ファイル本文を直接送ることもできます。

| 素材     | 対応拡張子             | 対応 MIME タイプ                                              | 追加ルール                                   |
| ------ | ----------------- | -------------------------------------------------------- | --------------------------------------- |
| 画像     | PNG、JPG/JPEG、WebP | `image/png`、`image/jpeg`、`image/webp`                    | 最大 50 MB                                |
| 音声     | MP3、WAV、AAC、M4A   | `audio/mpeg`、`audio/wav`、`audio/aac`、`audio/mp4`         | 最大 50 MB、10–300 秒                       |
| 字幕     | SRT               | `application/x-subrip`。`text/plain` はファイル名が `.srt` の場合のみ | 最大 50 MB                                |
| 動作参照動画 | MP4、MOV           | `video/mp4`、`video/quicktime`                            | 最大 100 MB、3–30 秒。Kling Motion Control 用 |

PDF、一般のテキスト、octet-stream、未対応の動画コンテナー、ZIP はアップロードできません。BeatAPI は宣言した MIME タイプとファイルのシグネチャを照合し、サーバーで動画の長さと寸法を読み取ります。ワークフローの入力 URL に localhost、プライベートネットワーク、data URL は使えません。

### ファイルのレスポンス

```json
{
  "data": {
    "id": "file_3xYz9",
    "object": "file",
    "url": "https://media.beatapi.io/inputs/file_3xYz9.mp3",
    "key": "inputs/file_3xYz9.mp3",
    "mime_type": "audio/mpeg",
    "size_bytes": 1048576,
    "purpose": "input",
    "audio_duration_seconds": 64.02,
    "audio_duration_source": "mp3_frame_scan",
    "created_at": 1782210000
  }
}
```

| フィールド                    | 型       | 存在条件 | 意味                   |
| ------------------------ | ------- | ---- | -------------------- |
| `id`                     | string  | 常に   | ファイル ID              |
| `object`                 | string  | 常に   | `file`               |
| `url`                    | string  | 常に   | 長期利用できる HTTPS 入力 URL |
| `key`                    | string  | 常に   | ストレージキー              |
| `mime_type`              | string  | 常に   | 検出・受け付けた MIME タイプ    |
| `size_bytes`             | integer | 常に   | アップロードのバイト数          |
| `audio_duration_seconds` | number  | 音声のみ | 検出した音声の長さ            |
| `audio_duration_source`  | string  | 音声のみ | 長さの検出方式              |
| `purpose`                | string  | 常に   | `input`              |
| `created_at`             | integer | 常に   | Unix タイムスタンプ         |

モデルやワークフローに `data.url` を指定します。音声タスクの制限は引き続き適用されます。Standard Music Video は 10–180 秒、Premium は 10–300 秒です。

## 利用量と上限を確認する

`GET /v1/usage`

認証が必要で、パラメーターはありません。

```bash
curl https://api.beatapi.io/v1/usage \
  -H "Authorization: Bearer $BEATAPI_API_KEY"
```

| フィールド                | 型                | 意味                                    |
| -------------------- | ---------------- | ------------------------------------- |
| `object`             | string           | `usage`                               |
| `credit_balance`     | number           | 現在の米ドル残高。マイナスの場合もある                   |
| `total_tasks`        | integer          | アカウントのタスク数                            |
| `credits_settled`    | number           | 精算済みの米ドル金額                            |
| `credits_refunded`   | number           | 返金済みの米ドル金額                            |
| `concurrency`        | object           | 処理中タスクの容量概要                           |
| `concurrency.limit`  | integer          | アカウントの同時処理タスク上限                       |
| `concurrency.active` | integer          | 現在、処理容量を使っているタスク数                     |
| `realtime`           | object, optional | Realtime Session の利用概要                |
| `realtime.sessions`  | integer          | Realtime Session の総数                  |
| `realtime.credits`   | number           | Realtime の精算済み米ドル金額                   |
| `realtime.active`    | integer          | `ready`、`connecting`、`active` のセッション数 |
| `by_workflow[]`      | object\[]        | ワークフロー互換の内訳                           |
| `by_capability[]`    | object\[]        | 安定した機能 ID ごとの全タスク種別の内訳                |
| `by_model[]`         | object\[]        | モデルエイリアス別の画像・動画タスク                    |
| `by_api_key[]`       | object\[]        | API キー別のタスク・クレジット合計                   |

内訳項目のフィールドは次のとおりです。

| 配列              | 必須項目                                                        |
| --------------- | ----------------------------------------------------------- |
| `by_workflow`   | `workflow`、`tasks`、`credits_settled`                        |
| `by_capability` | `task_kind`、`capability_id`、`tasks`、`credits_settled`       |
| `by_model`      | `media_type`、`model`、`tasks`、`credits_settled`              |
| `by_api_key`    | `api_key_id`、`title`、`key_prefix`、`tasks`、`credits_settled` |

`storyboard_ready` または `requires_action` で止まった Music Video は、処理中として数えられなくても精算済みクレジットを持つ場合があります。

## エラーと再試行方針

```json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Wait 12 seconds, then retry.",
    "retryable": true,
    "request_id": "req_abc123",
    "retry_after_seconds": 12
  }
}
```

すべてのエラーに `code`、原因を示す英語の `message`、`retryable`、`request_id` が付きます。`429` と待機時間が分かる `503` は `retry_after_seconds` と `Retry-After` も返します。`retryable` が `false` なら、内容を変更するまで同じ呼び出しは再び失敗します。

### 公開エラーコード

公開するのは以下の安定したコードのみです。第三者のステータスやエラー本文をそのまま返しません。[エラー](/errors)には、作成時と受け付け済みタスクの失敗コード、テキストの独自エラー形式を掲載しています。レスポンスでは `error.code`、非同期の終了時にも該当する値が `error_code` に入ります。

| コード                             | 意味                                                                             | クライアントの対処                                 |
| ------------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------- |
| `bad_request`                   | 不正な JSON、フィールド、組み合わせ、形式、URL、上限。作成時や、モデルが受け付け済みタスクの入力・パラメーターを拒否した場合。メッセージに対象を示す | 修正してから再試行                                 |
| `missing_api_key`               | キー未送信                                                                          | `Authorization: Bearer <key>` を送る         |
| `invalid_api_key`               | 不正、期限切れ、無効、上限到達。理由はメッセージ                                                       | ダッシュボードで有効なキーを確認                          |
| `unauthorized`                  | `401` の旧名称。2026-09-29 に `missing_api_key` と `invalid_api_key` に変更              | `invalid_api_key` と同様に扱う                  |
| `forbidden`                     | キーやアカウントで操作不可。無料対象外のモデル、IP 許可リスト、モデルグループなど                                     | メッセージを確認。無料クレジットのアカウントはチャージで全モデルを利用可能     |
| `not_found`                     | 不明なモデル・機能、存在しないリソース、またはキーのアカウントに属さないリソース                                       | ID と所有関係を確認                               |
| `insufficient_credits`          | 残高が 0、または料金に不足                                                                 | 次の有料リクエスト前にチャージ                           |
| `idempotency_conflict`          | 同じ冪等キーを異なる本文で使った                                                               | 同じ論理リクエストのみ再利用、または新しいキー                   |
| `user_concurrency_exceeded`     | アカウントの処理中タスク数が上限                                                               | 完了を待つか同時実行数を増やす                           |
| `rate_limit_exceeded`           | 無料モデルを含むリクエスト数の上限超過                                                            | `Retry-After` / `retry_after_seconds` に従う |
| `content_policy_violation`      | プロンプト、入力メディア、結果が審査で拒否された                                                       | 内容を修正して新しいリクエストを送る                        |
| `processing_unavailable`        | モデルが一時的に利用不可、または容量不足。利用者のレート制限ではない                                             | バックオフして再試行。受け付け済みタスクは確認を続ける               |
| `processing_failed`             | BeatAPI 側の理由で処理失敗                                                              | ポーリング停止。メッセージと返金を確認し、バックオフして再試行           |
| `processing_timeout`            | 処理時間内に完了しなかった                                                                  | 停止して返金を確認。必要なら新しいリクエスト                    |
| `result_transfer_failed`        | 生成結果を BeatAPI のストレージに保存できなかった                                                  | 停止して返金を確認。必要なら再実行                         |
| `invalid_signature`             | Webhook の署名・タイムスタンプを検証できない                                                     | 署名シークレット、生の本文、時刻、署名ヘッダーを確認                |
| `realtime_disabled`             | Realtime がアカウントで無効                                                             | 新しい Session の前にアクセスを有効化                   |
| `realtime_capacity_unavailable` | Realtime の容量が一時不足                                                              | 指定時間待って新しい Session を作る                    |
| `realtime_session_expired`      | Session が利用できない                                                                | 新しい Session とシークレットを作る                    |
| `origin_not_allowed`            | Session に許可されていないブラウザーのオリジン                                                    | 設定済みの正確な HTTPS オリジンを使う                    |
| `invalid_client_secret`         | Realtime シークレットが不正、または利用できない                                                   | 新しい Session のシークレットを使う                    |
| `transport_not_allowed`         | 指定した Realtime の通信方式が未許可                                                        | 文書化された方式を使う                               |
| `internal_error`                | 予期しない内部エラー                                                                     | `request_id` を保存。安全な場合のみ再試行、またはサポートに連絡    |

| HTTP  | コード                                                                                        | `retryable` | クライアントの対処                        |
| ----- | ------------------------------------------------------------------------------------------ | ----------- | -------------------------------- |
| `400` | `bad_request`、`content_policy_violation`                                                   | `false`     | フィールド、組み合わせ、形式、URL、上限、入力を修正      |
| `401` | `missing_api_key`、`invalid_api_key`                                                        | `false`     | Bearer キーを送る、または交換               |
| `402` | `insufficient_credits`                                                                     | `false`     | 次の有料リクエスト前にチャージ                  |
| `403` | `forbidden` または Realtime のオリジンエラー                                                          | `false`     | 権限や正確なオリジンを確認                    |
| `404` | `not_found`                                                                                | `false`     | モデル、reference、ID、所有関係を確認         |
| `409` | `idempotency_conflict`                                                                     | `false`     | 同じ論理リクエストの本文でのみ再利用               |
| `429` | `rate_limit_exceeded`、`user_concurrency_exceeded`                                          | `true`      | `Retry-After` に従うか処理完了を待つ        |
| `500` | `internal_error`                                                                           | `true`      | `request_id` を保存し 1 回再試行。その後サポート |
| `503` | `processing_unavailable`、`processing_timeout`、`processing_failed`、`result_transfer_failed` | `true`      | バックオフして再試行                       |

BeatAPI は `502` と `504` を返しません。見られる場合はネットワークのエッジからの応答で、JSON 本文はなく、`503` と同様に再試行します。

冪等性のルールはエンドポイントによって異なります。

* Realtime Session 作成は `Idempotency-Key` が必須（1–128 文字）です。
* Workflow、Image、Video、Effect タスク作成は任意です。完全に同じ論理リクエストの本文でのみ再利用します。
* Image、Video、Effect のキーは最大 255 文字です。Workflow のキーはデータベース間の互換性のため短くしてください。

## 本番利用のチェックリスト

* 接続先は正確に `https://api.beatapi.io` を指定します。
* 長期利用する API キーは信頼できるサーバーに保存します。
* 選択 API の必須・任意項目、列挙値、上限、条件付きルールを検証します。
* バックグラウンド処理の前にタスク/Session ID と `request_id` を保存します。
* ジッターを付けて確認し、文書化された終了・操作待ち状態で停止します。
* ステータス、`Retry-After`、`retry_after_seconds` に従います。
* JSON 解析前に、生のバイト列で Webhook の署名を検証します。
* クレジットの仮確保、精算、返金、エラー、最終出力 URL を記録します。
* カメラ、顔、声、参照素材を処理する前に[プライバシーポリシー](https://beatapi.io/privacy-policy)と[利用規約](https://beatapi.io/terms-of-service)を確認します。