Grok Imagine API：Pipe2 SDKで画像を生成する

Pipe2経由でGrok Imagine APIを使うには、Image Generatorをmodel: 'grok-imagine-image'で実行します。テキストプロンプトを送信し、返された実行IDで状況を確認して、生成された画像を取得します。このガイドではPipe2 APIとその認証を使います。xAI APIへの直接のリクエストは扱いません。

Grokを明示的に指定する

パイプラインのスラッグはimage-generatorです。モデル識別子はinput内に指定します。標準モデルにはgrok-imagine-image、Grok Imagine Qualityにはgrok-imagine-image-qualityを使います。Autoでは別のエンジンが選ばれる可能性があるため、Grokが必要な場合はモデルを固定してください。

この例は標準モデルを使い、参照画像を付けず、quality: 'fast'を指定します。このワークフローを示せる有効なGrok設定のうち、最も低コストな構成です。Fastの出力は1K、autoとhdは2Kです。標準のGrokでは現在、どちらのサイズも画像の基本料金は同じで、fastによる追加の値引きはありません。参照画像には追加料金がかかります。まとめて実行する前に、同じスラッグと入力でEstimatePipelineCostを呼び出してください。

SDKのサンプルを実行する

npm install @pipe2-ai/sdkでパッケージをインストールします。以下をgrok-image.mjsとして保存し、環境変数PIPE2_TOKENにPipe2の個人アクセストークンを設定して、node grok-image.mjsを実行してください。アカウントには十分なクレジットが必要です。トークンはサーバー側で保管します。

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

const token = process.env.PIPE2_TOKEN;
if (!token) throw new Error('Set PIPE2_TOKEN');
const client = createClient(token);
const input = {
  model: 'grok-imagine-image',
  prompt: 'A small red paper boat on a rain-darkened stone step, soft morning light, editorial photograph, no text.',
  quality: 'fast',
  enhance_prompt: false,
};
const { run_pipeline } = await client.RunPipeline({
  pipeline_slug: 'image-generator',
  input,
});

for (let attempt = 0; attempt < 60; attempt++) {
  const { pipeline_runs_by_pk: run } = await client.GetPipelineRun({
    id: run_pipeline.run_id,
  });
  if (!run) throw new Error('Run not found');
  if (run.status === 'failed' || run.status === 'cancelled') {
    throw new Error(run.error_message ?? run.status);
  }
  if (run.status === 'completed') {
    const url = run.assets?.[0]?.url;
    if (!url) throw new Error('Completed run has no image asset');
    console.log(url);
    process.exit(0);
  }
  await new Promise((resolve) => setTimeout(resolve, 3000));
}
throw new Error(`Polling timed out; resume with run ID ${run_pipeline.run_id}`);

対応するパイプラインのリクエストは次のとおりです。

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

このJavaScriptモジュールが使うクライアントについてはTypeScript SDKのドキュメント、公開APIについてはAPIリファレンスを参照してください。

画像が完成するまで実行IDを保持する

RunPipelineが返すのは実行IDであり、完成した画像ではありません。GetPipelineRunで状態と出力ファイルを取得します。この例は失敗やキャンセル時に停止し、完了した実行にファイルがあることを確認して、最初の画像のURLを表示します。確認は3秒間隔で60回までです。これはアプリケーション側の設定であり、生成時間を保証するものではありません。

確認がタイムアウトした場合は、生成を重複して送信せず、同じ実行IDで確認を再開します。開始に成功したら、すぐにIDを保存してください。本番環境ではネットワークエラーも処理し、アプリケーションで必要になる場所に出力ファイルの参照を保存します。

必要な場合にだけ参照画像を追加する

テキストプロンプトだけでも生成できます。Grokの両画像モデルはreference_imagesにJPEGまたはPNGを最大3枚受け付け、1枚あたりの上限は20 MBです。このパイプラインではreference_videosに対応していません。選べる縦横比は1:1、16:9、9:16、4:3、3:4です。この例は既定の正方形を使います。

enhance_prompt: falseを指定すると、テキストのみのリクエストで生成前のプロンプト書き換えを防げます。被写体、背景、構図、光を説明し、使用前に出力を確認してください。構図をさらに詰めるには、Grok Imagineのプロンプトガイドが参考になります。参照画像を追加するときは、それぞれの役割を説明し、変更後のリクエストで料金を再見積もりしてください。