画像生成 APIをTypeScriptから使う方法

画像生成 APIは、プログラムから実行したジョブを通じてプロンプトを画像に変換します。Pipe2では、Image Generatorを開始し、返された実行IDで状態を確認したあと、完了した実行のアセットから画像URLを取得します。以下のTypeScript例は、現行カタログで最も安い有効なモデルと品質の組み合わせを使います。

TypeScript SDKで画像を生成する

@pipe2-ai/sdkをインストールし、Pipe2のパーソナルアクセストークンをPIPE2_TOKENに設定して、このモジュールをNodeで実行します。プロンプトでは被写体、場所、光を一つずつ明確にしているため、最初の結果を評価しやすくなっています。

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

const input = {
  model: 'gpt-image-2',
  prompt: 'A small red paper boat on a rain-darkened stone step, soft morning light, editorial product photograph, no text.',
  quality: 'fast',
};
const client = createClient(process.env.PIPE2_TOKEN);
const { run_pipeline } = await client.RunPipeline({
  pipeline_slug: 'image-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 ?? 'Image generation failed');
  await new Promise((resolve) => setTimeout(resolve, 3000));
}

このプログラム内のパイプラインリクエストは、次の内容と完全に同じです。

{
  "pipeline_slug": "image-generator",
  "input": {
    "model": "gpt-image-2",
    "prompt": "A small red paper boat on a rain-darkened stone step, soft morning light, editorial product photograph, no text.",
    "quality": "fast"
  }
}

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

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

RunPipelineには、パイプラインのスラッグとJSON形式の入力オブジェクトを渡します。画像が完成するまで接続を維持するのではなく、非同期実行の識別子が返ります。run_pipeline.run_idを保存し、GetPipelineRunで最新の状態を取得してください。

ポーリングのループは二つの終了状態を処理します。completedになった実行には生成済みアセットが含まれることがあり、例では先頭のURLを出力します。failedの場合はerror_messageを実行IDと一緒に記録します。本番コードでは全体のタイムアウトも設定し、実行が見つからない場合もエラーとして扱ってください。リアルタイム更新が必要なら、SDKの非同期イテラブルWatchPipelineRunも利用できます。

最も安い有効なリクエストから始める

例ではgpt-image-2を固定し、quality: 'fast'を指定しています。現行のImage Generatorカタログでは最も費用の低い有効な組み合わせで、モデルの低品質生成ティアに対応します。認証、リクエスト形式、ポーリング、アセット処理を確認してから、最終画像により多くのクレジットを使うための設定です。

fastは費用を抑える選択であり、最初の出力がそのまま公開品質になるという保証ではありません。大量に実行する前に、同じpipeline_slugとinputをEstimatePipelineCostへ渡してください。モデル、品質、参照画像の数を変えたときも見積もりをやり直します。実際の料金は有効なカタログが基準です。

必要な画像設定だけを追加する

テキストプロンプトだけで実行できます。必要に応じて、参照画像、対応する参照動画1本、アスペクト比、品質、モデル、プロンプト補強の設定も追加できます。上限は選択したモデルによって異なるため、すべてのエンジンが同じメディアを受け付けると仮定せず、パイプラインのスキーマを確認してください。

テキストだけで生成する場合は、被写体、構図、光、スタイルを短い文章で記述します。画像内に表示したい文字列は引用符で囲み、生成後に必ず校正します。参照画像を使う場合は、それぞれの役割と維持すべき特徴を明示します。共通のアスペクト比は1:1、16:9、9:16、4:3、3:4です。

Autoを使うと、Pipe2が互換性のあるエンジンを選択します。製品が特定の文書化された機能を必要とする場合や、条件を揃えて比較する場合だけモデルを固定しましょう。AI画像生成モデルの比較では、プロンプト、参照、画角、試行回数を揃える方法を説明しています。

Image GeneratorでNano Banana ProのAPIを使う

Pipe2のAPIからNano Banana Proを使うには、同じimage-generatorパイプラインでinput.modelをgemini-3-pro-imageに設定します。Nano Banana Proはカタログ上の名前です。リクエストにはPipe2のモデル識別子を指定してください。SDKのメソッド、実行ID、ポーリング、生成画像の取得は、上の例と同じ流れです。認証にはPipe2のトークンを使います。

結果を比較する場合は、例のプロンプトをそのまま使い、モデルだけを変更します。既存のGPT Image 2とfastの組み合わせは、より低い費用で連携を確認するためのものです。Nano Banana Proを実行する前に、変更後のリクエストをEstimatePipelineCostで見積もってください。このモデルでは、quality: 'fast'で1K、autoまたはhdで2Kの画像を生成します。どちらのサイズも同じ料金帯なので、GPT Image 2とは異なり、fastにしても料金は下がりません。このパイプラインではNano Banana Proの4K出力は利用できません。

テキストプロンプトだけで実行でき、必要に応じてreference_imagesを最大14枚指定できます。各参照画像の役割をプロンプトで説明してください。このモデルにはreference_videosを送らないでください。Image GeneratorのNano Banana Proは動画入力に対応していません。参照画像なしのリクエストで元のプロンプトをそのまま使いたい場合は、enhance_promptをfalseに設定します。狙ったレイアウトにするには各要素の位置を説明し、画像内に表示する正確な文字列を引用符で囲み、生成結果を確認してから使いましょう。

Pipe2経由でGPT Image 2のAPIを使う

上の例は、そのままPipe2のAPIからGPT Image 2を利用できる設定です。pipeline_slug: 'image-generator'、input.model: 'gpt-image-2'、テキストプロンプトを送信し、Pipe2のトークンで認証します。返された実行IDを保存し、同じSDKメソッドで状態を確認して、完了後の画像アセットを取得してください。モデルを選択しても、この流れは変わりません。

品質は、連携確認の例で使っている低品質の設定ならquality: 'fast'、中品質ならauto、高品質ならhdを選びます。これらはPipe2の入力値なので、品質レベルの名前に置き換えず、そのまま送信してください。品質を上げる前に、変更後のリクエストの費用を見積もります。このパイプラインでGPT Image 2に渡せるreference_imagesは最大5枚で、reference_videosには対応していません。参照画像を追加する際は各画像の役割を説明し、特に文字や商品の細部に意図しない変更がないか確認しましょう。

トークン、失敗、出力URLを安全に扱う

SDKクライアントには、実行環境から渡したPipe2トークンを設定します。ソースコードへ直接書いたり、リポジトリへコミットしたり、ブラウザーのログへ出力したりしないでください。リクエストで指定するのはPipe2のパイプラインスラッグであり、モデル提供元のAPIキーを別途送る必要はありません。

ポーリング前に実行IDを保存しておけば、プロセスが再起動しても同じジョブを追跡できます。返されたアセットURLはアプリケーションデータとして扱い、永続的な参照が必要なら保存します。配列の先頭を読む前にアセットの存在を確認し、無限に再試行せずエラーを通知してください。ユーザーのプロンプトや参照メディアには、アプリケーションの認可、モデレーション、保存期間の規則も適用します。