クイックガイド

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

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

1. API キーを作成する

ダッシュボード → API キーで作成し、コマンド履歴に残さずシェルに読み込みます。

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

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

Authorization: Bearer <BEATAPI_API_KEY>

2. タスクを作成する

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

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. 結果をポーリングする

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 を読み、停止します。

API を選ぶ

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

GPT-5.6 の選択、SDK 互換形式、ストリーミング例は GPT-5.6 ガイドを参照してください。

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

GET /v1/tasks/{task_id}

ステータス

共通形式の Task フィールド

利用量と出力

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

POST /v1/files

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

Multipart フィールド

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

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

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

ファイルのレスポンス

{
  "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
  }
}

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

利用量と上限を確認する

GET /v1/usage

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

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

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

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

エラーと再試行方針

{
  "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 なら、内容を変更するまで同じ呼び出しは再び失敗します。

公開エラーコード

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

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 を記録します。
• カメラ、顔、声、参照素材を処理する前にプライバシーポリシーと利用規約を確認します。