Veo 3.1 | BeatAPI API Documentation

POST https://api.beatapi.io/v1/videos/tasks

長さが固定の 8 秒動画を生成します。Quality・Fast・Lite の区分と、720p・1080p・4K の出力を選択できます。テキストとフレーム画像からの生成では、デフォルト値は Quality・720p です。参照画像を使う場合は Fast または Lite が必要です。

対応する生成モード

モード	必須の入力	入力ルール
高品質（Quality）	`model`, `prompt`	`quality=Quality` を指定します。`resolution` は任意で、`720p`・`1080p`・`4k` を選択できます。
高速（Fast）	`model`, `prompt`	`quality=Fast` を指定します。`resolution` は任意で、`720p`・`1080p`・`4k` を選択できます。
軽量（Lite）	`model`, `prompt`	`quality=Lite` を指定します。`resolution` は任意で、`720p`・`1080p`・`4k` を選択できます。
開始・終了フレームを指定	`model`, `prompt`, `images`	開始フレームの URL を 1 個、または開始・終了フレームの順に URL を 2 個指定します。
参照画像を使用	`model`, `prompt`, `reference_images`	URL を 1～3 個指定し、Fast または Lite を使用します。`images` とは併用できません。

非同期処理の流れ： タスクを作成して data.id を保存し、GET /v1/tasks/{task_id} でステータスをポーリングします。succeeded の場合は data.output.media から結果を取得します。failed の場合は data.error_code と data.error_message を確認し、エラーと再試行の方針に従って対処してください。

ローカルファイルを使う場合： 先に入力ファイルをアップロードし、返された data.url を指定してください。

認証

Authorization string 必須

BeatAPI の API キーを Bearer トークンとして送信します。API キーはダッシュボードで作成できます。

Authorization: Bearer <BEATAPI_API_KEY>

通常の API キーは、信頼できるサーバーで管理してください。リクエストボディには Content-Type: application/json が必要です。対応するエンドポイントでは Idempotency-Key は任意ですが、同一のリクエストボディで安全に再試行するために指定を推奨します。

リクエストボディ

model string 必須

veo-3.1 を指定してください。

固定値: veo-3.1

prompt string 必須

動画生成の指示です。

文字数: 1 – 5000 文字

images string[] 任意

開始フレーム 1 枚、または開始・終了フレームの画像を公開 HTTPS URL で指定します。

要素数: 1 – 2 件

aspect_ratio enum<string> 任意

出力動画のアスペクト比です。

選択肢: 16:9, 9:16, auto
デフォルト値: "16:9"

resolution enum<string> 任意

出力動画の解像度です。4k と 4K は同じ意味です。品質と解像度によって料金が変わります。

選択肢: 720p, 1080p, 4k, 4K
デフォルト値: "720p"

quality enum<string> 任意

テキスト・フレーム画像からの生成、または参照画像を使う生成の区分です。

選択肢: Quality, Fast, Lite
デフォルト値: "Quality", "Fast"

watermark string 任意

選択したモデルに渡す、任意の透かし文字列です。

enable_translation boolean 任意

生成前のプロンプト翻訳を許可します。

reference_images string[] モードにより必須

公開 HTTPS 参照画像 URL です。

要素数: 1 – 3 件

リクエスト例

高品質（Quality）

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header 'Authorization: Bearer <BEATAPI_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "veo-3.1",
  "prompt": "A cinematic aerial reveal of a quiet coastal village at sunrise.",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "quality": "Quality"
}'

高速（Fast）

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header 'Authorization: Bearer <BEATAPI_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "veo-3.1",
  "prompt": "A fast cinematic product reveal with natural camera motion.",
  "aspect_ratio": "16:9",
  "resolution": "1080p",
  "quality": "Fast"
}'

軽量（Lite）

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header 'Authorization: Bearer <BEATAPI_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "veo-3.1",
  "prompt": "A concise storyboard-ready product reveal.",
  "aspect_ratio": "16:9",
  "resolution": "4k",
  "quality": "Lite"
}'

開始・終了フレームを指定

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header 'Authorization: Bearer <BEATAPI_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "veo-3.1",
  "prompt": "Move smoothly from the opening portrait to the final product reveal.",
  "images": [
    "https://media.beatapi.io/samples/neon-singer.png",
    "https://media.beatapi.io/samples/smart-bottle.png"
  ],
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "quality": "Quality"
}'

参照画像を使用（Fast）

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header 'Authorization: Bearer <BEATAPI_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "veo-3.1",
  "prompt": "Create a cohesive cinematic scene using the supplied visual references.",
  "reference_images": [
    "https://media.beatapi.io/samples/neon-singer.png",
    "https://media.beatapi.io/samples/smart-bottle.png"
  ],
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "quality": "Fast"
}'

レスポンス

リクエストが成功すると、HTTP 201 が返されます。

{
  "data": {
    "id": "task_8K2qA",
    "object": "task",
    "task_kind": "video",
    "capability_id": "veo-3.1",
    "capability_version": null,
    "media_type": "video",
    "model": "veo-3.1",
    "status": "queued",
    "stage": "queued",
    "created_at": 1782210000,
    "updated_at": 1782210000,
    "completed_at": null,
    "output": null,
    "usage": {
      "credits_reserved": 2.0,
      "credits_charged": 2.0,
      "billable_duration_seconds": 8,
      "credits_settled": 0,
      "credits_refunded": 0
    },
    "request_id": "req_abc123",
    "error_code": null,
    "error_message": null
  }
}

エラー

ステータスコード	意味と対処方法
`400`	JSON の形式が不正、またはフィールド・値・組み合わせが未対応です（`bad_request`。メッセージにフィールド名が記載されます）。入力がコンテンツ審査で拒否された場合は `content_policy_violation` です。修正せずに再試行しても成功しません。
`401`	API キーが未指定（`missing_api_key`）、またはキーが不正・期限切れ・無効・上限到達です（`invalid_api_key`。理由はメッセージに記載されます）。`Authorization: Bearer <key>` で送信してください。`sk-` 接頭辞の有無にかかわらず使えます。そのまま再試行しないでください。
`402`	残高不足です（`insufficient_credits`）。残高がゼロ、またはこのリクエストの料金に足りません。残高をチャージしてから再度送信してください。それまでは再試行しないでください。
`403`	キーまたはアカウントに、この呼び出しの権限がありません（`forbidden`）。例として、無料クレジットでは利用できないモデル（チャージすると利用可能）、キーの IP 許可リスト外からのリクエスト、キーのグループに含まれないモデルがあります。そのまま再試行しないでください。
`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 を返しません。