AI動画生成API：TypeScriptでテキストから動画を作る

AI動画生成APIでは、プロンプトから非同期の実行を開始して動画を作ります。Video Generatorを起動し、返された実行IDで状態を確認し、完了した実行のアセットから動画URLを読み取ります。Pipe2のTypeScript SDKはこれらの公開操作を直接提供するため、テキストから動画を作る最初の実装を小さく保てます。

TypeScript SDKでテキストから動画を生成する

@pipe2-ai/sdkをインストールし、Pipe2トークンをPIPE2_TOKENに設定して、このモジュールをNodeで実行します。例では、生成対象を明確な1ショットにするため、観察できる1つの動作と短い時間指定を使っています。

import { createClient } from '@pipe2-ai/sdk';

const input = {
  prompt: '[0-3s] A paper airplane circles above a classroom. [3-6s] It lands beside a notebook. Gentle room ambience, no music.',
};
const client = createClient(process.env.PIPE2_TOKEN);
const { run_pipeline } = await client.RunPipeline({
  pipeline_slug: 'video-generator',
  input,
});

while (true) {
  const { pipeline_runs_by_pk: run } = await client.GetPipelineRun({
    id: run_pipeline.run_id,
  });
  if (run?.status === 'completed') {
    console.log(run.assets?.[0]?.url);
    break;
  }
  if (run?.status === 'failed') throw new Error(run.error_message ?? 'Video generation failed');
  await new Promise((resolve) => setTimeout(resolve, 3000));
}

認証と状態確認を除いた、同じパイプラインリクエストは次のとおりです。

{
  "pipeline_slug": "video-generator",
  "input": {
    "prompt": "[0-3s] A paper airplane circles above a classroom. [3-6s] It lands beside a notebook. Gentle room ambience, no music."
  }
}

TypeScript SDKドキュメントには、インストール、認証、パイプライン実行、状態取得、サブスクリプション、アップロード、クレジット操作がまとめられています。

実行・ポーリング・アセット取得の流れ

RunPipelineには、パイプラインのslugとJSONの入力オブジェクトを渡します。動画生成が終わるまでHTTPリクエストを保持するのではなく、新しい実行の識別子が返ります。GetPipelineRunで使うrun_pipeline.run_idを保存してください。

ポーリングするたびに、最新の実行レコードが返ります。状態がcompletedの実行には生成アセットが含まれ、例では最初のアセットURLを表示します。failedの実行には、利用者への表示やログ記録に使えるエラーメッセージがあります。本番コードでは全体のタイムアウトも設け、実行が見つからない場合は無限に問い合わせずエラーとして扱います。

小さなスクリプトなら数秒ごとのポーリングで十分です。継続的な更新が必要なサービスでは、同じ実行状態を非同期イテラブルとして受け取るWatchPipelineRunも利用できます。

最も単純な有効入力から始める

このリクエストの入力はpromptだけです。これはテキストから動画を作るための最小の実用入力で、モデル選択はAutoのままです。Video Generatorには、開始・終了フレームや、任意の画像・動画・音声参照も渡せます。利用できる長さ、解像度、アスペクト比、参照数の上限は、互換性のあるモデルルートによって異なります。

製品要件で必要になった設定だけを追加してください。配信先に合うアスペクト比、被写体を保つための参照画像、長いクリップに対応する別ルートなどが考えられます。費用やメディア量が増えるリクエストを送る前に、同じpipeline_slugとinputでEstimatePipelineCostを呼び出せます。

1つの生成ショットに合うプロンプトを書く

APIを使っても、正確なショット指示は必要です。画面に見える動作、カメラの動き、環境、時間、音を記述し、指定時間内に物理的に成立する動作に絞ります。

例には2つの時間帯がありますが、出来事は連続しています。紙飛行機が旋回し、その後ノートの横に着地します。場所の切り替え、複数人物、編集カットは求めていません。そのため、動きの連続性、物体の形、着地の瞬間、音を確認しやすくなります。

大きな制作では、ショットごとに生成して確認してから編集します。AI動画の作り方では、このAPI呼び出しの先にある企画、確認、組み立て、字幕、仕上げを解説しています。

認証と失敗を明示的に処理する

Pipe2トークンでクライアントを作成し、トークンはサーバーまたは安全なローカル環境変数に保存します。ブラウザーに配信するソース、リポジトリ、パイプライン入力には含めないでください。

送信時のエラーと実行中の失敗を分けて扱います。未認証、不正な入力、必要なクレジットを予約できない場合は、実行が始まる前に送信が失敗します。正常に作成された実行が後でfailedになることもあるため、error_messageを確認します。アセットURLは状態がcompletedになってから利用してください。

画像から始める場合は、SDKで説明されているアセット手順でアップロードまたは参照し、画像からAI動画を作るガイドで素材の準備と動きの指定を確認できます。