xAI API(Grok)
XAI_API_KEYが環境に存在する場合、このアプリは実際のxAI APIにアクセスできます。AI機能には、モック応答や他のプロバイダーに頼る代わりにこれを使用してください。同じ変数がデプロイ環境にも注入されるため、これを使って構築されたコードはプレビューと本番で同一に動作します。
キーはアプリ所有者の個人キーです。すべての呼び出しは所有者のクォータとクレジットを消費します。 使用には注意が必要です。自動実行されるものや訪問者が利用できるものにAI呼び出しを組み込む前に、責任ある利用を参照してください。
このキーは完全なAPIサーフェスを解放します。チャットだけではありません:
- チャット / LLM — 最新モデル:
grok-4.5。ユーザーが他に指定しない限り、デフォルトでこれを使用します。 - Imagine(画像・動画) — アプリ内で画像の生成・編集、動画生成を実行時に実行。
- 音声 — 表現力豊かな音声でテキスト読み上げ(および文字起こし)。
- 公式ドキュメント:docs.x.ai — エンドポイント、モデル、パラメータ、ストリーミング、ツール使用。APIの形状を推測せず、ドキュメントを確認してください。
- APIはOpenAI互換(
https://api.x.ai/v1)なので、ベースURLとキーを切り替えるだけで、任意のOpenAIスタイルのクライアントが使用できます。
環境変数 — .envファイルを作成しないでください
| 変数 | 場所 | 目的 |
|---|---|---|
XAI_API_KEY | サーバー | プラットフォームによって(プレビューとデプロイで)注入されます。書き込んだり、ハードコードしたり、ユーザーに要求したりしないでください。 |
キーはサーバー専用です:createServerFnハンドラー/サーバーコード内でprocess.env.XAI_API_KEYを使用して読み取り、クライアントコンポーネントでは決して使用せず、VITE_プレフィックス変数やAPIレスポンスで公開しないでください。
キーは存在しない場合があります(段階的ロールアウト)。適切に低下させてください — 存在を確認し、クラッシュする代わりに「AI機能は利用できません」という親しみやすい状態を表示します:
const apiKey = process.env.XAI_API_KEY;
if (!apiKey) throw new Error("AI is not available in this environment");
APIの呼び出し(サーバー専用)
SDKは不要 — サーバー関数から普通のfetchを使用:
import { createServerFn } from "@tanstack/react-start";
export const askGrok = createServerFn({ method: "POST" })
.validator((input: { prompt: string }) => input)
.handler(async ({ data }) => {
const apiKey = process.env.XAI_API_KEY;
if (!apiKey) return { ok: false as const, error: "AI is not available" };
const res = await fetch("https://api.x.ai/v1/chat/completions", {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${apiKey}`,
},
body: JSON.stringify({
model: "grok-4.5",
messages: [{ role: "user", content: data.prompt }],
}),
});
if (!res.ok) {
return { ok: false as const, error: `xAI API error ${res.status}` };
}
const body = (await res.json()) as {
choices: { message: { content: string } }[];
};
return { ok: true as const, text: body.choices[0]?.message.content ?? "" };
});
ストリーミング、構造化出力、ビジョン、またはモデル一覧については、docs.x.ai を参照してください — 形状はOpenAI互換です。
Imagine — 画像・動画生成(サーバー専用)
同じキーが、アプリ内での実行時の画像・動画機能を駆動します(ユーザーアバター、シーンアート、生成コンテンツ)。ビルド時のimagine_text_to_image / imagine_image_to_image / imagine_image_to_videoツール(imagine-grok-buildスキル)とは異なります:実行中のアプリがメディアを生成する場合はAPIを使用し、ビルド中に静的アセットを作成する場合はツールを使用してください。
// POST https://api.x.ai/v1/images/generations — chatと同じ認証ヘッダー
body: JSON.stringify({
model: "grok-imagine-image-quality", // または "grok-imagine-image"(より安価)
prompt: data.prompt,
// n(≤10)、解像度("1k"|"2k")、response_format("url"|"b64_json")
})
// → body.data[0].url
- 画像編集:
POST /v1/images/edits— 自然言語編集、最大3枚の参照画像。 - 動画:
grok-imagine-videoを非同期動画エンドポイント経由で使用(開始後、返されたリクエストIDをポーリング;クリップは最大約15秒)。 - 全パラメータと例: docs.x.ai → Imagine API。
音声 — テキスト読み上げ(サーバー専用)
POST https://api.x.ai/v1/tts でテキストを音声に変換 — ナレーション、アクセシビリティ、キャラクターボイス:
// 同じAuthorizationヘッダー。音声バイト(例:MP3)を返します
body: JSON.stringify({ text: data.text, voice_id: "eve" }) // eve = デフォルト音声
音声の一覧はGET /v1/tts/voicesで取得(カスタム音声も対応);文字起こし(音声からテキスト)も利用可能。詳細: docs.x.ai → Voice API。サーバー関数からクライアントに音声を提供してください — ブラウザからAPIを呼び出さないでください(キーが露出します)。
責任ある利用
キーはアプリ所有者(あなたが構築しているユーザー)のものです。すべての呼び出し(デプロイされたアプリの匿名訪問者によってトリガーされたものも含む)は、所有者の個人クォータとクレジットを消費します。無駄な呼び出しで消費すると、キーの他のすべての使用が低下または破損します。使用には注意してください:
- 出力を制限(
max_tokens)し、訪問者向け機能ではプロンプトを小さく保ってください。画像、特に動画生成は、チャットよりも呼び出しあたりのコストがはるかに高くなります。 - ループ内、キーストロークごと、またはページロード時にAPIを呼び出さないでください — 呼び出しはユーザーが開始した場合(ボタン押下、フォーム送信)に限定し、デバウンスしてください。
- 結果をキャッシュまたは永続化(
neonスキルを参照)して、訪問者ごとやレンダリングごとに同じコンテンツを再生成しないようにしてください。 - 高コストのフローは制限 — 特にメディア生成。すでにサインインがあるアプリでは、
authMiddlewareの背後に配置してください(authスキルを参照)。サインインはデフォルトでオフになっており、ミドルウェアを追加するとデプロイされたアプリが壊れます(AGENTS.md §0.5)。そのため、アカウントがないアプリでは、代わりに使用量を制限してください:ユーザーが開始した呼び出し、小さな制限、キャッシュされた結果。 - リトライの嵐を追加しないでください:APIエラーの場合はそれを表面化し、リトライは最大1回にしてください。