画像生成 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画像生成モデルの比較では、プロンプト、参照、画角、試行回数を揃える方法を説明しています。

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

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

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